BookStack on Kubernetes with FluxCD

Project Overview

This project demonstrates the deployment of the BookStack web application on a Kubernetes cluster using the GitOps approach powered by FluxCD.

BookStack is an open-source documentation platform that allows users to create and manage documentation in the form of books, chapters, and pages. The application relies on a relational database for data persistence.

Solution Architecture

• Application: BookStack
• Containerization: Docker
• Orchestration: Kubernetes
• CI/CD approach: GitOps
• GitOps Operator: FluxCD
• Database: MariaDB
• Database Operator: Official MariaDB Operator (mariadb-operator)
• Storage: Default Rancher StorageClass (local-path)

Components

BookStack

• Deployed using a Helm chart
• Configured via values.yaml
• Uses a PersistentVolumeClaim for application configuration and uploaded files
• Database connection is configured via environment variables

MariaDB

• Deployed as a Custom Resource (MariaDB)
• Managed by the official MariaDB Operator
• Uses persistent storage provided by the cluster default local-path StorageClass

Persistent Storage

• The cluster uses the default Rancher StorageClass (local-path)
• No explicit storageClassName is defined in manifests
• PersistentVolumeClaims are automatically provisioned by the cluster

FluxCD

• Continuously reconciles Kubernetes manifests from the Git repository
• Provides self-healing by restoring deleted resources
• Manages separate environments for staging and production using different overlays

Application Deployment

The application is deployed using FluxCD Kustomizations and HelmReleases.

Deployment Flow

1. FluxCD watches the configured Git branch and path.
2. Kustomize builds environment-specific manifests.
3. HelmReleases deploy the BookStack Helm chart.
4. The MariaDB Operator reconciles the MariaDB custom resource.
5. PersistentVolumeClaims are automatically created using the default StorageClass.
6. Pods are scheduled and started in the cluster.

Environments

• Staging environment is deployed from the main branch. Url: https://bookstack.stage.local/
• Production environment is deployed from the main branch. Url: https://bookstack.local/
• Each environment has its own namespace and configuration.

Project Goals

The main goals of this project are:

• to demonstrate a GitOps workflow in Kubernetes;
• to deploy a stateful application using Kubernetes Operators;
• to use Helm and Kustomize for configuration management;
• to achieve automated deployment and self-healing of Kubernetes resources.

flux bootstrap github --owner=yarovskiy --repository=rd-course-project --branch=main --path=./clusters/local --personal

Create Admin User

❯ kubectl exec -it <pod> -- bash
 php /app/www/artisan bookstack:create-admin --email=<email> --name=<name> --password=<password>

Results

❯ kubectl get helmreleases -A
NAMESPACE     NAME                    AGE     READY   STATUS
flux-system   mariadb-operator        6h7m    True    Helm install succeeded for release flux-system/mariadb-operator.v1 with chart mariadb-operator@25.10.2
flux-system   mariadb-operator-crds   6h7m    True    Helm install succeeded for release flux-system/mariadb-operator-crds.v1 with chart mariadb-operator-crds@25.10.2                                                                                                                                                              
production    bookstack               3h51m   True    Helm upgrade succeeded for release production/bookstack.v2 with chart bookstack@0.20.0
staging       bookstack               31m     True    Helm install succeeded for release staging/bookstack.v1 with chart bookstack@0.20.0

❯ flux get kustomizations -A
NAMESPACE       NAME                    REVISION                SUSPENDED       READY   MESSAGE                              
flux-system     app-production          main@sha1:1bede82d      False           True    Applied revision: main@sha1:1bede82d    
flux-system     app-staging             main@sha1:1bede82d      False           True    Applied revision: main@sha1:1bede82d    
flux-system     flux-system             main@sha1:1bede82d      False           True    Applied revision: main@sha1:1bede82d    
flux-system     mariadb-operator        main@sha1:1bede82d      False           True    Applied revision: main@sha1:1bede82d  

❯ kubectl get pods -n staging
NAME                         READY   STATUS    RESTARTS   AGE
bookstack-6b8d745875-4hlv8   1/1     Running   0          34m
bookstack-db-0               1/1     Running   0          116m

❯ kubectl get pods -n production
NAME                         READY   STATUS    RESTARTS         AGE
bookstack-56c87ff887-p7967   1/1     Running   0                3h54m
bookstack-56c87ff887-w8q9f   1/1     Running   0                115m
bookstack-db-0               2/2     Running   0                116m
bookstack-db-1               2/2     Running   0                116m
bookstack-db-2               2/2     Running   0                116m

❯ kubectl get ingress -A
NAMESPACE    NAME        CLASS     HOSTS                   ADDRESS        PORTS     AGE
production   bookstack   traefik   bookstack.local         192.168.64.2   80, 443   3h55m
staging      bookstack   traefik   bookstack.stage.local   192.168.64.2   80, 443   35m