Installation instructions

1. Install dependency wkhtmltopdf and poppler-utils (for pdfunite)

2. Clone the git repository

3. Create a virtualenv to run it with:

   $ python3 -m venv ve
   

4. Install the dependencies in the virtualenv:

   $ ve/bin/python -m pip install -r requirements.txt
   

5. Create a localsettings.py:

   $ cp src/debian_reimbursements/localsettings.py.sample \
        src/debian_reimbursements/localsettings.py
   

6. Configure critical settings in localsettings.py:

   1. Enable DEBUG if doing local development.

   2. Your database (DATABASES).

   3. Your vhost name (ALLOWED_HOSTS).

   4. Your site identity (SITE_NAME, SITE_URL).

   5. Generate a new random string for a secret key (SECRET_KEY).

   6. Outbound email (EMAIL_HOST`, `DEFAULT_FROM_EMAIL).

   7. Receipts storage (RECEIPTS_PATH). Make sure this is writeable by the web-server.

   8. Workflow defaults (DEFAULT_CURRENCY, DEFAULT_PAYER, DEFAULT_APPROVER).

7. Create the database:

   $ ve/bin/python src/manage.py migrate
   

8. Create the standard groups:

   $ ve/bin/python src/manage.py loaddata fixtures/groups.json
   

9. Create the standard expense types:

   $ ve/bin/python src/manage.py loaddata fixtures/standard_types.json
   

10. Import a set of historical exchange rates:

    $ ve/bin/python src/manage.py import_ecb_exchangerates --historical
    

11. Check the installation:

    $ ve/bin/python src/manage.py check --deploy
    

12. Create an initial superuser:

    $ ve/bin/python src/manage.py createsuperuser
    

13. In development: Run the development web server:

    $ ve/bin/python src/manage.py runserver
    

14. In production: Setup automatic exchange rate updates with systemd, using reimbursements-update-ecb-exchange.timer or reimbursements-update-oxr-exchange.timer:

    1. Copy the appropriate .timer and .service file from docs/examples to /etc/systemd/system/.

    2. Edit the paths in the .service file to point to your installation. Select the correct user to run the update.

    3. Tell systemd to read the files:

       # systemctl daemon-reload
       

    4. Enable the sytemd unit:

       # systemctl enable reimbursements-update-OPTION-exchange.timer
       

    5. Do the initial run:

       # systemctl start reimbursements-update-OPTION-exchange.timer
       

    6. Verify that it ran correctly:

       # journalctl log --unit=reimbursements-update-OPTION-exchange.service --since='1hr ago'
       

Open Exchange Rates

The ECB exchange rate database only has a limited set of currencies in it. Open exchange rates offers more data for free, but requires an API key.

1. Sign up and generate an app ID.

2. Configure it in localsettings.py as OPEN_EXCHANGE_RATES_APP_ID.

3. Import exchange rates:

   $ ve/bin/python src/manage.py import_openexchangerates --since=2023-01-01