Install Ottertrail
An Ottertrail instance runs on one server with Docker Compose. The install is a folder with four files from a GitHub release and a settings file, .env. You do not need a copy of the source code.
What you need
Section titled “What you need”- A Linux server with Docker Engine and Docker Compose 2.23.1 or later. Run
docker compose versionto see your version. - About 8 GB of memory. ClickHouse, the database for events and telemetry, uses at most 40% of it.
- A domain or subdomain for the instance, such as
analytics.example.com. Point its DNSArecord (andAAAArecord for IPv6) at the server. - Ports 80 and 443 open to the internet. Caddy, the web server in the stack, uses them to get a TLS certificate from Let’s Encrypt. Browsers send events to port 443. No other port must be open, except SSH.
- Outgoing HTTPS, so that the worker can download the location data from DB-IP and the cloud providers. Without it, the instance works, but events have no location and visits from data centers are not recognised. See Location data.
What runs
Section titled “What runs”| Service | What it does | Open to the internet |
|---|---|---|
caddy |
Gets and renews the TLS certificate, redirects HTTP to HTTPS, and passes requests to the API. | Ports 80 and 443 |
api |
Serves the dashboard, the tracker script, and the API. | No |
worker |
Runs uptime checks, evaluates alert rules, sends notifications, deletes expired data, joins session replays, checks the disk, and keeps the location data current. | No |
migrate |
Updates the database schemas, then stops. | No |
postgres |
PostgreSQL: accounts, projects, and settings. | No |
clickhouse |
ClickHouse: events, errors, traces, logs, and metrics. | No |
garage |
Garage, an S3-compatible object store for source maps and session replays. Optional. | No |
Download the release files
Section titled “Download the release files”-
Make a folder for the instance, and go into it:
Terminal window mkdir ottertrail && cd ottertrail -
Download the Compose file, the example settings, and the backup scripts from the latest release:
Terminal window curl -fLO https://github.com/ottertrail/ottertrail/releases/latest/download/compose.yamlcurl -fLO https://github.com/ottertrail/ottertrail/releases/latest/download/example.envcurl -fLO https://github.com/ottertrail/ottertrail/releases/latest/download/backup.shcurl -fLO https://github.com/ottertrail/ottertrail/releases/latest/download/restore.sh -
Make the scripts executable:
Terminal window chmod +x backup.sh restore.sh -
Make your settings file from the example, and make it private:
Terminal window cp example.env .envchmod 600 .env
Each release’s compose.yaml runs the image of that release, ghcr.io/ottertrail/ottertrail, for linux/amd64 and linux/arm64.
Fill in the settings
Section titled “Fill in the settings”The .env file holds the passwords and keys of your instance. Keep it private.
-
Set
OTTERTRAIL_DOMAINto your domain, withouthttps://:Terminal window OTTERTRAIL_DOMAIN=analytics.example.com -
Make a different random value for each of these six settings. Run the command one time for each setting:
Terminal window openssl rand -hex 32Put the values in
POSTGRES_PASSWORD,CLICKHOUSE_PASSWORD,AUTH_SECRET,OBJECT_STORE_SECRET_ACCESS_KEY,GARAGE_RPC_SECRET, andGARAGE_ADMIN_TOKEN. Use hex values: they are safe inside the database URL.GARAGE_ADMIN_TOKENis optional. With it, the dashboard shows how much Garage really stores, and the instance keeps a quota on Garage’s bucket. See Storage and warnings. -
Make the object store’s access key ID. Garage needs this form:
Terminal window printf 'GK%s\n' "$(openssl rand -hex 12)"Put the value in
OBJECT_STORE_ACCESS_KEY_ID.
The example settings turn on Garage, the object store on the same server, for source maps and session replays. To use Cloudflare R2, Amazon S3, or no object store, read Object storage before the first start.
Alert email is optional. See SMTP_URL in the configuration reference. Every other setting is in the same reference.
Start the instance
Section titled “Start the instance”Go on to The first start.