---
title: Docker Compose
description: Deploy Tracecat using a Docker Compose template.
---

<Note>
  This deployment has been tested on macOS with Docker Desktop and Ubuntu (22.04 LTS and 24.04 LTS) only.
  For help with other operating systems, please find us on [Discord](https://discord.gg/n3GF4qxFU8) for support.
</Note>

## Prerequisites

- [Docker](https://docs.docker.com/engine/install/) version 26.0.0+
- [Docker Compose](https://docs.docker.com/compose/install/) version 2.29.0+
- [openssl](https://www.openssl.org/source/)

## Verify Prerequisites

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

```bash
# Check Docker installation
docker

# Check Docker Compose installation
docker compose
```

## Download Configuration Files

<Note>
  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.
</Note>

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.

```bash
# 1. Download the env.sh installation script
curl -o env.sh https://raw.githubusercontent.com/TracecatHQ/tracecat/0.19.1/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.19.1/.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`.

<Info>
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).
</Info>

<Note>
  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.
</Note>

![env.sh](/img/self-hosting/env-script.png)

## Download Caddyfile

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

```bash
curl -o Caddyfile https://raw.githubusercontent.com/TracecatHQ/tracecat/0.19.1/Caddyfile
```

## Download Docker Compose File

```bash
curl -o docker-compose.yml https://raw.githubusercontent.com/TracecatHQ/tracecat/0.19.1/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.

```bash
docker compose up
```

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

![welcome-page](/img/self-hosting/welcome-page.png)

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

## Login

<Note>
  Find out how to configure authentication in Tracecat. [View docs](/self-hosting/authentication/introduction).
</Note>

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.

![sign-in](/img/self-hosting/sign-in.png)

## Next Steps

- Log into Tracecat and build your first playbook. [View quickstart](/quickstart).
- Tracecat comes with basic (email + password) authentication. Find out how to configure other authentication methods. [View docs](/self-hosting/authentication/introduction).
- Read inline comments in the generated `.env` file to better understand Tracecat's configurations. [View `.env.example` file](https://raw.githubusercontent.com/TracecatHQ/tracecat/0.13.2/.env.example)
