TideMeter
Skip to Content
Getting Started

Getting Started

This guide walks you through setting up TideMeter from scratch. Pick the option that fits your workflow — Docker if you just want to run it, or build from source if you want to hack on it.

Installation

There are two ways to get started: using the pre-built Docker image (quickest) or building from source.

Option A: Docker Image (Quickest)

All you need is Docker installed on your machine or server. No Node.js, no pnpm, no build step.

You’ll also need a PostgreSQL 16+ database. You can run one with Docker too (see below) or use a managed instance.

Start PostgreSQL with Docker (if you don’t have one)

docker run -d \
  --name tidemeter-db \
  -p 5432:5432 \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=tidemeter \
  postgres:16-alpine

Pull and run TideMeter

Pull the image from Docker Hub :

docker pull tidemeter/tidemeter:tidemeter-v0.1.3

Run with a connected PostgreSQL database:

docker run -d \
  -p 3700:3700 \
  -e DATABASE_URL="postgresql://postgres:[email protected]:5432/tidemeter" \
  -e PAYLOAD_SECRET="your-secret-key-minimum-32-characters" \
  -e NEXT_PUBLIC_APP_URL="http://localhost:3700" \
  tidemeter/tidemeter:tidemeter-v0.1.3

Skip to First Steps After Setup once it’s running.

Option B: Build from Source

This option is for developers who want to contribute or customize TideMeter.

Prerequisites:

  • Node.js 22+ — Download from nodejs.org 
  • pnpm 9+ — Install with npm install -g pnpm
  • Docker (recommended) — For running database containers locally
  • PostgreSQL 16+ — Required for app data (or use the Docker container above)

1. Clone the Repository

git clone https://github.com/tidemeter/tidemeter.git
cd tidemeter

2. Install Dependencies

pnpm install

This installs all dependencies across the monorepo using pnpm workspaces.

3. Configure Environment

cp .env.example .env

Edit .env with your database connection details:

# PostgreSQL connection (required)
DATABASE_URL=postgresql://postgres:postgres@localhost:5480/tidemeter

# App settings
NEXT_PUBLIC_APP_URL=http://localhost:3700
PAYLOAD_SECRET=your-secret-key-here-minimum-32-characters
SESSION_SALT_SECRET=another-random-secret-for-hashing

# Analytics database (defaults to PostgreSQL)
ANALYTICS_DB_TYPE=postgresql
# ANALYTICS_DB_TYPE=clickhouse
# CLICKHOUSE_URL=http://localhost:8124
# CLICKHOUSE_DATABASE=tidemeter_analytics

4. Start the Database

Using Docker (recommended):

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

This starts PostgreSQL on port 5480.

If you want ClickHouse for analytics too:

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

5. Start the Dev Server

pnpm dev

Open http://localhost:3700  in your browser.

First Steps After Setup

Database Migrations Run Automatically

You do not need to run any migration command. Migrations run on the first request that initializes PayloadCMS after a new container starts — typically the Kubernetes readiness/startup probe calling /api/health. On that first call, TideMeter:

  1. Connects to PostgreSQL using DATABASE_URL.
  2. Applies the PayloadCMS schema:
    • In development (NODE_ENV != "production"), Drizzle “push” mode auto-syncs collections to the database.
    • In production (NODE_ENV == "production"), versioned migrations under apps/web/src/migrations/ run via payload.db.migrate() and are tracked in payload_migrations.
  3. The analytics package applies pending SQL migrations from packages/analytics/drizzle/ (or ClickHouse migrations when ANALYTICS_DB_TYPE=clickhouse). A Postgres advisory lock keeps multi-replica rollouts safe.
  4. If DEMO_MODE=true, demo data is seeded.

If any of these steps fails the pod fails its readiness probe and Kubernetes (or docker compose) holds back the rollout. The database user just needs CREATE privileges.

Heads up: because init is lazy, the database stays empty between kubectl apply and the first /api/health call. If you check the DB the instant the pod starts, you’ll see no tables — that’s normal. Wait for the pod to report Ready (or curl /api/health once) and the schema will be in place.

When you upgrade by pulling a newer image, the same flow runs again — pending migrations are applied, already-applied ones are skipped. See Configuration → Database Migrations for advanced overrides.

Create Your Account

  1. Navigate to http://localhost:3700/admin 
  2. On a fresh database with no users, PayloadCMS automatically redirects you to /admin/create-first-user — fill in an email and password to create the initial admin. No SMTP server is required for this step.
  3. Log in to access the dashboard.

You can change your password later from /admin/account. Additional users are created from the admin panel by an existing admin.

Forgot password? That flow requires email delivery. See Configuration → Email — TideMeter supports both Resend (HTTP API) and SMTP, and email is optional. You only need it if you actually plan to use password-reset links.

Add Your First Website

  1. Go to Settings → Websites
  2. Click Add Website
  3. Enter your website’s name and domain
  4. Copy the tracking script snippet

Install the Tracker

Add the tracking script to your website’s HTML, just before the closing </body> tag:

<script
  defer
  data-website-id="your-website-id"
  src="https://your-tidemeter-instance.com/t.js"
></script>

That’s it! You’ll start seeing analytics data within seconds.

Build for Production

pnpm build
pnpm start

For deployment instructions, see the Deployment guide.

Individual Package Commands

Build or test specific packages:

# Build only the web app
pnpm --filter @tidemeter/web build
 
# Build only the tracker
pnpm --filter @tidemeter/tracker build
 
# Run analytics package tests
pnpm --filter @tidemeter/analytics test
 
# Run all tests
pnpm test

Next Steps

IntroductionArchitecture