How to Set Up a Local Test Environment Using Docker Compose?
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.
Create a Docker Compose file (
docker-compose.yml
) with the following configuration:services: cs: image: niis/xroad-central-server:jammy-7.4.2 container_name: cs environment: XROAD_TOKEN_PIN: 123456xrd! 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.2 container_name: ss1 ports: - 1000:4000 - 1080:8080 - 1443:8443 environment: XROAD_TOKEN_PIN: 123456xrd! 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.2 container_name: ss2 ports: - 2000:4000 - 2080:8080 - 2443:8443 environment: XROAD_TOKEN_PIN: 123456xrd! 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.2 container_name: ss3 ports: - 3000:4000 - 3080:8080 - 3443:8443 environment: XROAD_TOKEN_PIN: 123456xrd! 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
Start the environment (
docker compose up -d
).View the logs (
docker compose logs -f
ordocker 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 thecs
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 thecs
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
forss1
,ss2
forss2
andss3
forss3
.
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:
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
.