README.md

OneGround ZGW APIs: Docker Compose Setup

• OneGround ZGW APIs: Docker Compose Setup
  • About This Guide
  • Prerequisites
  • Getting Started
    • 1. Download the Repository
    • 2. Start the ZGW API Services
    • 3. Install the Local SSL Certificate
      • For Windows (using PowerShell)
      • For macOS and Linux (using Bash)
    • 4. Update Your hosts File
    • 5. Configure API Authentication
      • Step 5.1: Get the Client Secret from Keycloak
      • Step 5.2: Update Environment File and Restart Services
      • Step 5.3: Request an Access Token
      • Step 5.4: Creating a Sample Case Using Postman
    • 6. Stopping the Services
  • Service Endpoints and Tools
    • ZGW API Services/Listeners
    • Hosted Tools
  • License

About This Guide

This guide provides instructions for launching a complete, local demonstration 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:

• Docker Engine (Desktop or Server)
• Docker Compose (This is often included with Docker Desktop)

Getting Started

1. Download the Repository

1. Download the repository as a ZIP file by opening this URL: https://github.com/OneGround/ZGW-APIs/archive/refs/heads/main.zip

2. Unzip the downloaded file. This will create a folder named ZGW-APIs-main.

3. Open your terminal and navigate into the docker-compose directory:

   cd ZGW-APIs-main/getting-started/docker-compose

2. Start the ZGW API Services

From the docker-compose 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-main/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 "..\..\getting-started\docker-compose\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-main/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 ../../getting-started/docker-compose/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-main/getting-started/docker-compose directory in your terminal:

   cd ZGW-APIs-main/getting-started/docker-compose

2. Open the ZGW-APIs-main/getting-started/docker-compose/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.

Step 5.4: Creating a Sample Case Using Postman

You can quickly use the Zaken API by creating a sample case ("zaak") using Postman and the provided Create Case Postman collection.

Steps:

1. Import the Create Case collection and environment

   • Open Postman;
   • Go to the Collections tab. Import ZGW Create Case.postman_collection.json;
   • Go to the Environments tab. Import ZGW Create Case.environment.json.

2. Obtain an Access Token

   • Follow the instructions in the "Configure API Authentication" section above to get a valid access token.
   • Paste the token into the jwt_token variable in your Postman Create Case Environment.

3. Set Up Other Environment Variables

   • Update the variables for your local setup if they deviate from standard set up, such as zrc_url.

4. Create a Sample Case

   • In the imported collection ZGW Create Case, find the folder named Casetype. Click 'run' and 'Run ZGW Create Case'. The catalog will be created, a case and other types will be added.
   • Find the folder named Case. Click 'run' and 'Run ZGW Create Case'. The case with related entities (status, result, document) will be added. If you need more cases run it multiple times.

For more details and advanced scenarios, see the documentation in the Postman collection.

6. Stopping the Services

To stop all running Docker containers, run the following command from the docker-compose 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.

License

This project is licensed under the BSD 3-Clause License.