This deployment has been tested on Ubuntu (22.04 LTS and 24.04 LTS), macOS / RHEL with Docker Desktop, and Windows Linux Subsystem (WSL). 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.

The default Docker compose configuration has basic email / password auth enabled. Basic auth is not recommended for production environments, especially if exposed to the public internet.

Please consider using a more secure authentication method such as OAuth or SAML SSO unless running in an air-gapped environment with defense-in-depth controls.

​
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’ve deployed Tracecat into an external VM (e.g. AWS EC2, GCP Compute Engine, Azure VM), you’ll need 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/.

Moreover, if you are using a Windows machine, make sure to set PUBLIC_APP_URL to 127.0.0.1 (not localhost).

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.35.3/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.35.3/.env.example

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

After running env.sh, you’ll be prompted to input the following:

  • Use production mode? - defaults to y (use y unless you are a Tracecat developer)
  • Set PUBLIC_APP_URL to - defaults to localhost
  • Require PostgreSQL SSL mode? - defaults to n

When installing Tracecat on a local workstation, use localhost or 127.0.0.1 as the IP address. Avoid using 0.0.0.0, as the frontend will attempt to call 0.0.0.0/api/ to access the backend API, causing connection issues.

If you want to expose Tracecat on a custom port, you can set PUBLIC_APP_PORT in the .env file. For example, to expose Tracecat UI at http://localhost:8082, set PUBLIC_APP_PORT=8082 in the .env file.

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.35.3/Caddyfile

​
Download Docker Compose File

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

​
Start Tracecat

If you want to expose Tracecat on a custom port (default is 80), you can set PUBLIC_APP_PORT in the .env file. For example, to expose Tracecat UI at http://localhost:8080, set PUBLIC_APP_PORT=8080 in the .env file.

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:${PUBLIC_APP_PORT}. To access the Tracecat GUI, visit http://localhost:${PUBLIC_APP_PORT}.

Tracecat comes with a REST API, you can visit the live API docs at http://localhost:${PUBLIC_APP_PORT}/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. Check out the admin tutorial for more information.

​
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.