Skip to content

README.md

Latest commit

 

History

History
265 lines (182 loc) · 12.3 KB

README.md

File metadata and controls

265 lines (182 loc) · 12.3 KB

Docker Hosted Services

About This Guide

This guide provides instructions for launching a complete, local development of the OneGround ZGW APIs using the provided Docker Compose setup. The goal is to get you up and running quickly so you can explore the entire suite of services.

This setup includes:

  • All core ZGW API services running in Docker containers.
  • HAProxy for routing services to user-friendly local domain names.
  • Keycloak for authentication, pre-configured for the services.
  • Scripts to automatically generate and install a local SSL certificate.

Follow the instructions below to launch the stack, authenticate, and interact with the live APIs.

Prerequisites

Before you begin, ensure you have the following software installed:

Getting Started

1. Clone the Repository

  1. Clone the repository:

    git clone https://github.com/OneGround/ZGW-APIs.git

  2. Open your terminal and navigate into the localdev directory:

    cd ZGW_APIs/localdev

2. Start the ZGW API Services

From the localdev directory, run the following command to start all the required services in the background:

docker compose --env-file ./.env up -d

3. Install the Local SSL Certificate

For your browser to trust the local services, you need to install the generated SSL certificate. After the services start, a new folder named oneground-certificates will appear in your current directory. This folder should contain these files:

  • oneground.local.pem - The public certificate
  • oneground.local.key - The private key
  • oneground.local.combined.pem - A combination of the key and certificate

Note: The generated SSL certificate is valid for 365 days.

Follow the steps for your operating system.

For Windows (using PowerShell)

  1. Open PowerShell as an Administrator.

    • Click the Start menu, type "PowerShell", right-click on "Windows PowerShell", and select "Run as administrator".

  2. Navigate to the certificate installer directory:

    cd ZGW_APIs/tools/oneground-certificates-installer

  3. Run the following command to check your current execution policy:

    Get-ExecutionPolicy -List

  4. To allow the script to run just for this session, execute the following command. This bypasses the policy for the current process only:

    Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

  5. Run the installation script:

    .\install-oneground-certificate.ps1 -RelativeCertPath "..\..\localdev\oneground-certificates\oneground.local.pem"

    The script will import the certificate into the Windows "Trusted Root Certification Authorities" store.

For macOS and Linux (using Bash)

  1. Open your terminal.

  2. Navigate to the certificate installer directory:

    cd ZGW_APIs/tools/oneground-certificates-installer

  3. Make the script executable (you only need to do this once):

    chmod +x ./install-oneground-certificate.sh

  4. Run the installation script. (you may be prompted for your password):

    ./install-oneground-certificate.sh ../../oneground-certificates/oneground.local.pem

    This script installs the certificate into your system's keychain or trust store.

Note: After installing the certificate, we recommend restarting your web browser to ensure the changes take effect.

4. Update Your hosts File

To ensure all services can communicate with each other and are accessible in your browser, you need to map the service hostnames to your local machine. This is a crucial step for the local domain names (e.g., zaken.oneground.local) to work correctly.

  1. Open your hosts file as an administrator.

    • Windows: C:\Windows\System32\drivers\etc\hosts
    • macOS/Linux: /etc/hosts

  2. Add the following lines to the end of the file and save it:

    127.0.0.1 autorisaties.oneground.local
127.0.0.1 besluiten.oneground.local
127.0.0.1 catalogi.oneground.local
127.0.0.1 documenten.oneground.local
127.0.0.1 documentlistener.oneground.local
127.0.0.1 notificaties.oneground.local
127.0.0.1 notificaties-receiver.oneground.local
127.0.0.1 notificatielistener.oneground.local
127.0.0.1 referentielijsten.oneground.local
127.0.0.1 zaken.oneground.local
127.0.0.1 haproxy-tool.oneground.local
127.0.0.1 keycloak-tool.oneground.local
127.0.0.1 rabbitmq-tool.oneground.local

5. Configure API Authentication

To make authorized requests to the APIs, you first need to get a client secret from Keycloak and then use it to request a Bearer token.

Step 5.1: Get the Client Secret from Keycloak

See AUTHENTICATION.md.

Step 5.2: Update Environment File and Restart Services

  1. Return to the ZGW_APIs/localdev directory in your terminal:

    cd ZGW_APIs/localdev

  2. Open the ZGW_APIs/localdev/default.env file in a text editor.

  3. Find the following line and replace the placeholder with the secret you copied from Keycloak:

    ZgwServiceAccounts__Credentials__0__ClientSecret=<oneground-client-secret>

  4. Save the default.env file.

  5. Restart the Docker containers to apply the new configuration:

    docker compose --env-file ./.env up -d

Step 5.3: Request an Access Token

See AUTHENTICATION.md.

6. Configure Data Protection & Encryption

To securely store sensitive personal data in your services, you must configure HMAC hashing and DataProtection encryption.

Step 6.1: Generate Encryption Keys and Certificates

See DATAPROTECTION.md.

Step 6.2: Update Environment File and Restart Services

  1. Return to the ZGW_APIs/localdev directory in your terminal:

    cd ZGW_APIs/localdev

  2. Open the ZGW_APIs/localdev/default.env file in a text editor.

  3. Add the generated HMAC key and DataProtection certificate values as described in the Data Protection guide.

    HmacHasher__HmacKey=<base64-encoded-key-minimum-32-bytes>
DataProtection__Certificate=<base64-encoded-pfx>
DataProtection__CertificatePassword=<pfx-password>

  4. Save the default.env file.

  5. Restart the Docker containers to apply the new configuration:

    docker compose --env-file ./.env up -d

7. Stopping the Services

To stop all running Docker containers, run the following command from the localdev directory:

docker compose down

Service Endpoints and Tools

Here is a reference list of all the services and tools running in this Docker setup.

ZGW API Services/listeners

Service Port Swagger UI Health Check
Autorisaties API 5009 https://autorisaties.oneground.local/swagger https://autorisaties.oneground.local/health
Besluiten API 5013 https://besluiten.oneground.local/swagger https://besluiten.oneground.local/health
Catalogi API 5011 https://catalogi.oneground.local/swagger https://catalogi.oneground.local/health
Documenten API 5007 https://documenten.oneground.local/swagger https://documenten.oneground.local/health
Notificaties API 5015 https://notificaties.oneground.local/swagger https://notificaties.oneground.local/health
Referentielijsten API 5018 https://referentielijsten.oneground.local/swagger https://referentielijsten.oneground.local/health
Zaken API 5005 https://zaken.oneground.local/swagger https://zaken.oneground.local/health
Notificatielistener (message dispatcher) 5098 n/a https://notificatielistener.oneground.local/health
Documentlistener (message dispatcher) 5099 n/a https://documentlistener.oneground.local/health

Hosted Tools

Tool URL Notes
HAProxy Stats https://haproxy-tool.oneground.local/ View statistics for the reverse proxy.
Keycloak https://keycloak-tool.oneground.local/ Identity and Access Management (user: admin, password: admin).
RabbitMQ https://rabbitmq-tool.oneground.local/ Message broker management UI (user: guest, password: guest).
PostgreSQL http://localhost:5432 Database server. Connect with any SQL client.