Getting started

Deploying Tandem

Tandem is a proxy that sits between your application and your database. It encrypts and decrypts data as it passes through the proxy, based on your configurations. This guide will walk you through the process of deploying Tandem to the example application.

Tandem is deployed as a Docker container. You can deploy Tandem to any environment that supports Docker containers. In this exmample we will be deploying Tandem locally, alongside the example application.

Configuring Tandem

Tandem is configured using a combination of environment variables and a configuration file. The configuration file is a JSON file that contains the proxy settings and database connection information. The configuration file is mounted into the Tandem container as a volume and is read by the proxy when it starts.

Tandem configuration

Tandem can be configured using a configuration file or environment variables. For this example you'll use environment variables to configure Tandem. You can view the full list of configuration options and descriptions in the reference section.

You can view the required environment variables in the docker compose file for the Tandem service. It is reccomended that credentials are pulled from a secrets management solution such as Hashicorp Vault, or AWS Secrets Manager. The following environment variables are defined:

1# general options
2LOG_LEVEL: debug
5# tandem connection options
6CS_PORT: 6432
7CS_USERNAME: postgres
8CS_PASSWORD: password
10# connect to postgres
11CS_DATABASE__HOST: postgres
17# setup using stash-cli
18CS_WORKSPACE_ID: fill_me_in
19CS_CLIENT_ID: fill_me_in
20CS_CLIENT_KEY: fill_me_in
21CS_CLIENT_ACCESS_KEY: fill_me_in

Setting your workspace ID

The workspace ID is used to group your datasets together. You can find your workspace ID by running the following command:

1stash workspaces

This will display a list of workspaces that you have access to. Copy the workspace ID for the workspace that you want to use for this example and export it as an environment variable:

1export CS_WORKSPACE_ID=12345678-1234-1234-1234-123456789012

Generate an access key

Tandem uses an access key as a machine to machine authentication method with the CipherStash cloud to pull down a dataset configuration. You can generate an access key using the stash CLI tool. If you don't have the stash CLI tool installed, you can follow the instructions in the first step of this guide.

1stash access-keys create --workspace-id $CS_WORKSPACE_ID tandem-tutorial

This will generate an access key and display the access key for programmatic access. Copy the access key and save it for the next step.

Populate the environment variables

Now that you have an access key, you can populate the environment variables in the docker compose file where you see fill_me_in. Replace the fill_me_in values with the values for the access key, client ID, client key, and workspace ID that you generated in the previous steps.

An easy way to do this, given you've exported all the environment variables from the previous steps, is to run the following command:

1env | grep CS_

Re-deploying the Tandem proxy

Tandem is already running as part of the Docker Compose configuration. You can see the Tandem service defined in the docker-compose.yaml file. Now that Tandem is configured, you can restart Docker Compose to start Tandem with your configuration.

1docker compose stop
2docker compose up

Routing traffic through Tandem

Now that you have configured Tandem, you have to configure the application to connect to Tandem instead of directly to the database. Open the server.js file in the server directory and update the pool configuration to the following:

1const pool = new Pool({
2  user: "postgres",
3  host: "tandem",
4  database: "stash",
5  password: "password",
6  port: 6432,

Save the file and since you are using nodemon to run the application, the application will automatically restart and connect to Tandem.

Note that the host is set to tandem instead of postgres and the port is updated to 6432. This is the name and port of the service that we defined in the docker-compose.yml file for the Tandem service.

Verifying that Tandem is working

Now that you have Tandem running, you can verify that it is working correctly. Navigate to the application at http://localhost:3000. You should see the application running as before with the Welcome message.

Navigate to the users route at http://localhost:3000/users. You should see the list of users as before. If you look at the database, you'll see that the data is still unencrypted.

2  {
3    "id": 1,
4    "name": "Anakin",
5    "email": "[email protected]"
6  },
7  {
8    "id": 2,
9    "name": "Luke",
10    "email": "[email protected]"
11  }

Next you'll configure Tandem to encrypt and decrypt the data.

Step 2 - Datasets and client keys