Logister Documentation Self-hosting
Documentation / Self-hosting

Run Logister yourself.

Use this page to plan the infrastructure footprint before you deploy. Start with the required app, database, Redis, and worker pieces, then add ClickHouse, S3-compatible archive storage, email, Turnstile, or analytics only when your install needs them.

Guide overview

Use this guide when you want to run the Logister app yourself.

When you self-host Logister, the baseline footprint is a Rails web process, a PostgreSQL database, Redis, and a Sidekiq worker. Optional services extend that baseline for scale, email, auth protection, and analytics.

Production quickstart

Follow this path before tuning optional services.

  1. Provision PostgreSQL, Redis, and a host that can run one web container plus one worker container.
  2. Pull a versioned image from ghcr.io/taimoorq/logister or docker.io/taimoorq/logister.
  3. Copy .env.sample to your deploy provider's secret/config store and set RAILS_ENV, RAILS_MASTER_KEY, DATABASE_URL, REDIS_URL, LOGISTER_PUBLIC_URL, and LOGISTER_ADMIN_EMAILS.
  4. Run ./bin/release before the new web container receives traffic.
  5. Run the web process with ./bin/thrust ./bin/rails server.
  6. Run a separate worker process with bundle exec sidekiq -C config/sidekiq.yml.
  7. Verify /up, sign-in, project creation, API key generation, Sidekiq startup, and one test event in the inbox.
  8. Add SMTP, ClickHouse, S3-compatible archive storage, Turnstile, or analytics only after the baseline install works.

Keep it boring first

A first production install does not need every optional service. Start with web, worker, PostgreSQL, Redis, HTTPS, and backups; add the rest when your operating model actually needs them.

Prerequisites

What you need before booting the app.

  • Ruby 4.0.5
  • PostgreSQL >= 14
  • Redis >= 7
  • Optional ClickHouse if you want a dedicated analytics store
  • Optional S3-compatible object storage if you want archive exports before pruning older hot telemetry

Infrastructure plan

Plan for the required baseline first.

A self-hosted Logister install needs the same core pieces whether you run it on Fly, Kamal, Docker, or another container platform. The optional services below are supported, but the app does not require all of them on day one.

InfrastructureWhat users get from itPlanning notes
Web app processRequiredServes the Logister UI, auth screens, project pages, public pages, and ingest endpoints.Runs Rails on Puma, usually from the provided Docker image. Put it behind HTTPS through your platform, load balancer, or reverse proxy.
PostgreSQLRequiredStores accounts, active and archived projects, API keys, events, error groups, occurrences, monitors, project sharing, and notification preferences.Set DATABASE_URL. Start with managed PostgreSQL if you want backups, upgrades, and point-in-time recovery handled for you.
RedisRequiredPowers the Rails cache and Sidekiq job queue.Set REDIS_URL. TLS Redis URLs such as rediss://... are supported by the Redis client.
Sidekiq worker processRequiredRuns asynchronous jobs, including optional ClickHouse event/span writes, Action Mailer delivery, first-occurrence error alerts, digest scheduling, and operator-run archive/prune tasks.Run a separate worker process with bundle exec sidekiq -C config/sidekiq.yml. Tune with SIDEKIQ_CONCURRENCY.
Persistent app storageOptionalKeeps any local Active Storage files if your deployment uses local disk storage.Normal event data lives in PostgreSQL. If you rely on local Active Storage, mount and back up /rails/storage.
S3-compatible archive storageOptionalStores compressed JSONL archive exports for older hot telemetry before you prune high-volume non-error events from PostgreSQL.Set ACTIVE_STORAGE_SERVICE=amazon plus the AWS/S3 variables from the deployment guide. Any S3-compatible provider can be used with endpoint/path-style overrides.
Outbound email / SMTPRecommendedEnables confirmation, password reset, system mail, first-occurrence error alerts, and daily or weekly project digests.The documented path uses Amazon SES SMTP variables, but any compatible SMTP endpoint can be provided through the same settings. Verify the sender domain and keep Sidekiq running for notification delivery.
ClickHouseOptionalAdds a dedicated analytics store for higher-volume event and span analysis.Keep it disabled until PostgreSQL-only operation is not enough. When enabled, load the schema, run the worker, and verify /health/clickhouse reports ready.
Cloudflare TurnstileOptionalAdds bot protection to auth flows.Enable when your public sign-in, sign-up, password, or confirmation forms need extra protection.
Cookie consent and analyticsOptionalLets operators add consent-gated Google Analytics or Cloudflare Web Analytics.Useful for public product pages. It is not required for the app to monitor your services.
Static docs hostingOptionalHosts your fork of these public docs separately from the app.The repo includes Cloudflare Pages docs, but your self-hosted app can also point to the canonical public docs host.

Start small

For a first production install, plan one web process, one Sidekiq worker, managed PostgreSQL, and managed Redis. Add S3 archive storage when you need export-before-prune retention, and add ClickHouse after you know your event volume and analytics needs.

Docker option

Run the app image with managed services or a Compose-backed single-host stack.

Release images are published to GitHub Container Registry at ghcr.io/taimoorq/logister and Docker Hub at docker.io/taimoorq/logister, with optional Quay mirrors when the release workflow is configured with Quay credentials. Self-hosters can pull a versioned image from any available registry and run separate web and worker containers against PostgreSQL and Redis. ClickHouse, S3-compatible archive storage, SMTP, Turnstile, and analytics remain external provider services configured through environment variables.

