Skip to main content

​
Required secrets

SecretPurpose
TRACECAT__DB_ENCRYPTION_KEYFernet key for at-rest encryption in PostgreSQL. Losing it makes encrypted credentials unrecoverable.
TRACECAT__SERVICE_KEYHMAC key for service-to-service JWT signing.
TRACECAT__SIGNING_SECRETSigns webhook URLs and HMAC operations. Changing it invalidates existing webhook URLs.
USER_AUTH_SECRETSigns OAuth state parameters and password-reset tokens.
Generate all four with openssl: 
# TRACECAT__SERVICE_KEY
openssl rand -hex 32

# TRACECAT__SIGNING_SECRET
openssl rand -hex 32

# USER_AUTH_SECRET
openssl rand -hex 32

# TRACECAT__DB_ENCRYPTION_KEY (Fernet-compatible base64)
openssl rand 32 | base64 | tr -d '\n' | tr '+/' '-_'

​
Example .env

PUBLIC_APP_URL=https://tracecat.yourdomain.com
PUBLIC_API_URL=https://tracecat.yourdomain.com/api
TRACECAT__APP_ENV=production
TRACECAT__DB_ENCRYPTION_KEY=<openssl rand 32 | base64 | tr -d '\n' | tr '+/' '-_'>
TRACECAT__SERVICE_KEY=<openssl rand -hex 32>
TRACECAT__SIGNING_SECRET=<openssl rand -hex 32>
USER_AUTH_SECRET=<openssl rand -hex 32>
TRACECAT__AUTH_SUPERADMIN_EMAIL=admin@yourdomain.com
TRACECAT__DB_SSLMODE=require
TRACECAT__POSTGRES_USER=postgres
TRACECAT__POSTGRES_PASSWORD=<secure-password>
See .env.example for all options.

​
Variables

​
Network

VariableDefaultDescription
PUBLIC_APP_PORT80Port the reverse proxy listens on.
PUBLIC_APP_URLhttp://localhost:${PUBLIC_APP_PORT}Public URL users visit to reach the Tracecat UI.
PUBLIC_API_URL${PUBLIC_APP_URL}/apiPublic URL for the Tracecat API, used by the browser and for webhook callbacks.
INTERNAL_API_URLhttp://api:8000Internal URL that other services use to reach the API container.

​
Application

VariableDefaultDescription
TRACECAT__APP_ENVdevelopmentOne of development, staging, or production. Controls logging detail and debug behavior.
TRACECAT__API_URL${INTERNAL_API_URL}API URL used by backend services. Normally matches INTERNAL_API_URL.
TRACECAT__API_ROOT_PATH/apiPath prefix the API registers behind the reverse proxy.
TRACECAT__PUBLIC_APP_URL${PUBLIC_APP_URL}Public frontend URL used for links in emails and notifications.
TRACECAT__PUBLIC_API_URL${PUBLIC_API_URL}Public API URL used for incoming webhooks. If you expose webhooks through a tunnel (e.g. ngrok), set this to the tunnel URL.
TRACECAT__ALLOW_ORIGINShttp://localhost:3000,${PUBLIC_APP_URL}Comma-separated list of allowed CORS origins.

​
PostgreSQL

VariableDefaultDescription
TRACECAT__POSTGRES_USERpostgresPostgreSQL username.
TRACECAT__POSTGRES_PASSWORDpostgresPostgreSQL password. Change this in production.
TRACECAT__DB_URIpostgresql+psycopg://${TRACECAT__POSTGRES_USER}:${TRACECAT__POSTGRES_PASSWORD}@postgres_db:5432/postgresFull database connection URI. Override this when using an external database.
TRACECAT__DB_SSLMODEdisablePostgreSQL SSL mode. Set to require or verify-full for remote databases.

​
Authentication

VariableDefaultDescription
TRACECAT__AUTH_SUPERADMIN_EMAILEmail of the first user to promote to superadmin on initial startup.
TRACECAT__AUTH_TYPESbasicComma-separated list of enabled auth methods: basic, oidc, saml.
TRACECAT__AUTH_ALLOWED_DOMAINSComma-separated email domains allowed to register (e.g. example.com,example.org). Leave blank to allow all.
TRACECAT__AUTH_MIN_PASSWORD_LENGTH12Minimum password length for basic auth.

​
OIDC / OAuth

VariableDefaultDescription
OIDC_ISSUEROIDC issuer URL (e.g. https://accounts.google.com).
OIDC_CLIENT_IDOAuth client ID from your identity provider.
OIDC_CLIENT_SECRETOAuth client secret from your identity provider.
OIDC_SCOPESopenid profile emailSpace-separated OAuth scopes to request.

​
SAML

VariableDefaultDescription
SAML_IDP_METADATA_URLURL to your SAML IdP metadata XML.
SAML_ACCEPTED_TIME_DIFF3Maximum clock skew in seconds accepted when validating SAML assertions.

​
Temporal

VariableDefaultDescription
TEMPORAL__CLUSTER_URLtemporal:7233Temporal cluster gRPC endpoint.
TEMPORAL__CLUSTER_QUEUEtracecat-task-queueTemporal task queue name.
TEMPORAL__CLUSTER_NAMESPACEdefaultTemporal namespace.
TEMPORAL__API_KEYAPI key for Temporal Cloud. Leave empty for self-hosted Temporal.

​
Executor

VariableDefaultDescription
TRACECAT__EXECUTOR_BACKENDdirectExecution strategy for actions. direct runs a subprocess per action, pool uses warm nsjail workers (requires nsjail), ephemeral spawns a cold nsjail subprocess per action for full isolation, auto selects pool if nsjail is available and falls back to direct, test runs in-process for tests only.
TRACECAT__DISABLE_NSJAILtrueDisable nsjail sandboxing. Set to false only if nsjail is installed.
TRACECAT__RESULT_EXTERNALIZATION_ENABLEDtrueStore large action results in blob storage instead of Temporal history.
TRACECAT__COLLECTION_MANIFESTS_ENABLEDtrueStore large collections as chunked manifests in blob storage.
TRACECAT__RESULT_EXTERNALIZATION_THRESHOLD_BYTES128000Byte threshold above which payloads are externalized to blob storage.
TRACECAT__WORKFLOW_ARTIFACT_RETENTION_DAYS30Retention period in days for workflow artifacts. Objects older than this are automatically deleted via S3 lifecycle rules. Set to 0 to disable.

​
Blob storage

VariableDefaultDescription
TRACECAT__BLOB_STORAGE_BUCKET_WORKFLOWtracecat-workflowS3 bucket for workflow artifacts.
TRACECAT__BLOB_STORAGE_BUCKET_ATTACHMENTStracecat-attachmentsS3 bucket for case attachments.
TRACECAT__BLOB_STORAGE_BUCKET_REGISTRYtracecat-registryS3 bucket for registry packages.

​
MinIO

VariableDefaultDescription
MINIO_ROOT_USERminioMinIO root username. Only used with the bundled MinIO instance.
MINIO_ROOT_PASSWORDpasswordMinIO root password. Change this in production.

​
Redis

VariableDefaultDescription
REDIS_HOSTredisRedis hostname.
REDIS_PORT6379Redis port.
REDIS_URLredis://${REDIS_HOST}:${REDIS_PORT}Full Redis connection URL. Override this when using an external Redis instance.