Skip to content

Latest commit

 

History

History
365 lines (233 loc) · 9.79 KB

INSTALL.rst

File metadata and controls

365 lines (233 loc) · 9.79 KB
Raw

Installation

This installation is meant for developers of Open Inwoner Platform. 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:

You will also need the Libxml2 and GDAL development libraries. For Linux (Debian) they are following:

  • libxml2-dev
  • libxmlsec1-dev
  • libxmlsec1-openssl
  • libgdal-dev
  • gdal-bin

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]:maykinmedia/open-inwoner.git
cd open-inwoner

  3. Install all required (backend) libraries. Tip: You can use the bootstrap.py script to install the requirements and set the proper settings in manage.py. Or, perform the steps manually:

    virtualenv env
source env/bin/activate
pip install -r requirements/dev.txt

  4. Run third-party install commands:

    • Install the required browsers for Playwright end-to-end testing.
    playwright install

  1. Install and build the frontend libraries:

    npm install
npm run build
    • Or as an alternative:
    npm ci --legacy-peer-deps
npm run build

  2. Create the statics and database:

    python src/manage.py collectstatic --link
python src/manage.py migrate

  3. Create a superuser to access the management interface:

    python src/manage.py createsuperuser

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

    python src/manage.py runserver

  5. Create a .env file with database settings. See dotenv.example for an example.

    cp dotenv.example .env

Note: If you are making local, machine specific, changes, add them to src/open_inwoner/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 npm run watch.

Note: The project makes use of the open-inwoner-design-tokens package , a node module which contains the values for the project's design tokens from the NL Design System.

ElasticSearch

  1. To start ElasticSearch, run the following command:

    bin/start_elasticsearch.sh

  2. Then build the indices:

    src/manage.py search_index --rebuild

Update installation

When updating an existing installation:

  1. Activate the virtual environment:

    cd open-inwoner
source env/bin/activate

  2. Update the code and libraries:

    git pull
pip install -r requirements/dev.txt
npm install
or as an alternative: npm ci --legacy-peer-deps
npm run build

  3. Update the statics and database:

    python src/manage.py collectstatic --link
python src/manage.py migrate

  4. Update the ElasticSearch indices:

    src/manage.py search_index --rebuild

Testsuite

To run the test suite:

python src/manage.py test open_inwoner

Configuration via environment variables

A number of common settings/configurations can be modified by setting environment variables. You can persist these in your local.py settings file or as part of the (post)activate of your virtualenv.

  • SECRET_KEY: the secret key to use. A default is set in dev.py
  • DIGID_MOCK: determines if a mock-DigiD interface is to be shown on the frontend, if configured in the admin this has to be set to True to avoid switching to the mock-authentication by accident.
  • EHERKENNING_MOCK: determines if a mock-eHerkenning interface is to be shown on the frontend, if configured in the admin this has to be set to True to avoid switching to the mock-authentication by accident.
  • DB_NAME: name of the database for the project. Defaults to open_inwoner.
  • DB_USER: username to connect to the database with. Defaults to open_inwoner.
  • DB_PASSWORD: password to use to connect to the database. Defaults to open_inwoner.
  • DB_HOST: database host. Defaults to localhost
  • DB_PORT: database port. Defaults to 5432.
  • SENTRY_DSN: the DSN of the project in Sentry. If set, enabled Sentry SDK as logger and will send errors/logging to Sentry. If unset, Sentry SDK will be disabled.
  • TWO_FACTOR_FORCE_OTP_ADMIN: Enforce 2 Factor Authentication in the admin or not. Defaults to True.
  • TWO_FACTOR_PATCH_ADMIN: Whether to use the 2 Factor Authentication login flow for the admin or not. Defaults to True.

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 open-inwoner:

    git clone [email protected]:maykinmedia/open-inwoner.git
Cloning into 'open-inwoner'...
...

cd open-inwoner

  2. Start the database and web services:

    docker-compose up -d
Starting open-inwoner_db_1 ... done
Starting open-inwoner_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 open-inwoner_web_1

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

    docker exec -it open-inwoner_web_1 /app/src/manage.py createsuperuser
E-mail address: [email protected]
...
Superuser created successfully.

  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/open_inwoner/conf/docker.py for all settings.

docker build -t open_inwoner
docker run \
    -p 8000:8000 \
    -e DATABASE_USERNAME=... \
    -e DATABASE_PASSWORD=... \
    -e DATABASE_HOST=... \
    --name open_inwoner \
    open_inwoner

docker exec -it open_inwoner /app/src/manage.py createsuperuser

Staging and production

Ansible is used to deploy test, staging and production servers. It is assumed the target machine has a clean Debian installation.

  1. Make sure you have Ansible installed (globally or in the virtual environment):

    pip install ansible

  2. Navigate to the project directory, and install the Maykin deployment submodule if you haven't already:

    git submodule update --init

  3. Run the Ansible playbook to provision a clean Debian machine:

    cd deployment
ansible-playbook <test/staging/production>.yml

For more information, see the README file in the deployment directory.

Settings

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

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.