shell 
docker pull ghcr.io/taimoorq/logister:v2.3.0
docker pull docker.io/taimoorq/logister:v2.3.0
cp .env.sample .env.production
# Edit .env.production with production URLs and secrets before starting containers.

Each release publishes three image tags to the configured registries: the version tag such as v2.3.0, latest, and the short commit SHA. GHCR and Docker Hub are the default public registries; Quay can be enabled as an additional mirror. If you prefer to build from source, the repository still includes a production Dockerfile.

Docker shapeUse whenNotes
App image + managed servicesYou want durable production operations.Run web and worker containers from the Logister image, then point DATABASE_URL and REDIS_URL at managed PostgreSQL and Redis.
Single-host Compose stackYou want everything on one Docker host.Run web, worker, PostgreSQL, Redis, and optional ClickHouse together. Replace sample passwords, back up volumes, and put a reverse proxy or platform HTTPS layer in front of the web container.
Local Compose infrastructureYou are developing locally.The checked-in docker-compose.yml starts PostgreSQL, Redis, and ClickHouse for local work. Its default credentials are not production secrets.

A production Compose file should keep the app process and worker process separate. This shape shows the supported container split while leaving optional services disabled unless you configure them. Save it as docker-compose.selfhost.yml or adapt it to your own Compose file.

yaml 
services:
  web:
    image: ghcr.io/taimoorq/logister:v2.3.0
    env_file: .env.production
    command: ./bin/thrust ./bin/rails server -b 0.0.0.0 -p 80
    ports:
      - "3000:80"
    depends_on:
      - postgres
      - redis

  worker:
    image: ghcr.io/taimoorq/logister:v2.3.0
    env_file: .env.production
    command: bundle exec sidekiq -C config/sidekiq.yml
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: logister
      POSTGRES_PASSWORD: replace-me
      POSTGRES_DB: logister_production
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7
    volumes:
      - redisdata:/data

  clickhouse:
    image: clickhouse/clickhouse-server:24.8
    profiles: ["analytics"]
    volumes:
      - chdata:/var/lib/clickhouse

volumes:
  pgdata:
  redisdata:
  chdata:

For that single-host shape, set DATABASE_URL to the PostgreSQL service name, set REDIS_URL to the Redis service name, and enable ClickHouse only when you also start the analytics profile.

shell 
DATABASE_URL=postgresql://logister:replace-me@postgres:5432/logister_production
REDIS_URL=redis://redis:6379/0
LOGISTER_CLICKHOUSE_ENABLED=false
# When using the analytics profile:
# LOGISTER_CLICKHOUSE_ENABLED=true
# LOGISTER_CLICKHOUSE_URL=http://clickhouse:8123
shell 
docker compose -f docker-compose.selfhost.yml up -d postgres redis
docker compose -f docker-compose.selfhost.yml run --rm web ./bin/release
docker compose -f docker-compose.selfhost.yml up -d web worker
# Include optional ClickHouse:
docker compose -f docker-compose.selfhost.yml --profile analytics up -d clickhouse web worker

Production warning

The example above is a starting point, not a secret-safe file to paste unchanged into production. Replace passwords, keep RAILS_MASTER_KEY and provider tokens in a secret store, back up PostgreSQL and Redis volumes, and terminate HTTPS before exposing the app publicly.

Local quickstart

Start the app locally.

shell 
git clone https://github.com/taimoorq/logister.git
cd logister
cp .env.sample .env
bundle install
bin/rails db:prepare
bin/dev

Tip

bin/dev starts the Rails app and Tailwind watcher. Keep PostgreSQL and Redis available yourself, or use bin/dev-infra when you want Docker to start local infrastructure first. For production, use the .env.sample reference to decide which values belong in your deploy provider's secret store.

Docs map

Use the focused guides instead of one giant deployment checklist.

Local development

Boot, seed, and verify the app locally

Use this for bin/dev, Docker-backed infra, seeds, and local verification.

Read local development docs

Deployment config

Set production variables and provider config

Use this for the full .env.sample reference, S3 archive storage, Turnstile, analytics, Amazon SES, Cloudflare Pages docs variables, and deployment files.

Read deployment config docs

ClickHouse

Enable dedicated analytics storage

Use this when you want the optional ClickHouse path, schema readiness, raw event/span tables, and rollups.

Read ClickHouse docs

Deployment shapes

Choose the shape that matches your team and traffic.

ShapeBest forWhat to run
Single-node trialEvaluation, internal demos, and low-volume installsOne web process, PostgreSQL, Redis, and one worker. Keep backups on for the database.
Small production installA team monitoring a few servicesManaged PostgreSQL, managed Redis, one or more web processes, one Sidekiq worker, SMTP if users need account emails.
Growing event volumeMore apps, more logs, or heavier performance/event analysisScale web and worker processes separately, raise SIDEKIQ_CONCURRENCY carefully, monitor PostgreSQL size, archive older telemetry to S3-compatible storage before pruning, then add ClickHouse when analytics volume justifies it.
Public self-hosted instanceMulti-user deployments exposed to the internetHTTPS termination, SMTP, Turnstile, admin email allow-list, backups, log retention, and health checks for /up and /health/clickhouse if ClickHouse is enabled.

Verify deploy

Check the app before you start sending production traffic.

Deployment verification
Web app responds successfully
Background jobs can start
Project creation works
API key creation works
A test event appears in the project inbox