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.38.4/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.38.4/.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
  • Enter email address for the first user (superadmin) - required field

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

​
Download Docker Compose File

curl -o docker-compose.yml https://raw.githubusercontent.com/TracecatHQ/tracecat/0.38.4/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 super admin 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.

Important: Only the email address you specified during the env.sh setup can become super admin. You must sign up using exactly that email address to gain super admin privileges.

To proceed, sign up and create an account with a strong and secure password using the super admin email you configured. Check out the admin tutorial for more information.

​
Networking

The following env variables are used to configure external facing network settings for Tracecat:

  • PUBLIC_APP_URL - Tracecat frontend URL.
  • PUBLIC_APP_PORT - Tracecat frontend port.
  • PUBLIC_API_URL - Tracecat API URL.
  • NEXT_PUBLIC_APP_URL - Browser client will use this URL to access the Tracecat frontend.
  • NEXT_PUBLIC_API_URL - Browser client will use this URL to access the Tracecat API.
  • BASE_DOMAIN - Caddy will use this domain to reverse proxy the Tracecat frontend and API. Defaults to :{PUBLIC_APP_PORT}
  • ADDRESS - Caddy will use this address to bind to the network. Defaults to 0.0.0.0

Within the docker network, the following env variables are used to configure network settings within the docker network for Tracecat:

  • INTERNAL_API_URL - Tracecat API URL (defaults to http://api:8000)
  • INTERNAL_EXECUTOR_URL - Tracecat executor URL (defaults to http://executor:8000)
  • NEXT_SERVER_API_URL - Tracecat API URL (defaults to INTERNAL_API_URL)

​
Troubleshooting

​
”Network error” / “Failed to fetch” sign-in page

This error occurs when your browser cannot connect to Tracecat API via PUBLIC_APP_URL. Please check the following:

  • Do not set PUBLIC_APP_URL to 0.0.0.0. Browsers cannot connect to this address. Use localhost, 127.0.0.1, or your machine’s actual IP address instead.
  • WSL users: Do not use 127.0.0.1. Run ip addr to find your WSL IP address (usually 172.x.x.x) and use that instead.
  • If you frontend is running on a different machine than the API, set NEXT_PUBLIC_API_URL to an address your browser can reach.
  • Run docker compose ps to verify all services are running.
  • Check the temporal service is healthy. Worker connectivity issues can sometimes affect login.
  • View container logs: docker compose logs api and docker compose logs temporal.
  • Check firewall and port forwarding if using a reverse proxy.

Related issues: #1166, #887, #867, #779

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