Bookstack

Bookstack is a great Wiki product that leverages a MariaDB backend with support for LDAP, SAML, and OIDC. I use it for detailed internal documentation about the Homelab. Below is how I've implemented Bookstack into my Kubernetes cluster.

Product: Bookstack
Install Type: Helm (Chart)
Container Image: Docker

Installation Details

For Helm charts, I generally pull the values to a file and modify that file for my specific needs:

 helm show values oci://ghcr.io/gabe565/charts/bookstack > values.yaml

This allows me to modify different settings, such as the details of the MariaDB values, and environment specific configurations such as OIDC configurations, define internal root CAs, persistent storage and others. Please configure as appropriate for your environment. You should consult the excellent Bookstack documentation for what environment variables you can define.

Below are some of the changes I've made. I am also leveraging Authentik to provide OIDC capabilities.

...

# -- environment variables.
#    For more options see [BookStack .env.example](https://github.com/BookStackApp/BookStack/blob/release/.env.example.complete).
# @default -- See [values.yaml](./values.yaml)
env: 
  APP_TIMEZONE: "America/New_York"
  APP_URL: "https://your.host.name"
  APP_DEBUG: false
  APP_DEFAULT_DARK_MODE: true
  FILE_UPLOAD_SIZE_LIMIT: 100
  EXPORT_PAGE_SIZE: letter
  DB_DATABASE : bookstack
  DB_HOST : YourDBServer
  DB_PASSWORD : "YourSuperSecretPassword"
  DB_USERNAME : bookstack
  MAIL_DRIVER: smtp
  MAIL_FROM_NAME: "Name of your Sender"
  MAIL_FROM: "address@your.domain"
  MAIL_HOST: your.server.or.relay.host
  MAIL_PORT: 25
  MAIL_USERNAME: "username@your.server.or.relay"
  MAIL_PASSWORD: "YourSuperSecretPassword"
  MAIL_ENCRYPTION: tls
  AUTH_METHOD: oidc 
  AUTH_AUTO_INITIATE: true
  # Refer to https://www.bookstackapp.com/docs/admin/oidc-auth/
  OIDC_NAME: Authentik
  OIDC_DISPLAY_NAME_CLAIMS: name
  OIDC_CLIENT_ID: from_authentik
  OIDC_CLIENT_SECRET: from_authentik
  OIDC_ISSUER: https://your.authentik.host/application/o/your_application_in_authentik/
  OIDC_ISSUER_DISCOVER: true
  # OIDC_PUBLIC_KEY: null
  # OIDC_AUTH_ENDPOINT: null
  # OIDC_TOKEN_ENDPOINT: null
  # OIDC_ADDITIONAL_SCOPES: null
  OIDC_DUMP_USER_DETAILS: false
  OIDC_USER_TO_GROUPS: true
  OIDC_GROUPS_CLAIM: groups
  OIDC_REMOVE_FROM_GROUPS: false
  OIDC_EXTERNAL_ID_CLAIM: sub
  OIDC_END_SESSION_ENDPOINT: false

...

ingress:
  # -- Enable and configure ingress settings for the chart under this key.
  # @default -- See [values.yaml](./values.yaml)
  main:
    enabled: true
    ingressClassName: nginx-int
    annotations:
      cert-manager.io/cluster-issuer: your-issuer
    hosts:
      - host: your.host.name
         paths:
          - path: /
    tls:
      - secretName: bookstack-int-tls
        hosts:
          - your.host.name

...

The above assumes that you have a properly configured ingress (with a properly configured LoadBanacer with something like MetalLB) and Cert Manager configured with an ACME issuer like Let's Encrypt or an internal issuer with something like Step CA.

...

persistence:
  # -- Configure persistence settings for the chart under this key.
  # @default -- See [values.yaml](./values.yaml)
   config:
     enabled: true
     retain: true
     storageClass: longhorn
     accessMode: ReadWriteMany
     size: 10Gi

...

I'm using a single Maria Database Instance for all my deployments and we defined that in the environment above. So we will make sure it is disabled in the chart as we do not need to have it deployed.

You don't have to deploy your database in this chart, but I find it more convenient.

...

# -- Enable and configure mariadb database subchart under this key.
#    For more options see [mariadb chart documentation](https://github.com/bitnami/charts/tree/master/bitnami/mariadb)
# @default -- See [values.yaml](./values.yaml)
mariadb:
  enabled: false

...

Once you have made you changes, deploy with the following:

helm upgrade --install --namespace docs --create-namespace \
             -f values.yaml bookstack oci://ghcr.io/gabe565/charts/bookstack