Skip to content
This repository has been archived by the owner on Jan 3, 2019. It is now read-only.

Latest commit

 

History

History
336 lines (192 loc) · 12.5 KB

README.mkd

File metadata and controls

336 lines (192 loc) · 12.5 KB
Raw

❗ Attention: This project is not maintained anymore. Please head over to the betterDime repository for a maintained version.

forked from phpugl/Dime

DimeErp

An ERP based on Symfony and AngularDart

Build Status codecov Waffle.io - Columns and their card count

General Purpose

The project's purpose is tracking working Expenses Writing Offers and Sending Invoices

An API and open architecture will serve additional purposes:

  • accounting and invoicing (generate invoices, add non-time related items)
  • manage customers (CRM)
  • project management

Installation / Setup for Development

  1. WINDOWS USERS

    • Symfony uses symlinks that seem to break horribly on the windows file system. To circumvent this, sadly you will have to do your work in a virtual machine.
    • Download and install VM Ware Player or VirtualBox.
    • Download an Ubuntu 16.04 ISO
    • Setup your VM

  2. Install Docker and Docker Compose:

  3. Install the Dart SDK through Homebrew or download the binaries on the website.

    https://www.dartlang.org/tools/sdk#install

    brew install dart

  4. Check out the current version with all submodules

    sudo apt update && sudo apt install git               # if you don't have git yet
git clone --recursive git@github.com:stiftungswo/dime

  5. Build your Docker Images:

    docker-compose build

  6. Get dart packages:

    In src/Dime/FrontendBundle/Resources/public: pub get

  7. Start your backend from the dime root directory:

    docker-compose up

  8. Start your frontend form the src/Dime/FrontendBundle/Resources/public directory:

    pub run build_runner serve web:7000

  9. Restore php packages in repository root directory:

    docker exec -it dime composer install docker exec -it dime ./env/install_bundles.sh

  10. Open http://localhost:7000 with your favorite browser

  11. Open http://localhost:8080 for phpmyadmin

    host: mysql user: root no password

  12. Your app WILL crash at some point saying something along the lines of "Out of disk space, 0 bytes written". At this point, you will need to clear the cache:

    docker exec dime rm -rf /dev/shm/dime

Domain

A glossary in german is here.

erm

This ERM excludes some tables that are currently empty/unused. Here is the full ERM.

Project Structure

The Frontend can be found under src/Dime/FrontendBundle/Resources/public with a seperate README for further information.

The Backend files are located in 'src/Dime/' & the relative Bundle folder. Server-Side Routing happens in [Bundle]/Resources/config/routing.yml

Bundles

There are Multiple Bundle Seperated by features:

  • TimetrackerBundle: Base Entities and RestAPI for them
  • OfferBundle: Offer Entities ans RestAPI
  • InvoiceBundle: Invoice Entities and RestAPI
  • PrintingBundle: Service for Printing PDF's
  • FrontendBundle: The Javascript GUI
  • SwoCommonsBundle: Some Entities and Resources used by all our Applications

For understanding the database abstraction, see

TimetrackerBundle/Handler/GenericHandler

API Doc

Check out http://localhost:3000/api/doc when the server is running

Using Docker & docker-compose

You can inspect the logs of Dime and MySQL by:

docker-compose logs -f

Enter the dime docker container as root in interactive mode (bash):

docker exec -it dime bash

Run any command inside the docker container:

docker exec -it dime COMMAND

If you made any changes to the docker config, php config, composer dependencies etc. that are affecting the docker setup, run this command again:

docker-compose build

For more infos visit docker.com

Update

Update to last version

git pull
docker exec -it dime composer self-update
docker exec -it dime composer update -v
docker exec -it dime ./env/install_bundles.sh

If you have any problem remove vendor and install again

docker exec -it dime rm -fR vendor

Update database

docker exec -it dime php app/console doctrine:migrations:migrate

Debugging

In order to debug, you need to install the following things developer machine:

Once you have installed those tools, do the following:

  • Activate the debug-lister in PHPStorm (Phone in the top-right)
  • Browse Dime using chromium and enable the Xdebug helper
    • Alternatively, if testing requests to the API, you will have to copy the request from the Chrome devtools (e.g. as CURL) and run it via command line or something like Postman. Add XDEBUG_SESSION_START as a query parameter, i.e. http://localhost:3000/foobar/?XDEBUG_SESSION_START to start the debugger.

Once a breakpoint is hit, you will be able to inspect the code.

Currently xdebug is configured to work with "docker for mac". For other development environments you might need to adjust the php.ini at .docker/rootfs/usr/local/etc/php/php.ini (see comment).

Run Test

Run tests:

docker exec -it dime ./env/run_tests.sh

Run a single test:

