Getting Started

In this guide, we'll get all the prerequisite values for deploying Sombra.

To keep track of the values you'll need for Sombra, we recommend first creating a template file with the following values. Be sure to move these secrets to a secure storage location once you're finished setting up Sombra.

# API Keys used outside of Sombra

TRANSCEND_API_KEY=xxxx
INTERNAL_KEY=xxxx

# Sombra's Environment Variables

SOMBRA_ID=xxxx
SOMBRA_REVERSE_TUNNEL_API_KEY=xxxx
ORGANIZATION_URI=xxxx
TRANSCEND_URL=xxxx

JWT_ECDSA_KEY=xxxx
INTERNAL_KEY_HASH=xxxx

Create a Transcend API Key in the Admin Dashboard under Infrastructure → API Keys. No specific scope is required for this API key.

Save this under the TRANSCEND_API_KEY value in your template file. It will only be displayed once in the Admin Dashboard. If you lose it, you can always create a new one. This is used to authenticate to Transcend's Docker Registry.

  1. Go to the Sombra Gateways page

  2. Click "Create New Self Hosted Sombra"

  3. Select "Self-Hosted Sombra - Reverse Tunnel" from the dropdown

  4. Leave the "Existing Sombra ID" field blank, unless you're re-using a Sombra deployment currently registered with another organization

    Creating a Self Hosted Sombra using the Transcend Reverse Tunnel

Click the "Create" button to generate a configuration snippet that will look similar to:

SOMBRA_ID=xxxx
SOMBRA_REVERSE_TUNNEL_API_KEY=xxxx
ORGANIZATION_URI=xxxx
TRANSCEND_URL=xxxx

Save these values under their corresponding keys in your template file.

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.

Generate the JWT_ECDSA_KEY value with your by running:

JWT_ECDSA_KEY=$(openssl ecparam -genkey -name secp384r1 -noout | (base64 --wrap=0 2>/dev/null || base64 -b 0))
echo "Set this in your Sombra environment: JWT_ECDSA_KEY: $JWT_ECDSA_KEY"

Save this under the JWT_ECDSA_KEY value in your template file.

Generate your Sombra API key (INTERNAL_KEY) and a corresponding SHA-256 hash (INTERNAL_KEY_HASH) by running:

INTERNAL_KEY_BIN=$(openssl rand 32)
INTERNAL_KEY=$(echo -n "$INTERNAL_KEY_BIN" | base64)
INTERNAL_KEY_HASH=$(echo -n "$INTERNAL_KEY_BIN" | openssl dgst -binary -sha256 | openssl base64)
echo "Save this Sombra API key for your internal services: INTERNAL_KEY: $INTERNAL_KEY"
echo "Set this Sombra API key hash in your Sombra environment: INTERNAL_KEY_HASH: $INTERNAL_KEY_HASH"

The internal key is a bearer token used to authenticate your internal services to Sombra. The INTERNAL_KEY_HASH will be added to your Sombra environment variables, and is used to verify the bearer token.

Save these values in your template file, under the INTERNAL_KEY and INTERNAL_KEY_HASH values.

You can now proceed to a deployment guide. We recommend deploying with Kubernetes via Helm. You can view all deployment options here.