Configuration

TideMeter is configured through environment variables. This page documents all available options.

Database Migrations

Migrations run automatically when a new image starts — there is no separate migrate command. This applies to Docker, docker compose, and Kubernetes alike, so upgrading is just docker pull (or rolling a new image tag) and restarting the container.

What happens on boot:

1. PayloadCMS schema is applied:
   • Development (NODE_ENV != "production"): Drizzle “push” mode diffs the collections against the database and applies DDL automatically. Fast iteration, no migration files required.
   • Production (NODE_ENV == "production"): versioned migrations under apps/web/src/migrations/ are applied via payload.db.migrate() and tracked in the payload_migrations table. Already-applied migrations are skipped on subsequent boots.
2. The analytics package applies any pending SQL migrations from packages/analytics/drizzle/ against ANALYTICS_DATABASE_URL (or ClickHouse migrations from packages/analytics/clickhouse/ when ANALYTICS_DB_TYPE=clickhouse). A Postgres advisory lock serializes concurrent runners, so rolling deploys with multiple replicas are safe.
3. If DEMO_MODE=true, demo data is seeded (idempotent — see Demo Mode below).

If any step fails, the pod fails its readiness probe and Kubernetes halts the rollout — the previous image keeps serving traffic. There is no silent partial-upgrade state.

Init is triggered by any route that imports the Payload config — including /api/health, which is hit by the readiness/startup probes. The database user only needs CREATE privileges; no manual SQL is required.

Overrides

Adding a schema change (for contributors)

In dev (NODE_ENV=development), changes to Payload collections are picked up instantly via push. To ship the change in a production image:

cd apps/web && pnpm exec payload migrate:create

Commit the generated file under apps/web/src/migrations/ together with the updated index.ts. For analytics tables, add a numbered .sql file under packages/analytics/drizzle/ and update the Drizzle schema in packages/analytics/src/schema/tables.ts.

Environment Variables

Required

Application

Analytics Database

Optional

Email (optional)

TideMeter uses email only for password reset and account verification. If you don’t need those flows (single-user or private deployment), skip this entirely — Payload will print a one-time WARN: No email adapter provided on startup and write any outgoing email to stdout. Login, first-user creation (/admin/create-first-user) and password change from /admin/account all work without email.

Two backends are supported. They are picked in this order, so setting both is unnecessary:

1. Resend (RESEND_API_KEY set) — Resend’s HTTP API via @payloadcms/email-resend. No SMTP port required, lightweight, recommended if you don’t already run a mail server.
2. SMTP / Nodemailer (SMTP_HOST set) — works with any SMTP provider: your own Postfix, Gmail, SendGrid, Mailgun, Postmark, AWS SES, etc.

Option 1 — Resend

Option 2 — SMTP (Nodemailer)

Provider-specific SMTP_USER conventions:

Buffer Settings

The event buffer can be tuned via code constants in apps/web/src/lib/ingestion/buffer.ts:

Example .env File

# Database (PostgreSQL for PayloadCMS)
DATABASE_URL=postgresql://postgres:postgres@localhost:5480/tidemeter

# PayloadCMS
PAYLOAD_SECRET=a-very-long-and-random-secret-key-32-chars-minimum

# Privacy
SESSION_SALT_SECRET=another-random-secret-for-visitor-hashing

# Application
NEXT_PUBLIC_APP_URL=http://localhost:3700
NODE_ENV=development

# Analytics database (defaults to PostgreSQL)
ANALYTICS_DB_TYPE=postgresql
# ANALYTICS_DATABASE_URL=postgresql://postgres:postgres@localhost:5480/tidemeter

# For ClickHouse analytics
# ANALYTICS_DB_TYPE=clickhouse
# CLICKHOUSE_URL=http://localhost:8124
# CLICKHOUSE_DATABASE=tidemeter_analytics
# CLICKHOUSE_USER=default
# CLICKHOUSE_PASSWORD=

# For SQLite analytics
# ANALYTICS_DB_TYPE=sqlite
# ANALYTICS_SQLITE_PATH=./data/analytics.db

# Optional: GeoIP
# GEOIP_DB_PATH=/path/to/GeoLite2-City.mmdb

# Optional: Demo mode (seeds [email protected] / demodemo + sample data)
# DEMO_MODE=true

Demo Mode

Set DEMO_MODE=true to start TideMeter pre-populated with a demo user and sample analytics data. Useful for evaluation, screenshots, and public sandboxes.

On first startup the container will:

• Create the demo user [email protected] with password demodemo
• Create a sample website (demo.example.com)
• Generate ~1500 analytics events spanning the last 90 days
• Create three example funnels

Seeding is idempotent — it only runs when the demo data is missing, so restarts and upgrades are safe. To re-seed, wipe the database volume.

# Compose overlay (PostgreSQL + DEMO_MODE=true)
docker compose -f docker/docker-compose.yml -f docker/docker-compose.demo.yml up -d
 
# Or with `docker run`
docker run -d -p 3700:3000 \
  -e DATABASE_URL="postgresql://..." \
  -e PAYLOAD_SECRET="..." \
  -e SESSION_SALT_SECRET="..." \
  -e DEMO_MODE=true \
  tidemeter/tidemeter:latest

The public instance at demo.tidemeter.com  runs with this flag enabled.

Docker Configuration

PostgreSQL Only

docker compose -f docker/docker-compose.yml up -d

Default ports:

• Application: 3700
• PostgreSQL: 5480

PostgreSQL + ClickHouse

docker compose -f docker/docker-compose.yml -f docker/docker-compose.ch.yml up -d

Default ports:

• Application: 3700
• PostgreSQL: 5480
• ClickHouse HTTP: 8124
• ClickHouse Native: 9001

PayloadCMS Configuration

The PayloadCMS configuration is in apps/web/src/payload.config.ts. Key settings:

• Collections: Users, Teams, TeamMembers, Websites, ApiKeys, Funnels
• Auth: Cookie-based authentication with payload-token HTTP-only cookie
• Admin: Available at /admin
• REST API: Available at /api/{collection-slug}
• Editor: Lexical rich-text editor

Tailwind CSS 4

TideMeter uses Tailwind CSS 4 with the CSS-first configuration approach:

• Theme is defined in apps/web/src/app/globals.css using @theme
• No tailwind.config.js file
• PostCSS plugin: @tailwindcss/postcss

TypeScript

TypeScript strict mode is enabled across all packages via @tidemeter/tsconfig. Key conventions:

• Target: ES2022, module: ESNext, moduleResolution: bundler
• No any types (unless absolutely necessary)
• Named exports for all modules
• No .js extensions in imports (Turbopack doesn’t resolve them)
• noUncheckedIndexedAccess enabled