docker exec -it dime ./env/run_tests.sh --filter ActivitiesControllerTest::testGetActivitiesAction

We splitted up the test suite into five parts, so the CI is faster in completing all tests. If you add a new test file or change the content of one tests so it could have a massive performance impact, run the following commands to reflect the changes in the test suites.

env/fixtures/load.sh
bin/phpunit -c app/ --coverage-html test-coverage/ --log-junit junit src/
cd env/
php create_balanced_testsuite.php ../junit

Afterwards, commit the changes. Please note that it can take up to 30 minutes to run the phpunit-command with coverage. If you run it without coverage, the balance won't be accurate. You can also add the manually to one of the testsuites.

Building the Frontend

To build the JS & HTML files for deployment, run these commands:

docker exec -it dime ./env/build_frontend.sh

Database Schema Management

Update Database Schema to the latest version:

docker exec -it dime php app/console doctrine:migrations:migrate

Migrate Database Schema to a specific version:

docker exec -it dime php app/console doctrine:migrations:migrate <version>

Generate new Empty Migration Class:

docker exec -it dime php app/console doctrine:migrations:generate

After changing the ORM schema, sometimes you need to clear the cache before it works:

docker exec -it dime php app/console cache:clear

Regenerate Fixtures as needed (see below)

Recommended schema editing workflow

  • edit the Doctrine-Annotations on the entities
  • generate a new migration with docker exec -it dime php app/console doctrine:migrations:diff
  • you may need to edit the migration by hand
  • regenerate Fixtures as needed (see below)

Fixtures

The fixtures are an example dataset that can be used while developing. But more important: the tests run against this database.

Drop/create database and grant privileges for user dime:

docker exec -it dime ./env/fixtures/flush_db.sh

Load fixtures into the database:

docker exec -it dime ./env/fixtures/load.sh

When the database schema changed, you need to regenerate the fixtures. You can do this with the following command (may take a while):

docker exec -it dime ./env/db_generate_new_fixtures.sh

Then export the changes again and check in the new dime.sql into git

docker exec -it dime ./env/fixtures/export.sh

Logs

To log your symfony code, you can use logger:

use Psr\Log\LoggerInterface;
[...]
$logger = $this->get('logger');
$logger->info('My log');

The log file is in your container, look here:

/dev/shm/dime/log/var/www/html/app/

A good way to read it is

docker exec -it dime less /dev/shm/dime/log/var/www/html/app/test/test.log   #for tests
docker exec -it dime less /dev/shm/dime/log/var/www/html/app/dev/dev.log     #for dev

Formatting

The backend and frontend should always be properly formatted (the Travis build will fail if this is not the case).

Before committing you should always run the code-formatting tools:

Backend

The backend is formatted using phpcbf based on PSR-2.

Run it with composer run format or docker exec dime composer run format.

Frontend

The frontend is formatted using dartfmt (comes installed with the Dart SDK).

Run it with dartfmt -w --line-length 140 src/Dime/FrontendBundle/Resources/public/lib or docker exec dime /usr/lib/dart/bin/dartfmt -w --line-length 140 src/Dime/FrontendBundle/Resources/public/lib.

Deployment

Travis is able to deploy the project per SSH on a webhosting using its deploy skript. The following files need to be present on the target host for this to work:

Sentry

Production errors will be logged to Sentry if a valid SENTRY_DSN is specified. See Backend Config, Frontend Config

The Travis build will usually fill these in.

Deployment at SWO

Please see Documentation in the private Wiki

Sentry

Production errors will be logged to Sentry if a valid SENTRY_DSN is specified. See Backend Config, Frontend Config

The Travis build will usually fill these in.

Deployment at SWO

Please see Documentation in the private Wiki

Known Issues

Using dartlang Plugin with atom

If you use Atom as IDE you'll propably want to benefit from the type safety features of Dart and install the static analyzer plugin dart-atom/dartlang. Before you blame the readme that even after fixing the pub cache things don't work they way they are supposed to, just open the directory src/Dime/FrontendBundle/Resources/public in a new window and start coding.

Using Docker with Docker for Windows/Mac

If you use the new Docker for Windows/Mac Tray thing, you'll have to make sure that this Repository as well as any other mounted volumes in docker-compose.yml are part of the File Sharing Tab of the tool. Else sync will not work.

We recommend using at least 2 CPU's and 4 GB of memory for your docker machine to make everything run smooth.

OSX Workaround if response times are ugly slow

We used to use docker-sync, but recently using osxfs caching has been good enough and is now activated by default. Still slow, but not as bad, and without the hassle of docker-sync suddenly deciding to stop syncing again.

Some alternatives:

http://stackoverflow.com/questions/38168130/docker-on-osx-slow-volumes/42679301#42679301 https://github.com/IFSight/d4m-nfs