Install & quickstart
Get started

Install & quickstart

Run the container, mount your runbooks, and see your first page.

Run the container

The app ships as a container image and carries no content. You mount a directory of Markdown runbooks. The image is built from the public source at github.com/runbooks-help/runbooks.

Start Runbooks 
docker run -d --name runbooks \
  -p 8090:8090 \
  -v "$PWD/content:/app/content" \
  -v runbooks-data:/app/data \
  ghcr.io/runbooks-help/runbooks:latest

Open localhost:8090.

  • /app/content is the content root (CONTENT_DIR). If it is empty the index renders a welcome page; add a .md file to populate it.
  • /app/data holds the SQLite identity database when identity is on. It is unused otherwise, but mount it so a later upgrade keeps its data.
  • The container runs as a non-root user and exposes /healthz.

Pin a version tag (:vX.Y.Z) rather than :latest for a production deployment.

Your first runbook

Create content/mysql/backup/verify-backup.md:

---
title: Verify the nightly backup
slug: verify-backup
description: Check that last night's dump exists and restores.
---

## Check the dump

The dump should be from tonight and non-trivial in size.

The path puts it under MySQL › Backup in the sidebar, and the URL is /verify-backup (from the slug, not the filename). Content is read from disk at startup: no rebuild, no restart. Add a code block, a notice or vars as you need them: see Writing a runbook.

Configuration

Every setting is an environment variable; the full list is Configuration. The common ones:

VarDefaultMeaning
PORT8090HTTP listen port.
CONTENT_DIRcontentDirectory the runbooks are read from.
PUBLIC_URL(unset)Absolute site base; enables canonical/OpenGraph tags and /sitemap.xml.
IDENTITY_DB_DRIVER(unset)sqlite, mysql or postgres; unset leaves the app public.

Get the source

Runbooks is public and source-available under FSL-1.1-MIT. The source lives at github.com/runbooks-help/runbooks, and that repository is where the code, releases and issue tracker live. The image is the supported distribution; building from source is straightforward:

Clone, build and run 
git clone https://github.com/runbooks-help/runbooks
cd runbooks
mise install
mise run build
./runbooks            # serves on :8090, reads ./content

Where next