INSTALL.rst

Installation

The project is developed in Python using the Django framework. There are 3 sections below, focussing on developers, running the project using Docker and hints for running the project in production.

Development

Prerequisites

You need the following libraries and/or programs:

• Python 3.6 or above
• Python Virtualenv and Pip
• PostgreSQL 9.6 or above
• Node.js
• npm

Getting started

Developers can follow the following steps to set up the project on their local development machine.

1. Navigate to the location where you want to place your project.

2. Get the code:

   $ git clone [email protected]:VNG-Realisatie/klanten-api klanten
   $ cd klanten

3. Install all required libraries.

   $ pip install -r requirements/dev.txt

4. Install the front-end CLI tool gulp if you've never installed them before and install the frontend libraries:

   $ npm install -g gulp
   $ npm install
   $ gulp sass

5. Activate your virtual environment and create the database:

   $ source env/bin/activate
   $ python src/manage.py migrate

6. Create a superuser to access the management interface:

   $ python src/manage.py createsuperuser

7. You can now run your installation and point your browser to the address given by this command:

   $ python src/manage.py runserver

Note: If you are making local, machine specific, changes, add them to src/klanten/conf/local.py. You can base this file on the example file included in the same directory.

Note: You can run watch-tasks to compile Sass to CSS and ECMA to JS using gulp. By default this will compile the files if they change.

Update installation

When updating an existing installation:

1. Activate the virtual environment:

   $ cd klanten
   $ source env/bin/activate

2. Update the code and libraries:

   $ git pull
   $ pip install -r requirements/dev.txt
   $ npm install
   $ gulp build

3. Update the database:

   $ python src/manage.py migrate

Testsuite

To run the test suite:

$ python src/manage.py test klanten

Docker

The easiest way to get the project started is by using Docker Compose.

1. Clone or download the code from Github in a folder like klanten:

   $ git clone [email protected]:VNG-Realisatie/klanten-api klanten
   Cloning into 'klanten'...
   ...
   
   $ cd klanten

2. Start the database and web services:

   $ docker-compose up -d
   Starting klanten_db_1 ... done
   Starting klanten_web_1 ... done

   It can take a while before everything is done. Even after starting the web container, the database might still be migrating. You can always check the status with:

   $ docker logs -f klanten_web_1

3. Create an admin user and load initial data. If different container names are shown above, use the container name ending with _web_1:

   $ docker exec -it klanten_web_1 /app/src/manage.py createsuperuser
   Username: admin
   ...
   Superuser created successfully.
   
   $ docker exec -it klanten_web_1 /app/src/manage.py loaddata admin_index groups
   Installed 5 object(s) from 2 fixture(s)

4. Point your browser to http://localhost:8000/ to access the project's management interface with the credentials used in step 3.

   If you are using Docker Machine, you need to point your browser to the Docker VM IP address. You can get the IP address by doing docker-machine ls and point your browser to http://<ip>:8000/ instead (where the <ip> is shown below the URL column):

   $ docker-machine ls
   NAME      ACTIVE   DRIVER       STATE     URL
   default   *        virtualbox   Running   tcp://<ip>:<port>

5. To shutdown the services, use docker-compose down and to clean up your system you can run docker system prune.

More Docker

If you just want to run the project as a Docker container and connect to an external database, you can build and run the Dockerfile and pass several environment variables. See src/klanten/conf/docker.py for all settings.

$ docker build . && docker run \
    -p 8000:8000 \
    -e DJANGO_SETTINGS_MODULE=klanten.conf.docker \
    -e DATABASE_USERNAME=... \
    -e DATABASE_PASSWORD=... \
    -e DATABASE_HOST=... \
    --name klanten

$ docker exec -it klanten /app/src/manage.py createsuperuser

Settings

All settings for the project can be found in src/klanten/conf. The file local.py overwrites settings from the base configuration.

Generating the API spec

Installation of zds-schema makes the binary generate_schema available, which gnerates the src/openapi.yaml using drf-yasg.

Make sure you have installed the npm dependencies before using this.

Commands

Commands can be executed using:

$ python src/manage.py <command>

There are no specific commands for the project. See Django framework commands for all default commands, or type python src/manage.py --help.