Deploy on Caution-managed infrastructure¶

Deploy your first application on Caution's fully managed platform using AWS Nitro Enclaves. Your first deployment should take about 10 minutes.

What is fully managed?¶

Fully managed is a deployment model where Caution hosts and operates the deployment environment end-to-end on Caution-managed infrastructure. For full details, see the fully managed reference.

What you need¶

Before you begin, ensure you have the following:

Install the CLI¶

Clone the platform repository and run the automatic installer:

git clone https://codeberg.org/caution/platform
cd platform
make install-cli

On every supported platform (Linux/x86_64 and macOS/arm64) this builds the CLI with your local host toolchain, after a one-time acknowledgement that the build is not reproducibility-verified. To build the reproducible StageX CLI instead, run make install-cli-stagex (Linux/x86_64 only). See the CLI README for explicit build targets and verification options.

Create an account¶

To create an account, you'll need a valid access code and a passkey. You can register in the browser or with the CLI.

If you do not have an access code, request one at info@caution.co.

caution register --alpha-code <your_code>

Add an SSH key¶

Add an SSH key so you can authenticate your Caution deployments:

caution ssh-keys add --from-agent

Select an application¶

Deploy your own containerized application, or start with one of the Caution demo apps. For this guide, use hello-world-enclave:

git clone https://codeberg.org/caution/demo-hello-world-enclave.git
cd demo-hello-world-enclave

Initialize the application¶

From your application directory, run the following command to create a caution.hcl and other data required for the application:

caution init

caution.hcl defines how to run your application and which ports to expose. If you're using one of Caution's demo apps, a caution.hcl is already included. If you're deploying your own application, you'll need to create one. See the caution.hcl reference.

Commit the generated caution.hcl and .caution/deployment.json to your repository. The deployment file stores the Caution app resource ID so CLI commands can infer the target app from the repository.

For your own app, make sure the container builds from the repository root with the standard Docker form:

docker build -f Containerfile .

If you use another file, set containerfile in the build block and replace Containerfile with that path. Caution uses this build shape and does not pass extra build arguments, so public build-time values need to be part of the image inputs. Use Locksmith for secrets.

At minimum, your caution.hcl should specify how to run your application:

enclave "main" {
  unit "default" {
    command = "/app/server"
  }
}

For source verification, add your repository URL:

enclave "main" {
  build {
    app_sources = ["https://codeberg.org/myorg/myapp"]
  }
  unit "default" {
    command = "/app/server"
  }
}

Add environment variables¶

If your application needs environment variables, use Key services before deploying. The guide covers non-encrypted variables for public configuration and encrypted variables for secrets, including how to deploy Keymaker, generate shard-holder OpenPGP keys, create a quorum bundle, encrypt values from .env, and reference secrets with env::vault in your caution.hcl.

Skip this step if your application does not need environment variables.

Deploy the application¶

From your application directory, push the code to Caution:

git push caution main

Caution builds a reproducible enclave image with the standard Docker build and deploys it into the enclave.

Verify the deployment¶

From your application directory, run the following command to rebuild the image, compare hashes, and confirm exactly what the enclave is running:

caution verify --save-pcrs

The --save-pcrs flag saves the verified PCR values to .caution/trusted_hashes.json. This file is required before sending locksmith shards — commit it alongside your other .caution/ files.

Next steps¶

Your application is now running in a verified enclave. Here's what to explore next: