Local BookStack on OpenShift / CRC
CI Backup
Overview

dev-bookstack

A local BookStack instance running on Red Hat CodeReady Containers (CRC), with an automated pipeline that syncs Markdown files from Git straight into BookStack pages.

What is this?

dev-bookstack is a batteries-included local knowledge-base environment. You write content as plain Markdown files in a Git repository, and a CI/CD pipeline handles linting, testing, and publishing them to a self-hosted BookStack wiki — automatically.

📝

Git-native authoring

Write pages as Markdown, commit them, and the pipeline does the rest.

🔄

Automatic sync

Changed files are published to BookStack on every push to develop.

🛡️

Quality gates

Secret scanning, Markdown lint, pytest, and spell-check run before any sync.

☁️

Local + Remote

CI syncs a local CRC instance; merges to main push to a remote production instance.

Stack

Component Image Notes
BookStack lscr.io/linuxserver/bookstack:latest Requires anyuid SCC on OpenShift
Database bitnami/mariadb:10.11 Arbitrary-UID compatible; utf8mb4 charset

Both workloads run inside a single OpenShift namespace (bookstack-dev) on CRC, backed by PersistentVolumeClaims for data durability across pod restarts.

Infrastructure at a glance

ResourceFilePurpose
Secretsopenshift/secrets.yamlDB credentials & BookStack APP_KEY
MariaDBopenshift/mariadb.yamlPVC (2 Gi), Deployment, Service
BookStackopenshift/bookstack.yamlPVC (5 Gi), Deployment, Service, Route

Prerequisites

Quick Start

  1. 1

    Start CRC and log in as kubeadmin

    You need the kubeadmin role to create namespaces and grant Security Context Constraints (SCCs).

  2. 2

    Configure your shell for CRC

    Point your oc and Docker CLI at the embedded CRC cluster.

  3. 3

    Run the deploy script

    Creates the namespace, applies secrets, and deploys both workloads.

  4. 4

    Open BookStack in your browser

    Wait ~60 seconds for the readiness probe to pass, then visit the URL below.

shell
# 1. Start CRC and log in as kubeadmin
#    (needed to create projects and grant SCCs)
crc start
eval $(crc oc-env)
oc login -u kubeadmin https://api.crc.testing:6443
# Password: crc console --credentials

# 2. Deploy
./deploy.sh

BookStack will be available at:

http://bookstack-bookstack-dev.apps-crc.testing
⚠️ Default credentials — change after first login Email: admin@admin.com  ·  Password: password

Teardown

To remove the entire environment, run:

./teardown.sh
⚠️ Destructive action This deletes the bookstack-dev namespace and all data within it, including the MariaDB PVC and BookStack uploads. The script will prompt you to type yes before proceeding.

Next steps

Configuration →

Credentials, APP_URL customisation, persistent storage details.

Sync System →

How Markdown files are published to BookStack via the REST API.

CI / CD Workflows →

The full GitHub Actions pipeline, backup schedule, and autofix.

Content Authoring →

Page templates, required sections, and image conventions.