Self-Host

The Archodex Service can be self-hosted on-prem or in cloud environments for full control over where your data lives and how it is accessed.

The Archodex Service is easy to run using our archodex-backend container images. The backend service stores its state in an embedded on-disk database by default (with options to scale to a distributed database configuration as needed).

Once your self-hosted Archodex Service is running you can register it with the global archodex.com service. This enables you to login to the global Archodex Dashboard (https://app.archodex.com) which then will send requests directly to your self-hosted backend. When using a self-hosted Archodex Service, the only data stored in the global archodex.com service is your user authentication record and the location of your self-hosted Archodex Service.

Example Self-Hosted Architecture

The Archodex Backend can be run as a Docker Container, which is an easy way to try self-hosting:

docker run --rm -it -p 5732:5732 -v ./db:/db ghcr.io/archodex/archodex-backend:latest

This will run the Archodex Backend on port 5732 and persist its database files in the ./db folder.

Next we need to create a new account for your self-hosted Archodex Service. Start by logging into the Archodex Dashboard. If you don’t already have an account you will be presented with the Create Archodex Account form. If you already have an account, click on the Account Switcher on the left sidebar under the Archodex logo and select New Account.

In the Create Archodex Account form select the Self-Hosted Account option. Then provide the location of your self-hosted Archodex Backend. If you followed the above instructions to run the Archodex Backend locally as a Docker Container, you should enter http://localhost:5732. Then click Create Account.

This will create a record of your self-hosted account in the global Archodex accounts so the Dashboard knows where your self-hosted backend lives. Now, whenever you login to the Dashboard and select this account it will know to query your backend running at the endpoint you provided when creating the account.

Just as when using a managed archodex.com account, our next step is to create a Report API Key. This key will be used by the Archodex Agent to authenticate with your self-hosted Archodex Service.

After creating a new account you will be prompted to create a Report API Key in the Archodex Dashboard. You can also create and manage Report API Keys in the Account Settings page.

Create a descriptive name for your API key and click Create Key. Make sure to copy the generated API key, as you will need it in the next step.

When using a self-hosted Archodex Service you will need to tell the Archodex Agent where to send observation reports to. This can be accomplished by running with the -s / --service-endpoint argument or using the ARCHODEX_SERVICE_ENDPOINT environment variable. The following example shows how to run the Archodex Agent in a local Docker Container and send reports to the Archodex Backend we launched in another Docker Container above:

docker run --rm -it \
  --pid host --cap-add BPF --cap-add PERFMON --cap-add SYS_PTRACE \
  ghcr.io/archodex/archodex-agent:latest network \
  --service-endpoint http://172.17.0.1:5732 \
  --report-api-key <Report API Key>

Archodex uses SurrealDB for its graph database. SurrealDB can be thought of as a graph query processing unit with swappable key-value store (KVS) engine to hold records. In the hosted Archodex.com Service each customer account is provisioned an independent SurrealDB database. For self-hosted Archodex Services you only need a single SurrealDB database for the backend to use.

To make it easy to get up and running with Archodex the backend defaults to using a local directory for the database (/db in our published Docker / OCI Images, ./db when run locally). This is a convenient way to try self-hosting an Archodex account, but we strongly recommend against using this approach in production.

In production we recommend using Surreal Cloud, which provides managed SurrealDB databases as a service. You may also choose instead to host your own SurrealDB server (see the SurrealDB docs here). The Archodex Backend uses the following environment variables to connect to the SurrealDB database:

• SURREALDB_URL: The SurrealDB connection URL string, e.g. wss://archodex-0cdecs4v5b75pns.aws-use1.surreal.cloud
• SURREALDB_USERNAME: The SurrealDB username (optional, required if using authentication)
• SURREALDB_PASSWORD: The SurrealDB password (optional, required if using authentication)

The Archodex Backend is a stateless Rust service. You should only need to run one instance of the backend service, but it can scale horizontally if needed.

All user authentication occurs through the global auth.archodex.com service. Both our managed archodex.com service and self-hosted services validate JWT access tokens from the auth.archodex.com service. This provides a consistent and secure authentication experience across all Archodex accounts, and simplifies self-hosting configuration.

API keys contain both encrypted and signed information. By default, a private key is generated when self-hosted accounts are created, and this key is stored in the database. In your production environment you may have more secure mechanisms for generating and maintaining key material, such as hardware security modules (HSMs) or cloud-based key management services (KMSs). Instead of generating the private key and storing it in the database you can provide a 16-byte hex-encoded private key value through the ARCHODEX_PRIVATE_API_KEY environment variable. This must be set before you create an account in your self-hosted Archodex Service, and must continue to be provided each time the service is run.