Docker Run

This guide covers using basic docker run commands to run the Sombra server. This is not recommended for production environments, as docker run commands lack automatic container restart capabilities if connections are lost, memory issues occur, or other failures happen.

We recommend using this approach for testing and evaluation only. For production deployments, refer to the Helm deployment option.

Prerequisites

Follow our Getting Started guide to get access to our container registry, and get all the environment variables you'll need when configuring Sombra.

Use the following docker run command to deploy Sombra:

# Authenticate to the Docker registry using your API key from Getting Started Step 1
docker login docker.transcend.io -u Transcend -p <TRANSCEND_API_KEY>

# Pull the latest Sombra image
docker pull docker.transcend.io/sombra:latest

# Values from the copyable snippet from Getting Started Step 2
SOMBRA_ID=<SOMBRA_ID>
SOMBRA_REVERSE_TUNNEL_API_KEY=<SOMBRA_REVERSE_TUNNEL_API_KEY>
ORGANIZATION_URI=<ORGANIZATION_URI>
TRANSCEND_URL=<TRANSCEND_URL>

# Values generated from Getting Started Step 3
JWT_ECDSA_KEY=<JWT_ECDSA_KEY>
INTERNAL_KEY_HASH=<INTERNAL_KEY_HASH>

docker run \
  -p 5039:5039 \
  -e SOMBRA_ID="$SOMBRA_ID" \
  -e SOMBRA_REVERSE_TUNNEL_API_KEY="$SOMBRA_REVERSE_TUNNEL_API_KEY" \
  -e ORGANIZATION_URI="$ORGANIZATION_URI" \
  -e TRANSCEND_URL="$TRANSCEND_URL" \
  -e JWT_ECDSA_KEY="$JWT_ECDSA_KEY" \
  -e INTERNAL_KEY_HASH="$INTERNAL_KEY_HASH" \
  docker.transcend.io/sombra:latest

If you are migrating from an existing Transcend-hosted Sombra, it is critical that you migrate the existing JWT_ECDSA_KEY to your self-hosted Sombra. If you do not properly migrate your multi-tenant JWT_ECDSA_KEY, you will need to re-connect all integrations from scratch, and restart all DSRs!

Please follow this migration guide.

After the container has been running for a minute or so, look for a log message containing Successfully synced configuration with transcend backend. This confirms that:

  1. Your Sombra cluster can communicate with the Transcend backend
  2. Your API key is valid
  3. The Transcend backend can communicate with your Sombra cluster

Go to the Sombra Gateways page and click the "Test" button under "Test Gateway Connection" to make a GET request to the /test endpoint of the Sombra Gateway.

Buttons to test the Sombra connection

You should see a successful message if the connection is working. Congratulations on successfully deploying Sombra!

Go to http://localhost:5039/health to see that the HTTP API is accessible from port 5039.