Setting Up the Local Environment

This guide walks you through setting up the local development environment for Open Beheer, which consists of a Django backend and a React (Vite) frontend.

Prerequisites

Make sure the following tools are installed:

Python – check the Dockerfile for the required version.
uv.
Python Virtualenv and Pip
PostgreSQL
Node.js
npm – check the frontend/.nvmrc file for the required version.
Redis

Database Setup (PostgreSQL)

Create the openbeheer role and database:

sudo -u postgres psql

Inside the PostgreSQL shell (openbeheer is the user/password/database name used by default by the development server):

CREATE ROLE openbeheer WITH LOGIN PASSWORD 'openbeheer';
ALTER ROLE openbeheer CREATEDB;
CREATE DATABASE openbeheer OWNER openbeheer;

You can adjust the password or database name as needed, but make sure it matches your backend’s .env.

Clone the Repository

Start by cloning the repository:

git clone git@bitbucket.org:maykinmedia/openbeheer.git
cd openbeheer

Backend Setup (Django)

Navigate to the backend directory:
```
cd backend
```

Create and activate a virtual environment:

python -m venv env
source env/bin/activate

Install Python dependencies:
```
uv pip install -r requirements/dev.txt
```
Create a `.env` file and configure environment variables. See Environment Variables for details.

You can use the provided example as a starting point:
```
cp dotenv.dev.example .env
```
Apply migrations:
```
src/manage.py migrate
```
Create a superuser (optional, but recommended):
```
src/manage.py createsuperuser
```

Run the development server:
```
src/manage.py runserver
```

Automatic configuration

For development, you can configure the backend to use the external applications provided as docker compose by using the following setup-configuration file:

#
# ** Django setup configuration fixture **
#
# Can be used FOR DEVELOPMENT to configure the application with the docker services provided 
# in the folder /backend/docker-services.

oidc_db_config_enable: true
oidc_db_config_admin_auth:
  providers:
  - identifier: admin-oidc-provider
    oidc_use_nonce: true
    oidc_nonce_size: 32
    oidc_state_size: 32
    endpoint_config:
      oidc_op_discovery_endpoint: "http://localhost:28080/realms/openbeheer-dev/"
  items:
  - identifier: admin-oidc
    enabled: true
    oidc_rp_client_id: openbeheer-dev
    oidc_rp_client_secret: oCwSJtZVdHW6BzCFIxKnIg16nLL0x4zK
    oidc_rp_scopes_list:
    - openid
    - email
    - profile
    oidc_rp_sign_algo: RS256
    oidc_provider_identifier: admin-oidc-provider
    userinfo_claims_source: id_token
    options:
      user_settings:
        claim_mappings:
          username:
            - sub
          first_name:
            - given_name
          last_name:
            - family_name
          email:
            - email
        username_case_sensitive: true
      groups_settings:
        claim_mapping:
          - roles
        sync: true
        sync_pattern: '*'
        default_groups: []
        make_users_staff: true
        superuser_group_names:
          - Superuser

zgw_consumers_config_enable: true
zgw_consumers:
  services:
  - identifier: objecttypen-service
    label: Objecttypen API
    api_root: http://localhost:8004/api/v2/
    api_type: orc
    auth_type: api_key
    header_key: Authorization
    header_value: Token 18b2b74ef994314b84021d47b9422e82b685d82f
  - identifier: catalogi-service
    label: Open Zaak - Catalogi API
    api_root: http://localhost:8003/catalogi/api/v1/
    api_type: ztc
    auth_type: zgw
    client_id: test-vcr
    secret: test-vcr
  - identifier: selectielijst-service
    label: Open Zaak (public) - Selectielijst API
    api_root: https://selectielijst.openzaak.nl/api/v1/
    api_type: orc
    auth_type: no_auth

api_configuration_enabled: true
api_configuration:
  selectielijst_service_identifier: selectielijst-service
  objecttypen_service_identifier: objecttypen-service

This can be loaded by doing (from the backend folder):

src/manage.py setup_configuration --yaml-file src/openbeheer/config/setup_configuration/fixtures/data.yaml

Frontend Setup (React)

Navigate to the frontend directory:
```
cd ../frontend
```
Install frontend dependencies:
```
npm install
```
Create a `.env` file and configure environment variables. See Environment Variables for details.

You can use the provided example as a starting point:
```
cp .env.example .env
```
Start the frontend development server:
```
npm run dev
```

This will usually be available at http://localhost:5173/. The Django backend runs at http://localhost:8000/ by default.

Next Steps

Refer to Environment Variables for a complete breakdown of required configuration.

Running end-to-end tests

The E2E tests use pytest instead of the Django test framework (based on unittest). They make use of the libraries pytest-django and pytest-playwright.

We currently use the sync interface of Playwright, which is a wrapper around the async API that abstracts asyncio usage. Since under the hood Playwright remains asynchronous, it needs to be run with the environment variable DJANGO_ALLOW_ASYNC_UNSAFE=yes (see this issue for more details).

To run the tests locally, you first need to build the frontend. This can be done with the script backend/bin/setup_e2e.sh. This will build the frontend with the environment variable MYKN_API_URL="" and then symlink the index.html and the javascript/css assets into the templates and the static folders of the backend respectively. You can skip the building step with the environment variable SKIP_BUILD=yes.

Then, set the environment variable E2E_TESTS=yes. This will tell the backend to use the index.html as the template on the root page instead of the master.html.

Finally, run the e2e tests from the backend/ folder with (possible browsers are firefox|chromium|webkit):

pytest -k e2e --headed --browser=firefox src/

TL;DR

From backend/, run ./bin/setup_e2e.sh.
Set environment variables E2E_TESTS=yes and DJANGO_ALLOW_ASYNC_UNSAFE=yes.
Run tests from backend/ with pytest -k e2e --headed --browser=firefox src/.

Adding tests

Make sure that the tests are decorated with @pytest.mark.e2e:

import pytest

@pytest.mark.e2e
def test_some_feature(page, runner):
   ...

This marker is used to discover all the E2E tests.