Install

Eventfox runs as one Docker image. The all-in-one setup starts it with its own private Postgres in one command. If you already run Postgres, including Supabase, point Eventfox at it and it keeps everything in its own schema.

What you need

• Docker with Docker Compose v2 (docker compose version works). Docker Desktop on Windows or Mac is fine.
• About 1 GB of free memory for Eventfox, plus whatever your Postgres uses.
• Postgres 15 or later. The all-in-one setup includes one. The other path uses yours.
• For a public site: a domain name pointing at the machine, and ports 80 and 443 open if you use the bundled HTTPS.

All-in-one: Eventfox with its own Postgres

One command starts Eventfox and a private Postgres 17. The database has no port open to the outside; only Eventfox can reach it.

On Linux or Mac:

mkdir eventfox && cd eventfox
curl -fsSLO https://eventfox.dev/install/docker-compose.yml
curl -fsSLO https://eventfox.dev/install/Caddyfile
curl -fsSLO https://eventfox.dev/install/init.sh
curl -fsSLO https://eventfox.dev/install/init.sql
curl -fsSL https://eventfox.dev/install/env.example -o .env

On Windows, in PowerShell:

mkdir eventfox; cd eventfox
foreach ($f in "docker-compose.yml","Caddyfile","init.sh","init.sql") { Invoke-WebRequest "https://eventfox.dev/install/$f" -OutFile $f }
Invoke-WebRequest "https://eventfox.dev/install/env.example" -OutFile ".env"

Open .env in a text editor and set:

Then start it:

docker compose up -d

The first start downloads the image, which takes about a minute. Open your APP_URL. You should see the Admin account screen.

Automatic HTTPS

If the machine has a public IP address and your domain's DNS already points at it, Caddy can get and renew a certificate for you. In .env set:

EVENTFOX_DOMAIN=eventfox.example.com
APP_URL=https://eventfox.example.com
TRUST_PROXY=true

Then start with the https profile: docker compose --profile https up -d. Only set TRUST_PROXY=true when Eventfox really is behind a proxy you control.

Your own Postgres

Any Postgres 15 or later works: Supabase, a managed database or your own server. Eventfox keeps everything in a schema called eventfox, owned by a login called eventfox_app that has no other rights, so it can share a database with other apps without touching them. It needs no extensions.

Run this as a user who can create roles. Use a long random password, letters and digits only:

create role eventfox_app with login password 'PUT-A-LONG-RANDOM-PASSWORD-HERE' connection limit 10;
grant eventfox_app to current_user;
create schema eventfox authorization eventfox_app;
alter role eventfox_app set search_path = eventfox;
alter role eventfox_app set statement_timeout = '30s';

Your connection string looks like this. Keep ?sslmode=require for any database reached over the internet:

postgresql://eventfox_app:YOUR-PASSWORD@HOST:5432/DATABASE?sslmode=require

Then start the published image with your connection string. Put these two lines in a file called eventfox.env:

DATABASE_URL=postgresql://eventfox_app:YOUR-PASSWORD@HOST:5432/DATABASE?sslmode=require
APP_URL=http://localhost:3000

and run:

docker run -d --name eventfox --restart unless-stopped -p 3000:3000 --env-file eventfox.env ghcr.io/rbell317/eventfox:latest

Migrations run when Eventfox starts. To put HTTPS in front, use any reverse proxy you like (Caddy, nginx, Tailscale Funnel) and add TRUST_PROXY=true to the file. Set APP_URL to the public address.

First sign-in

1. Open your APP_URL. The first visit shows Admin account: choose an email and a password of at least 10 characters. That account is the administrator.
2. Name your organisation and create your first project: a name, the domain it will run on (for example example.com), and a privacy mode. Standard and Privacy modes explains the two.
3. The Install screen shows your script tag. Keep it open for the next step.

Check it is running

Open /api/health on your address. {"status":"ok","database":"connected",…} means Eventfox is up and can reach Postgres. Logs are in docker compose logs eventfox --tail 50; they never contain visitor IP addresses, keys or event contents.

Backups

Eventfox doesn't back itself up. Take a backup before every upgrade, and on a schedule if the data matters. Everything Eventfox stores is in the eventfox schema, so that is all you need to save.

With the all-in-one setup (Linux or Mac):

docker compose exec -T postgres pg_dump -U eventfox_app -d eventfox --schema=eventfox --format=custom > eventfox-backup.dump

With your own Postgres, run pg_dump against it with the same --schema=eventfox --format=custom options. Copy the file somewhere else: a backup next to the data it protects is not a backup.

Upgrading

1. Back up first.
2. With the all-in-one setup, run docker compose pull, then docker compose up -d. If you set EVENTFOX_VERSION, change it to the new version first. With docker run, pull the new image, then stop, remove and start the container again with the same command.
3. Migrations run when Eventfox starts. Check /api/health says ok, and read the changelog for anything that needs care.