Installation

Self-hosted only - Cloud users skip this: cloud.openwebtrack.one → create site → paste <script>.

Time: ~3 minutes · Needs: Docker + 1 domain or localhost

OpenWebTrack is one image + Postgres. Pick one path:

Option A - Docker Compose (recommended)

1. Create compose.yml:

services:
    app:
        image: ghcr.io/openwebtrack/openwebtrack:latest
        container_name: openwebtrack
        restart: unless-stopped
        ports:
            - 8424:8424
        environment:
            - DATABASE_URL=postgres://postgres:STRONG_PASSWORD@db:5432/openwebtrack
            - ORIGIN=http://localhost:8424
            - AUTH_SECRET=STRONG_SECRET
            - DISABLE_REGISTER=false
            # - AUTH_GOOGLE_CLIENT_ID=
            # - AUTH_GOOGLE_CLIENT_SECRET=
            # Optional: Email configuration
            # - CRON_SECRET=STRING
            # - SENDER_EMAIL=openwebtrack@yourdomain.com
            # - RESEND_API_KEY=STRING
            # - MAILEROO_API_KEY=STRING
            # - SMTP_HOST=smtp.example.com
            # - SMTP_PORT=587
            # - SMTP_USER=STRING
            # - SMTP_PASS=STRING
        depends_on:
            - db

    db:
        image: postgres:17-alpine
        container_name: openwebtrack-db
        restart: unless-stopped
        ports:
            - 5432:5432
        environment:
            - POSTGRES_USER=postgres
            - POSTGRES_PASSWORD=STRONG_PASSWORD
            - POSTGRES_DB=openwebtrack
        volumes:
            - postgres_data:/var/lib/postgresql/data

    # Optional: Weekly summary emails
    # cron:
    #     image: alpine:latest
    #     command: >
    #         sh -c "echo '0 9 * * 1 curl -s -H "Authorization: Bearer CRON_SECRET" http://app:8424/api/cron/weekly-summary' > /etc/crontabs/root && crond -f -L /dev/stdout"
    #     depends_on:
    #         - app

volumes:
    postgres_data:

2. Run:

docker compose up -d && docker compose logs -f

3. Open http://localhost:8424 → create admin account → Add website → copy the <script> tag into your site <head>.

4. Security: After first account, lock registration:

# in compose.yml set DISABLE_REGISTER=true then:
docker compose up -d

Environment Variables

Required

Optional

Post-install check

Visit your site once → dashboard Realtime should show 1 visitor. Check DevTools → Network → script.js 200.

Set your domain

Set ORIGIN=https://analytics.yourdomain.com and point DNS → then use that script URL on your sites.

Verification

Once installed, you can verify the installation:

1. Visit your OpenWebTrack URL
2. You should see the login/register page
3. Create an account
4. Add a website and get your tracking script

Troubleshooting

Port Already in Use

If port 8424 is taken, change the port mapping in compose.yml:

ports:
    - 3000:8424 # Use port 3000 instead

Database Connection Issues

Ensure the database container is healthy before the app starts:

docker compose ps
docker compose logs db

Email Not Working

Check your email provider configuration and ensure the cron service is running for weekly summaries.