Documentation

Install Velotrak on Linux

Updated 17 Nov 2026

On a Linux server, as root, run curl -fsSL https://velotrak.app/install.sh | sudo bash. The script installs Docker if needed, starts PostgreSQL and ClickHouse on localhost, and runs Velotrak as a systemd service.

Run the installer

The public script is velotrak.app/install.sh. Release binaries are on GitHub.

curl -fsSL https://velotrak.app/install.sh | sudo bash

The script refuses to run when you are not root, when the OS is not Linux, or when systemd or curl is missing. It accepts x86_64 (amd64) and aarch64 (arm64). On a fresh install, RAM under 3500 MB produces a warning that names 2 vCPU / 4 GB as the minimum. That warning does not stop the script, and the script does not check the CPU count. The site recommends 4 vCPU / 8 GB.

A fresh install does three things:

  1. If Docker is missing, it installs Docker from get.docker.com, then starts PostgreSQL and ClickHouse with Docker Compose under /opt/velotrak/stack. Postgres listens on 127.0.0.1:15432. ClickHouse listens on 127.0.0.1:19000. Passwords are generated into that directory’s .env.
  2. It downloads the release binary for this machine from the public velotrak/velotrak repository and checks SHA-256 against checksums.txt.
  3. It writes /opt/velotrak/velotrak.env, installs a velotrak systemd service that runs /opt/velotrak/velotrak as user velotrak, and waits until http://127.0.0.1:8080/healthz returns. The default HTTP port is 8080. Data goes to /var/lib/velotrak.

The binary also tries to download a DB-IP city lite database into /var/lib/velotrak/geoip. If that download fails, the script warns that country, region, and city stay empty until a database is placed there.

Choose a version or your own databases

Pin a release tag that exists on the releases page:

curl -fsSL https://velotrak.app/install.sh | sudo VELOTRAK_VERSION=v1.2.3 bash

Replace v1.2.3 with a real tag. To skip Docker and use databases you already run:

curl -fsSL https://velotrak.app/install.sh | sudo VELOTRAK_EXTERNAL_DB=1 bash

The script then tells you to set VELOTRAK_PG_DSN and VELOTRAK_CH_DSN in /opt/velotrak/velotrak.env and start the service with systemctl start velotrak. Migrations are compiled into the binary. velotrak migrate applies them without starting the server. To install a binary you already have: sudo ./install.sh ./velotrak.

Open the setup wizard

Until the first admin exists, the process writes a one-time token to /var/lib/velotrak/setup.token (mode 0600) and the installer prints a URL of the form http://<host>:8080/admin/#setup=<token>. POST /api/setup without that token returns 403. You can set VELOTRAK_SETUP_TOKEN yourself (at least 16 characters) before the first start. The file is removed after the admin account is created.

The wizard is welcome, environment check, admin account, general settings, license (skippable), then done. The environment check reports the app, PostgreSQL, ClickHouse, GeoIP, resources, and ports. General settings save a timezone and a currency of USD, CNY, EUR, GBP, or JPY. The password is 8 characters to 72 bytes. Activating a license can wait; see plans.

The admin path defaults to /admin/. Set VELOTRAK_ADMIN_HOST to one or more hostnames when the admin should not answer on the tracking domain. The operator notes say that an operator who can upload landers, or a third-party lander, should not share an origin with the admin.

Domains and TLS

Register every hostname you send traffic to on the Domains page. VELOTRAK_TLS_DOMAIN is treated as a tracking domain and turns on the built-in ACME client, which binds 443 and issues certificates for that name and for domains you add in the admin. Point DNS at the server, then use Check on the domain. Check is an external probe.

For a certificate you already have, set VELOTRAK_TLS_CERT_FILE and VELOTRAK_TLS_KEY_FILE. The generated env file includes commented examples. If a CDN other than Cloudflare sits in front, put its ranges in VELOTRAK_TRUSTED_PROXIES so the click’s IP is the visitor, not the proxy. Cloudflare’s own ranges are already compiled in. Orange-cloud TLS, caching, and the paths that must stay untouched are in Cloudflare. Unregistered hosts do not get a normal lander origin: the server sandboxes those responses, and a pixel on that host cannot use the tracking cookies.

Upgrade

Run the same command again. The previous binary is kept as /opt/velotrak/velotrak.old. The env file, generated passwords, and data directory are left in place. If the service does not answer, journalctl -u velotrak -n 50 --no-pager is what the installer tells you to read.

Stop or remove it

The repository does not ship an uninstall script. systemctl disable --now velotrak stops the service the unit file installed at /etc/systemd/system/velotrak.service. The installer created /opt/velotrak (binary, env, and the Compose stack) and /var/lib/velotrak (data, master.key, certificates, backups). Deleting those directories deletes the local databases’ Docker files and the tracker data, including backups. Copy master.key first if you still need to decrypt stored integration credentials. See backup.

Plan limits after install are on the pricing page.