TrustDeck – Startup & Setup (Dev + Prod)¶

This document covers only what you need to configure and start the service in:

Dev mode (Postgres + Keycloak in Docker, backend via Maven)
Prod-like mode (Postgres + Keycloak + backend all in Docker)

Prerequisites¶

Docker + Docker Compose
Java + Maven (needed for dev mode and for building the JAR before prod-like backend image)

Common setup (required for both dev + prod)¶

1) Clone the repository¶

git clone https://github.com/TrustDeck/ace.git

2) Create `trustdeck.env` in the repo root¶

The startup script expects a file named trustdeck.env next to trustdeck.sh.

cp trustdeck.env.template trustdeck.env
# or:
cp trustdeck.env.example trustdeck.env

3) Edit `trustdeck.env`¶

Fill in the variables needed for:

PostgreSQL (TrustDeck database):
- Needed for stroing data from/for the application in the database
- DATABASE_TRUSTDECK_HOST
- DATABASE_TRUSTDECK_PORT
- DATABASE_TRUSTDECK_USER
- DATABASE_TRUSTDECK_PASSWORD
PostgreSQL (Keycloak database):
- Needed for initializing Keycloak during the docker startup phase
- DATABASE_KEYCLOAK_USER
- DATABASE_KEYCLOAK_PASSWORD
Keycloak settings used by the backend:
- Used for communication between the application and Keycloak
- KEYCLOAK_SERVER_URI
- KEYCLOAK_REALM_NAME
- KEYCLOAK_CLIENT_ID
- KEYCLOAK_CLIENT_SECRET
- KEYCLOAK_HOSTNAME
- KEYCLOAK_RELATIVE_PATH
Keycloak users:
- Needed for caching of group paths from the application:
  - KEYCLOAK_CACHE_ADMIN_USER
  - KEYCLOAK_CACHE_ADMIN_PASSWORD
- Admin account that will be created during initializing Keycloak and is used for communication between the application and Keycloak
  - KEYCLOAK_ADMIN_USER
  - KEYCLOAK_ADMIN_PASSWORD
Logging levels:
- For more or less information about what's going on
- KEYCLOAK_LOG_LEVEL=INFO (preset to INFO-level)
- TRUSTDECK_LOG_LEVEL=INFO (preset to INFO-level)

Tip

Start with trustdeck.env.example, but change secrets/passwords for anything beyond local dev.

A) Dev mode (Docker infrastructure + Maven-run backend)¶

What “dev mode” does¶

Starts Postgres + Keycloak using the dev compose file
Waits for them to become healthy
Exports variables from trustdeck.env
Runs the backend via Maven (Spring Boot) locally

Start dev mode¶

./trustdeck.sh dev start

Stop dev mode¶

./trustdeck.sh dev stop

B) Production-like mode (everything in Docker)¶

What “prod-like mode” does¶

Starts Postgres + Keycloak using the prod compose file
Starts the backend container using the app compose file
Builds images and runs detached
Waits for the infrastructure containers to become healthy

One-time: create the external Docker network¶

The production compose expects an external Docker network named trustdeck.

docker network create trustdeck

(If it already exists, Docker will say so - that’s fine.)

Set locations of certificates in the `trustdeck.env`¶

Ensure that the paths to the certifcates are properly set in the environment file:

CHAIN_PEM_PATH
RSA_CRT_PATH
ECC_CRT_PATH
ORGANIZATION_CA_PEM_PATH

Build the backend JAR (required before starting prod-like)¶

The backend Dockerfile copies target/trustdeck*.jar into the container image, so you must build it first:

mvn -DskipTests package

Start prod-like mode¶

./trustdeck.sh prod start

Stop prod-like mode¶

./trustdeck.sh prod stop

Setup your reverse proxy¶

If required, setup your reverse proxy (e.g. nginx, Apache).

Examplary nginx-configuration that assumes Keycloak on port 8081 and the application on port 8080:

server {
    listen 443 ssl;
    server_name your.server.com alias.server.com;

    ssl_certificate     /path/to/server/certificates/chain.pem;
    ssl_certificate_key /path/to/server/certificates/privatekey.pem;

    # Optional (performance): OCSP stapling (needs a resolver configured)
    ssl_stapling on;
    ssl_stapling_verify on;

    ssl_prefer_server_ciphers on;
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 10m;

    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header Host              $host;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_redirect off;

    # Optional: fail-fast defaults, keep connection open longer
    keepalive_timeout 100;
    proxy_connect_timeout 3;
    proxy_send_timeout    3;
    proxy_read_timeout    3;

    location /api {
        proxy_pass http://127.0.0.1:8080/api;
        proxy_read_timeout 30;
    }

    location /swagger-ui {
        proxy_pass http://127.0.0.1:8080/swagger-ui;
    }

    location /v3/api-docs {
        proxy_pass http://127.0.0.1:8080/v3/api-docs;
    }

    location /auth {
        # Might be different depending on your exact Keycloak version and setup
        proxy_pass http://127.0.0.1:8081/auth/realms/master/protocol/openid-connect/certs;
    }

    location /admin/ {
        proxy_pass http://127.0.0.1:8081/auth/admin/;
    }

    location /health {
        proxy_pass http://127.0.0.1:9000/auth/health/ready;
    }

    location /js/ {
        proxy_pass http://127.0.0.1:8081/auth/js/;
    }

    location /realms/ {
        proxy_pass http://127.0.0.1:8081/auth/realms/;
    }

    location /resources/ {
        proxy_pass http://127.0.0.1:8081/auth/resources/;
    }

    location /robots.txt {
        proxy_pass http://127.0.0.1:8081/auth/robots.txt;
    }

    # Optional: forward all other requests to the frontend (if also available, assumed to be on port 8082)
    location / {
        proxy_pass http://127.0.0.1:8082/;
    }

    error_log  /var/log/nginx/error.log  error;
    access_log /var/log/nginx/access.log combined;
}

Note

Remember to set URIs in the environment-file accordingly

Quick checks (optional)¶

See container state¶

docker ps -a

Logs (replace names if your compose uses different container names)¶

docker logs trustdeck-postgresql
docker logs trustdeck-keycloak
docker logs trustdeck-backend