Evaluating with Docker Compose

The Compose stack in deploy/compose/ brings the whole product up on one host with one command. It runs the key server, PostgreSQL reached over verify-full, the REST Gateway and the Console. It is built from the same packages and images a production installation uses, with no identity in any image or in the Compose file.

Evaluation only, not a production shape

Everything runs on one host, with one key server, one database, no failover and no backup. The database's TLS is signed by a throwaway CA minted at first run. The key server's TLS identity is self-signed. Every port is published on 127.0.0.1 only. For production, install the Linux packages or the Windows MSIs on your own hosts, or run the images under an orchestrator as on AWS, with your own CA and database.

Prerequisites

• Docker Engine 26 or later with the Compose plugin. Volume subpath mounts are used. Proved on Docker Engine 29.5 with Compose 5.1.
• The release's tricryption-ks, tricryption-console-gateway and tricryption-node packages, all from one release, in one directory. tricryption-re is not used.
• The deploy/compose/ and packaging/oci/ directories of the Tricryption distribution, with bash, dpkg-deb and python3 on the host. The stack's images are built locally from the packages. Nothing Tricryption is installed on the host.
• Free host ports 127.0.0.1:29790, 29791 and 29793.

Commands

bash deploy/compose/te-compose.sh up --debs <package-dir>
bash deploy/compose/te-compose.sh check
bash deploy/compose/te-compose.sh down
bash deploy/compose/te-compose.sh up
bash deploy/compose/te-compose.sh purge

Command	Does
up --debs <package-dir>	builds the images from the packages, provisions once, and starts everything
check	checks that every container is healthy, both readiness routes answer 200, and every key-server database session is TLS
down	stops and removes the containers and the network; the volumes, and so the keys, are kept
up	starts again; the one-time provisioning is skipped and the same keys unwrap
purge	runs down, then removes the four volumes: every key is gone

The stack runs as the Compose project tricryption-eval: its containers are tricryption-eval-pg, tricryption-eval-init (the one-time init, which exits), tricryption-eval-ks, tricryption-eval-gateway and tricryption-eval-console, and docker ps --filter name=tricryption-eval lists them.

What is where

Host address	Is
127.0.0.1:29790	the Console. Sign in as admin.
127.0.0.1:29791	the REST Gateway (GET /api/v1/ready, POST /api/v1/session, /api/v1/crypto/*)
127.0.0.1:29793	the key server's TLS listener, for native clients
(not published)	PostgreSQL 16, which accepts TLS connections only

The key server's administrator password, which is also the Console's admin password, is generated at first run and kept in the key server's volume. Read it with:

docker exec tricryption-eval-ks cat /var/lib/pisoft/ks/main/_ADMINPASSWORD_

What happens at the first up

A one-time init container:

1. mints a throwaway CA, PostgreSQL's server certificate and the superuser's password, and writes a TLS-only pg_hba.conf;
2. creates the key server's database role and empty database over verify-full;
3. runs tricryption-ks-provision, writing the key-server instance into its volume exactly as on a host;
4. starts that key server briefly, so tricryption-tier-provision can enrol the Gateway's certificate identity and export the Gateway's and the Console's identities;
5. splits the export between the Gateway's and the Console's halves of a volume. Each container mounts only its own half, read-only.

Every generated secret lives in the stack's named volumes. None is in the Compose file, an .env file, an image layer or a build argument. The key-server image never provisions: started on an empty volume, it refuses and names the missing file.

The stack registers no release signer with the key server. As provisioned, the key server admits the Console and the Gateway without one, while both still re-check their own signed manifest at every start. A production key server registers its releases and raises its code-signing level: see Upgrade at code-signing level 2.

Named instances and the delegation option

A second stack can run beside the default one on the same host, as a named instance. Each instance is one line of deploy/compose/instances.conf:

# name    prefix                   port base  delegation
myeval    tricryption-myeval-eval  29850      delegation

Every command takes --instance <name>; with no --instance, a command drives the default stack, which is unchanged. An instance is its own Compose project, named by its prefix, with its own containers, network and volumes. It publishes the Console on the port base, the Gateway on base + 1 and the key server on base + 3, and it owns the ten ports from its base. Choose a base inside 29790-29899 that no other stack uses. purge --instance <name> removes only that instance's volumes and state.

bash deploy/compose/te-compose.sh up --instance myeval --debs <package-dir>
bash deploy/compose/te-compose.sh check --instance myeval
bash deploy/compose/te-compose.sh purge --instance myeval

The fourth column is the delegation option: delegation, or - for none. The default stack never has it. With it, the instance's Gateway can act for a registered service:

• up enrols a delegator certificate for the Gateway, with the DELEGATION flag and no role, and gives the Gateway a service registry, empty at first;
• operator --instance <name> --out <dir> writes the operator's files: the administrator's password (mode 600), the delegator's certificate and the registry in force;
• registry --instance <name> --file <json> replaces the service registry from a file on the host and restarts the Gateway on it. If the Gateway refuses the file, the previous registry is put back and the command fails;
• check adds delegation=on, or delegation=off for an instance without the option.

To register a service on such an instance and run an integration starter against it, follow Step 4 of the operator bootstrap, which runs every command against the instance's ports.