Installation

eodia analytics needs only one service alongside it: PostgreSQL (17 recommended), which holds the configuration, the raw data and the views read by eodia insights. No message broker, no separate analytical database. The repository provides two Compose files: docker-compose.yml for development, docker-compose.prod.yml for production.

For development

Prerequisites: Node.js 22 or later, pnpm 9 and Docker.

git clone https://github.com/eodia/analytics.git && cd analytics
docker compose up -d                            # PostgreSQL, on port 55436
pnpm install
pnpm --filter @eodia-analytics/tracker dev      # the script, rebuilt into apps/tracker/dist/a.js
pnpm --filter @eodia-analytics/api dev          # the API, on port 4600 (worker included)
pnpm --filter @eodia-analytics/web dev          # the interface, on port 3600

Open http://localhost:3600 and sign in with admin@eodia.local / eodia-analytics. On first start, a demo instance is created: the fictional shop Maison Arvor (in measurement cookie mode) and the Arvor blog (cookieless). See Getting started.

Service	Address	Role
Interface	http://localhost:3600	Next.js; relays /api/* to the API
API	http://localhost:4600	REST /api/v1, authentication, /a.js, /collect
Test page	http://localhost:4600/demo	a page carrying the demo site’s tag
PostgreSQL	localhost:55436	the analytics database (schemas public, collect, analytics)

All ports are published on 127.0.0.1 only. To have something to analyze in insights:

pnpm demo:traffic            # a few weeks of visits, sources, events and clicks
pnpm demo:traffic --live     # then a few visits per minute, for the Verification tab

The insights ports are taken

eodia analytics and eodia insights run side by side on the same machine: analytics uses ports 3600 (web), 4600 (API) and 55436 (PostgreSQL), and its session cookie has a different name from the insights one.

In production

A single image, built by the repository’s Dockerfile, contains the API (with the script), the interface and the worker. docker-compose.prod.yml puts it together with PostgreSQL and Caddy, which obtains the HTTPS certificate.

Prerequisites: a server with Docker and Compose v2, a domain name pointing to it, and ports 80 and 443 open. The stack is lightweight: a few hundred megabytes of memory are enough to start with; it is PostgreSQL that grows with traffic.

1. The .env file

Next to docker-compose.prod.yml, create a .env file:

DOMAIN=stats.example.com
SECRET_KEY=<openssl rand -hex 32>
DB_PASSWORD=<a strong password>
READER_PASSWORD=<the password of the role read by eodia insights>

Variable	Role
DOMAIN	the public domain; Caddy obtains its Let’s Encrypt certificate
SECRET_KEY	64 hexadecimal characters: encrypts the site secrets
DB_PASSWORD	the password of the application’s PostgreSQL
READER_PASSWORD	optional: without it, the eodia_analytics role exists but cannot connect

The other variables — collection address, connection to insights, SSO, email — are described in Environment variables.

The instance key

Keep SECRET_KEY somewhere safe, together with the database backups: without it, the site secrets (which sign signed-in visitors) can no longer be read.

2. Start

docker compose -f docker-compose.prod.yml up -d --build

On first start, the API applies the migrations: the three schemas, the analytics views and their comments, the read role. Then open https://stats.example.com: the first screen creates the administrator account.

The first visit creates the administrator

As long as no account exists, the first person to open the interface becomes administrator. Create this account as soon as the instance is reachable.

What Caddy publishes

Path	Service
/a.js, /p.js	the API: the script, and the preview mode overlay
/collect, /collect/*	the API: the public collection endpoint and server-side collection
/api/*	the API: REST and authentication
everything else	the interface

Caddy keeps no access log: it would retain the visitors’ IP addresses, which the application never stores.

What next?

• Getting started: create a site, paste the tag, see “Received ✓”.
• Docker: the image, its roles and the production services.
• Connecting eodia insights: the PostgreSQL source and the read role.