Self-hosting guide

Run Publistic on your own infrastructure. Full control over your data, unlimited pageviews, unlimited sites. Free forever.

Requirements

Docker and Docker Compose installed on your server
4GB+ RAM minimum (ClickHouse needs memory for analytical queries)
50GB disk minimum (analytics data grows over time; plan accordingly for your traffic volume)
A domain name pointed at your server (for SSL via Caddy)

Installation

Clone the repository

git clone https://github.com/nicholasgriffintn/publistic.git
cd publistic

Copy the environment file
```
cp .env.example .env
```
Edit .env and set your domain, database passwords, and JWT secret.
Start all services
```
docker compose up -d
```
This starts all services in the background.
Initialize the ClickHouse tables
```
docker compose exec clickhouse clickhouse-client \
  --multiquery < clickhouse/init.sql
```
This creates the analytics tables. Only needed on first run.
Register your first user
Open https://your-domain.com/register in your browser and create your account.

✅

Caddy handles SSL automatically. Point your domain's A record to your server's IP address, and Caddy will provision and renew Let's Encrypt certificates for you.

Architecture

Publistic runs as a set of Docker containers managed by Docker Compose:

ClickHouse

The analytics database. Stores all pageview, engagement, and Web Vitals data. Optimized for fast analytical queries over large datasets.

PostgreSQL

Account database. Stores user accounts, site configurations, API keys, and settings. Small footprint.

Ingest

The event collection service. Receives pageview and engagement events from the tracker script, enriches them (GeoIP, device parsing, referrer classification), and writes to ClickHouse in batches.

API

The dashboard backend. Serves the dashboard frontend, handles authentication, and runs all analytical queries against ClickHouse.

Caddy

Reverse proxy and SSL termination. Routes requests to the appropriate service and handles automatic HTTPS certificate provisioning.

Configuration

All configuration is done through environment variables in the .env file. Key settings:

# Your domain (used by Caddy for SSL)
DOMAIN=analytics.yoursite.com

# Database passwords
POSTGRES_PASSWORD=your-secure-password
CLICKHOUSE_PASSWORD=your-secure-password

# JWT secret for authentication
JWT_SECRET=your-random-secret-string

# Optional: GeoIP database path
GEOIP_DB=/data/GeoLite2-City.mmdb

Updating

To update to the latest version:

git pull
docker compose pull
docker compose up -d

ClickHouse migrations are applied automatically on startup when needed.

Backups

Back up both databases regularly:

PostgreSQL — standard pg_dump for account data
ClickHouse — use ClickHouse's built-in backup functionality or snapshot the data directory

⚠️

ClickHouse data can grow significantly depending on your traffic volume. Monitor disk usage and plan storage accordingly. A site with 1M pageviews/month typically uses around 5-10GB of ClickHouse storage per year.

Troubleshooting

Services not starting

Check container logs to identify the issue:

docker compose logs -f

ClickHouse out of memory

ClickHouse needs memory for analytical queries. If you see OOM errors, increase the server's RAM or adjust ClickHouse's memory limits in the Docker Compose configuration.

SSL certificate issues

Make sure your domain's DNS A record points to the server's IP address. Caddy needs to be reachable on ports 80 and 443 for certificate provisioning. Check Caddy logs if certificates aren't being issued.