Skip to main content

Full Stack (Docker)

This guide provides the minimal steps to get our full software stack running locally for development and testing purposes. Choose the deployment option that matches your needs:

  • Local deployment: Run everything on your local machine for development and testing
  • Domain deployment: Deploy to a server with a public domain behind an SSL-terminating proxy
Security Notice

This quick setup guide is designed for development and testing environments only. The configurations provided use shared starter values and are not hardened for production use. Option B exposes the stack to the internet; do not use it for real data or leave it running unattended.

Prerequisites​

  • Docker installed on your local machine
  • Deployment credentials and files (provided by your implementation team):
    • Container registry login command with credentials (docker login -u ...)
    • Docker Compose configuration file
    • Environment and configuration files

1. Log in to Docker​

Use the provided credentials to log in to Docker.

docker login -u [username] -p [password] [registry-url].azurecr.io

2. Set customer name for Docker registry​

Set the CUSTOMER variable to your assigned customer name (lowercase, for example acme):

export CUSTOMER=<customer_name>

Your implementation team provides this with your Docker credentials. Note that it may differ slightly from your Docker username.

3. Choose your deployment​

Option A: Local deployment​

note

Option A is for exploring the Desk and the APIs on your own machine. Wallet flows, such as issuing to or verifying with a mobile wallet, need Core to be reachable from outside your machine. To test these locally, expose Core through a tunnel. See Local Testing with a Tunnel. For a permanent setup, use Option B.

Configure local domain resolution​

Your deployment uses service names, like keycloak, that need to resolve to your local machine. The /hosts file tells your computer how to resolve domain names locally, before it asks DNS servers.

  1. Open your hosts file:

sudo vim /etc/hosts     # You may need to input your system password to open the file

  1. Add the following line:

127.0.0.1 keycloak

  1. Save and exit the editor.

Now your computer will redirect keycloak to localhost instead of looking for it on the internet.

Need help editing in vim?

  1. Press o to create a new line and enter insert mode

  2. Type: 127.0.0.1 keycloak

  3. Press Esc to exit insert mode

  4. Type :wq and press Enter to save and quit

Quick reference:

  • o = new line + insert mode
  • Esc = exit insert mode
  • :wq = save and quit
  • :q! = quit without saving

Start services​

docker compose up -d

This command starts all services in detached mode. The first startup may take a few minutes as services initialize and discover each other. If you see errors related to OIDC configuration discovery, wait a minute or two and try accessing the application again.

Access your application​

Your full stack is now running! Access the application at http://localhost and login with these test credentials:

  • username: example_user
  • password: example_password

See 4. Create your first organization for the final step.

Option B: Server deployment with a domain​

Use this option to deploy to a server with your own domain. The stack includes Traefik as a reverse proxy, which terminates TLS and obtains certificates from Let's Encrypt automatically.

If your server already runs a reverse proxy or sits behind a load balancer, see Domains and Exposure before continuing.

Before you begin​

  • A server with Docker, with ports 80 and 443 reachable from the internet. Port 80 is required for Let's Encrypt certificate issuance.
  • DNS records pointing the following hostnames to your server:
    • <domain>
    • core.<domain>
    • keycloak.<domain>
    • bridge.<domain>
    • wrpr.<domain>

Replace placeholders​

The configuration in /docker_compose_behind_ssl_proxy contains two placeholders:

  • <domain>: your domain, for example example.com
  • <email>: the email address used for your Let's Encrypt account

From the docker_compose_behind_ssl_proxy directory, replace them in all files:

grep -rl '<domain>' . | xargs sed -i.bak 's/<domain>/example.com/g'
grep -rl '<email>' . | xargs sed -i.bak 's/<email>/you@example.com/g'
find . -name '*.bak' -delete

Confirm that no placeholders remain:

grep -rn '<domain>\|<email>' .

The command should return no results.

Start services​

docker compose up -d

This command starts all services in detached mode. The first startup may take a few minutes as services initialize and discover each other. If you see errors related to OIDC configuration discovery, wait a minute or two and try accessing the application again.

Access your application​

Access the application at https://<domain> using the test credentials:

  • username: example_user
  • password: example_password

See 4. Create your first organization for the final step.

Next steps​

As soon as your chosen applications become available: