Skip to content
OpenStatus openstatus

Self-Host the OpenStatus Status Page (Lightweight)

Problem

Section titled “Problem”

You want a status page to communicate incidents and maintenance to your users, but you don’t need automated monitoring, analytics, or alerting. You may already have your own monitoring tools, or you simply want a lightweight way to manage your public-facing status page.

Solution

Section titled “Solution”

OpenStatus provides a lightweight Docker Compose setup that runs only 4 services: a database, a one-shot migration runner, the dashboard, and the status page. This is ideal for teams who only want to self-host the status page without monitoring, or for teams that manage incidents manually using external monitoring tools.

Lightweight vs Full

Section titled “Lightweight vs Full”

The lightweight stack strips away all monitoring infrastructure. Here’s what each version includes:

FeatureFullLightweight
Status pageYesYes
DashboardYesYes
Database (libSQL)YesYes
Automated monitoringYesNo
Analytics & charts (Tinybird)YesNo
API serverYesNo
Private location probesYesNo

If you need automated monitoring, follow the full self-hosting guide instead.

Prerequisites

Section titled “Prerequisites”
  • Docker and Docker Compose installed
  • Git installed
  • Command line experience

Step-by-step guide

Section titled “Step-by-step guide”

Part 1: Initial Setup and Service Launch

Section titled “Part 1: Initial Setup and Service Launch”

  1. Clone the Repository

    Get the latest version of openstatus:

    Terminal window
    git clone https://github.com/openstatushq/openstatus
    cd openstatus

  2. Configure Your Environment

    Copy the example environment file. This is a simplified version of the full configuration, with only the variables relevant to the status page and dashboard.

    Terminal window
    cp .env.docker-lightweight.example .env.docker

    Open .env.docker in a text editor. You must set values for the following variables:

    • AUTH_SECRET — required for authentication. Generate a value with:
      Terminal window
      openssl rand -base64 32
    • RESEND_API_KEY — required for magic link login emails. Get a key from resend.com.

    Optionally, you can configure GitHub or Google OAuth providers by filling in the AUTH_GITHUB_* or AUTH_GOOGLE_* variables in the same file.

  3. Build and Start Services

    Use Docker Compose to build and run all services in the background:

    Terminal window
    docker compose -f docker-compose-lightweight.yaml up -d

    The first build takes several minutes as it compiles the Next.js applications. Subsequent starts are much faster.

    Check the status of the services:

    Terminal window
    docker compose -f docker-compose-lightweight.yaml ps

    Wait until all services show as healthy before proceeding. The db-migrate service will show as exited — this is expected, as it runs once and stops.

Part 2: Application Configuration

Section titled “Part 2: Application Configuration”

  1. Access the Applications

    • Dashboard: http://localhost:3000
    • Status Page: http://localhost:3001

    Log in to the dashboard using email authentication (magic link). This will create your account and workspace.

  2. Set Workspace Limits

    Because this is a self-hosted instance, you need to manually set the feature limits for your workspace directly in the database. The following command updates the limits for the workspace with id = 1:

    Terminal window
    curl -X POST http://localhost:8080/ -H "Content-Type: application/json" \
      -d '{"statements":["UPDATE workspace SET limits = '\''{\\"monitors\\":100,\\"periodicity\\":[\\"30s\\",\\"1m\\",\\"5m\\",\\"10m\\",\\"30m\\",\\"1h\\"],\\"multi-region\\":true,\\"data-retention\\":\\"24 months\\",\\"status-pages\\":20,\\"maintenance\\":true,\\"status-subscribers\\":true,\\"custom-domain\\":true,\\"password-protection\\":true,\\"white-label\\":true,\\"notifications\\":true,\\"sms\\":true,\\"pagerduty\\":true,\\"notification-channels\\":50,\\"members\\":\\"Unlimited\\",\\"audit-log\\":true,\\"private-locations\\":true}'\'' WHERE id = 1"]}'

    You can find your workspace ID by querying the database:

    Terminal window
    curl -X POST http://localhost:8080/ -H "Content-Type: application/json" \
      -d '{"statements":["SELECT id, name FROM workspace"]}'

  3. Create Your Status Page

    In the dashboard, create a new status page, add components for the services you want to display, and publish it. Your status page will be available at http://localhost:3001.

Service architecture

Section titled “Service architecture”
ServiceContainerHost PortPurpose
libsqlopenstatus-libsql8080Database (HTTP API)
db-migrateopenstatus-db-migrate—One-shot database migration (exits after completion)
dashboardopenstatus-dashboard3000Admin interface
status-pageopenstatus-status-page3001Public status page

Data persistence

Section titled “Data persistence”

All application data is stored in the openstatus-libsql-data Docker volume.

  • docker compose down preserves your data.
  • docker compose down -v destroys the volume and all data.

For production use, back up this volume regularly.

Troubleshooting

Section titled “Troubleshooting”

Containers won’t start: Check the logs for the failing service:

Terminal window
docker compose -f docker-compose-lightweight.yaml logs <service-name>

Magic link emails not arriving: Verify that RESEND_API_KEY is set correctly in .env.docker.

Dashboard shows errors on first load: The db-migrate service may still be running. Check its status:

Terminal window
docker compose -f docker-compose-lightweight.yaml ps

Port conflicts: If ports 3000, 3001, or 8080 are already in use on your machine, update the host port mappings in docker-compose-lightweight.yaml. For example, change "3000:3000" to "4000:3000" to use port 4000 instead.

Next steps

Section titled “Next steps”