This deployment has been tested on macOS with Docker Desktop, Ubuntu (22.04 LTS and 24.04 LTS) and RHEL with Docker Compose. For help with other operating systems, please find us on Discord for support.

It you have SELinux installed, you’ll also need to add the :z suffix to the Caddy volume mount: ./Caddyfile:/etc/caddy/Caddyfile:z in the Docker Compose file.

​
Prerequisites

​
Verify Prerequisites

To verify that Docker Compose and Docker are installed on the machine where you plan to install Tracecat, run the following commands.

# Check Docker installation
docker

# Check Docker Compose installation
docker compose

​
Download Configuration Files

If you’re deploying Tracecat into an external instance (e.g. AWS EC2, GCP Compute Engine, Azure VM), please note that you’ll have to set PUBLIC_APP_URL and PUBLIC_API_URL in the .env file to the IP address or host you are accessing Tracecat from.

For example, if you are port forwarding Tracecat from http://localhost (port 80) inside AWS EC2 to http://localhost:8080 on your local machine, you must set PUBLIC_APP_URL to http://localhost:8080 and PUBLIC_API_URL to http://localhost:8080/api/.

You can set these options when running the env.sh configuration script.

Tracecat requires a set of environment variables and credentials stored in .env file to run. We created a helpful shell script to generate the .env file. Use the commands listed below to download the required configuration files (env.sh, .env.example) and generate your own .env file.

# 1. Download the env.sh installation script
curl -o env.sh https://raw.githubusercontent.com/TracecatHQ/tracecat/0.21.5/env.sh

# 2. Download the .env.example template file (env.sh needs this to generate your .env file)
curl -o .env.example https://raw.githubusercontent.com/TracecatHQ/tracecat/0.21.5/.env.example

# 3. Make the env.sh script executable and run it
chmod +x env.sh && ./env.sh

You should see the following instructions after executing env.sh.

You’ll be prompted to input the following:

  • y (yes to production mode)
  • localhost (default host)
  • n (no to postgres SSL mode).

Otherwise, if you’re deploying Tracecat into an external / Cloud VM, input:

  • y (yes to production mode)
  • <host-where-tracecat-is-exposed> (e.g. localhost:8080)
  • n (no to postgres SSL mode).

Setting production mode to n changes where Tracecat’s remote repository is installed. Do not set production mode to n unless you are a Tracecat developer.

By default, Tracecat will install the remote repository to the user’s home directory at ~/.local/lib/python3.12/site-packages/. Setting production mode to y will install the remote repository to the PYTHONUSERBASE directory specified in enviroment variables.

​
Download Caddyfile

Tracecat uses Caddy as a reverse proxy. You’ll need to download the following Caddyfile to configure this service.

curl -o Caddyfile https://raw.githubusercontent.com/TracecatHQ/tracecat/0.21.5/Caddyfile

​
Download Docker Compose File

curl -o docker-compose.yml https://raw.githubusercontent.com/TracecatHQ/tracecat/0.21.5/docker-compose.yml

​
Start Tracecat

Run the command below to start Tracecat and all related services. Make sure your docker-compose.yml and generated .env files are in the same directory.

docker compose up

Your Tracecat instance should now be running on http://localhost. To access the Tracecat GUI, visit http://localhost.

Tracecat comes with a REST API, you can visit the live API docs at http://localhost/api/docs.

​
Login

Find out how to configure authentication in Tracecat. View docs.

For each new Tracecat deployment, the admin superuser role is assigned to the first user who logs into the Tracecat instance. This user owns the organization and has admin rights to every workspace in the Tracecat deployment.

To proceed, sign up and create an account with a strong and secure password.

​
Next Steps

  • Log into Tracecat and build your first playbook. View quickstart.
  • Tracecat comes with basic (email + password) authentication. Find out how to configure other authentication methods. View docs.
  • Read inline comments in the generated .env file to better understand Tracecat’s configurations. View .env.example file