Environment Setup

Prerequisites

You need the following libraries and/or programs:

Python 3.12 or above
Python Virtualenv and Pip
PostgreSQL 10 or above with PostGIS extension
Node.js 24.12
npm
Elastic Search 7.9.2 or above

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.

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

Get the code:

git clone git@github.com:maykinmedia/open-inwoner.git
cd open-inwoner
# initialize submodules
git submodule update --init --recursive

This will include the Open-Inwoner-Design-Tokens subdirectory. When all is built and run this is where the OIP design tokens CSS will be generated. When this repository gets updated, it needs to be pulled again.

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
```
Run third-party install commands:
- Install the required browsers for Playwright end-to-end testing.
```
playwright install
```

Install and build the frontend libraries:
```
npm install
npm run build
```

Create the statics and database:

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

Create a superuser to access the management interface:
```
python src/manage.py createsuperuser
```
You can now run your installation and point your browser to the address given by this command:
```
python src/manage.py runserver
```
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.

ElasticSearch

To start ElasticSearch, run the following command:
```
bin/start_elasticsearch.sh
```
Then build the indices:
```
src/manage.py search_index --rebuild
```

Update installation

When updating an existing installation:

Activate the virtual environment:

cd open-inwoner
source env/bin/activate

Update the code and libraries:

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

Update the statics and database:

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

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.