How to Set Up a Local Test Environment Using Docker Compose?

Owned by Petteri Kivimäki, created
Last updated: Feb 21, 2024
4 min read

The easiest way to set up a local X-Road test environment is to use Docker Compose. The local test environment consists of four containers:

  • Container 1 (cs)

    • Central Server

    • Test CA with OCSP and TSA

  • Container 2 (ss1)

    • Management Security Server

  • Container 3 (ss2)

    • Security Server

    • Is used as a service consumer

  • Container 4 (ss3)

    • Security Server

    • Is used as a service provider.

Each container has three volumes where the container’s configuration is persisted. This makes it possible to destroy and recreate the containers without loosing the environment’s configuration.

 Run the containers

Create the test environment by following these steps:

The Central Server Docker image is for test and development purposes only and therefore, the username and password for the management UI are not configurable using environmental variables. The default values are:

Username: xrd

Password: secret

The management UI users can be managed by connecting to a running Central Server container and following the instructions in the Central Server User Guide.

  1. Create a Docker Compose file (docker-compose.yml) with the following configuration:

    1. version: '3.5' services: cs: image: niis/xroad-central-server:jammy-7.4.0 container_name: cs environment: XROAD_TOKEN_PIN: 1234 ports: - 4000:4000 - 8888:8888 volumes: - cs-db-volume:/var/lib/postgresql/14/main - cs-conf-volume:/etc/xroad - cs-test-ca-volume:/home/ca networks: - xroad-network ss1: image: niis/xroad-security-server-sidecar:7.4.0 container_name: ss1 ports: - 1000:4000 - 1080:8080 - 1443:8443 environment: XROAD_TOKEN_PIN: 1234 XROAD_ADMIN_USER: xrd XROAD_ADMIN_PASSWORD: secret XROAD_LOG_LEVEL: INFO volumes: - ss1-db-volume:/var/lib/postgresql/12/main - ss1-conf-volume:/etc/xroad - ss1-archive-volume:/var/lib/xroad networks: - xroad-network depends_on: - cs ss2: image: niis/xroad-security-server-sidecar:7.4.0 container_name: ss2 ports: - 2000:4000 - 2080:8080 - 2443:8443 environment: XROAD_TOKEN_PIN: 1234 XROAD_ADMIN_USER: xrd XROAD_ADMIN_PASSWORD: secret XROAD_LOG_LEVEL: INFO volumes: - ss2-db-volume:/var/lib/postgresql/12/main - ss2-conf-volume:/etc/xroad - ss2-archive-volume:/var/lib/xroad networks: - xroad-network depends_on: - cs ss3: image: niis/xroad-security-server-sidecar:7.4.0 container_name: ss3 ports: - 3000:4000 - 3080:8080 - 3443:8443 environment: XROAD_TOKEN_PIN: 1234 XROAD_ADMIN_USER: xrd XROAD_ADMIN_PASSWORD: secret XROAD_LOG_LEVEL: INFO volumes: - ss3-db-volume:/var/lib/postgresql/12/main - ss3-conf-volume:/etc/xroad - ss3-archive-volume:/var/lib/xroad networks: - xroad-network depends_on: - cs volumes: cs-db-volume: name: cs-db-data cs-conf-volume: name: cs-conf-data cs-test-ca-volume: name: cs-test-ca-data ss1-db-volume: name: ss1-db-data ss1-conf-volume: name: ss1-conf-data ss1-archive-volume: name: ss1-archive-data ss2-db-volume: name: ss2-db-data ss2-conf-volume: name: ss2-conf-data ss2-archive-volume: name: ss2-archive-data ss3-db-volume: name: ss3-db-data ss3-conf-volume: name: ss3-conf-data ss3-archive-volume: name: ss3-archive-data networks: xroad-network: name: xroad-network driver: bridge

  2. Start the environment (docker compose up -d).

  3. View the logs (docker compose logs -f or docker logs -f <container-name>).

Configuration

The environment must be configured following the instructions available here. Please use the following configuration values during the configuration process:

  • Step 1.1.

    • The Central Server address is cs.

  • Step 1.3

    • The CA root certificate (ca.cert.pem) and OCSP certificate (ocsp.cert.pem) are located in the /home/ca/CA/certs directory of the cs container.

    • When adding an OCSP responder, the OCSP responder URL is http://cs:8888.

  • Step 1.4

    • The TSA certificate (tsa.cert.pem) is located in the /home/ca/CA/certs directory of the cs container.

    • When adding a time-stamping service, the time-stamping service URL is http://cs:8899.

  • Step 3.6

    • When registering the Security Server authentication certificate, the Security Server DNS name is ss1 for ss1, ss2 for ss2 and ss3 for ss3.

The UIs of different components are available at:

  • Central Server (cs): https://localhost:4000

  • Test CA (cs): https://localhost:8888/testca/

  • Security Server 1 (ss1): https://localhost:1000

  • Security Server 2 (ss2): https://localhost:2000

  • Security Server 3 (ss3): https://localhost:3000.

Please note that accessing the UIs of different components at the same time using the same browser causes problems with the login session. The user gets constantly logged out and therefore, it’s recommended to use different browsers to access the UIs simultaneously.

Testing the environment

Instructions for testing that the environment is working as expected after completing the configuration are available here.

The Security Server 1 (ss1) request interface is available on ports 1080 / 1443, the Security Server 2 (ss2) request interface is available on ports 2080 / 2443 and the Security Server 3 (ss3) request interface is available on ports 3080 / 3443.

Adding your own services

More information about adding new services to the Security Server is available here. The services should be added to the Security Server 3 (ss3) while the Security Server 2 (ss2) is used as a service consumer. However, also the opposite configuration can be used.

Before invoking a service, please check the client subsystem’s Connection Type and update the configuration if needed:

https://docs.x-road.global/Manuals/ug-ss_x-road_6_security_server_user_guide.html#91-communication-with-service-consumer-information-systems

Incorrect Connection Type configuration causes an error message to be returned.

The Security Server 2 (ss2) request interface for client information systems is available on ports 2080 / 2443 and the Security Server 3 (ss3) request interface for client information systems is available on ports 3080 / 3443.