BookStack on Kubernetes (in-cluster MySQL + external HAProxy)

Image used: lscr.io/linuxserver/bookstack:latest (community-maintained, actively updated, includes /status health endpoint that BookStack's own HA docs recommend probing).

1. Create the database in your existing MySQL

BookStack manages its own schema, so it just needs an empty database + a user with full rights on it. Run on your existing MySQL:

CREATE DATABASE bookstack CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'bookstack'@'%' IDENTIFIED BY 'CHANGE_ME_strong_password';
GRANT ALL PRIVILEGES ON bookstack.* TO 'bookstack'@'%';
FLUSH PRIVILEGES;

Use the same password in 01-secret.yaml (DB_PASSWORD).

2. Edit before applying

File	What to change
`01-secret.yaml`	`DB_PASSWORD` to match what you set in MySQL
`02-configmap.yaml`	`APP_URL` (must match the host users/HAProxy hit), `DB_HOST` (your MySQL Service DNS name)
`03-pvc.yaml`	`storageClassName` — run `kubectl get storageclass` to see what's available
`06-ingress.yaml`	`host`, and `ingressClassName` if you're not on ingress-nginx

DB_HOST resolution inside the cluster:

Same namespace as MySQL's Service → just the Service name, e.g. mysql
Different namespace → mysql.<that-namespace>.svc.cluster.local

3. Apply

kubectl apply -f 01-namespace.yaml
kubectl apply -f 04-secret.yaml
kubectl apply -f 03-configmaps.yaml
kubectl apply -f 04-storage-class.yaml
kubectl apply -f 05-deployment.yaml
kubectl apply -f 06-service.yaml

Check it's healthy:

kubectl -n bookstack get pods
kubectl -n bookstack logs -f deploy/bookstack
kubectl -n bookstack port-forward svc/bookstack 8080:80
curl -i http://localhost:8080/status   # should return 200

Default login is admin@admin.com / password — change it immediately after first login.

4. Point HAProxy

This setup gives you Proxy Service and Ingress Should point the DNS to the Proxy service. Because Bookstakc is running in diffrent Namespace, so HAProxy cannot cross-connect to diffrent namespace.

Create Proxy for Bookstack:

apiVersion: v1
kind: Service
metadata:
  name: bookstack-proxy
  namespace: default
spec:
  type: ExternalName
  externalName: bookstack.bookstack.svc.cluster.local
  ports:
  - port: 80

Example HAProxy backend:

I Hosts: 
        - bookstack.yourdomain.com
Add the below in rules: 
- host: bookstack.yourdomain.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: bookstack-proxy
                port:
                  number: 80

Revision #7
Created 2026-06-23 06:29:48 UTC by Admin
Updated 2026-06-23 08:54:58 UTC by Admin