Adds .gitea/workflows/lint.yaml calling DevOps/software-infrastructure's reusable-ansible-role-lint.yaml, and a baseline (.ansible-lint-ignore, 1 file/rule entries) of existing findings so only new problems fail. Manual-only until the shared runner is proven stable (#41) and the CI tools image is published (#49). CI files only; nothing the role deploys changes. Refs DevOps/software-infrastructure#53 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ansible-role-discourse
Reusable Ansible role to deploy Discourse on Kubernetes using the official
discourse/base image through the
official discourse_docker launcher build process. discourse/base is the
upstream base/build image, not a fully configured forum container. The launcher
combines it with the web templates, a Discourse Git revision, and plugins to
produce local_discourse/app; the role tags and pushes that resulting app image
for Kubernetes to run.
The role manages the Kubernetes namespace, app credentials, PostgreSQL and
Redis StatefulSets, their PVCs, the Discourse web Deployment and Service,
optional Ingress, and optional Tor OnionService. PostgreSQL and Redis are
separate internal services; Discourse uploads/backups/logging use a persistent
/shared claim. The forum is deliberately one replica with Recreate rollout
because the official image uses one writable shared directory and its built-in
web/worker supervision model.
Requirements
- Ansible Core 2.16–2.19; install Python packages from
requirements.txtand thekubernetes.corecollection fromrequirements.yml. - Kubernetes API access from the Ansible controller (
kubeconfigorK8S_AUTH_*settings) and a StorageClass that supports the configured claims. - For image builds, a Linux Ansible controller with Docker Engine, Git, and
registry push access already configured. The role runs the official
discourse_docker/launcher bootstrap applocally, then tags/pusheslocal_discourse/apptodiscourse_image. No registry password is accepted by the role; authenticate Docker outside Ansible. The cluster needs an image pull secret if the target registry is private. - Ingress controller/cert-manager and DNS for optional ingress; the Tor operator and its OnionService CRD for optional onion access.
- Encrypted backups of the database and uploads, stored outside the cluster, with regular restore tests. The role does not move Bitnami PVC data or perform Discourse's admin backup restore workflow.
Bitnami migration for eom.dev
Use playbooks/migrate-eom.yml for the one-time
migration. It creates a separate discourse-next namespace and leaves the
Bitnami discourse namespace, release, and PVCs alone during preparation. The
first deployment has no ingress or onion route, so the existing site keeps
serving while you restore and test the replacement.
1. Prepare and verify a backup
- Inventory the live Bitnami release: actual Discourse and PostgreSQL versions, PVC names/classes, storage capacity, SMTP/OIDC/LDAP settings, plugins, and ingress/TLS and OnionService configuration. The role cannot infer these accurately from the old chart task.
- Take a Discourse application backup that includes uploads, download it, and encrypt it off-cluster. Restore that backup in a disposable test instance first. Keep the old Kubernetes data untouched.
- Choose and test the target Discourse revision, PostgreSQL image/major, external plugin refs, and registry tag. The old application is 3.4.7; do not assume the newest revision or an arbitrary old Git revision is a safe restore target. Verify the backup's restore/version compatibility.
- Install the role dependencies, select the intended kube context, and provide the encrypted site variables described below. Authenticate Docker to the image registry on the Linux controller.
2. Build and deploy the isolated target
The EOM playbook requires explicit acknowledgement that the backup was tested.
After completing the steps above, run the migration playbook with
discourse_migration_backup_verified=true and discourse_backup_confirmed=true
from your encrypted/approved deployment variables. Start with --syntax-check
and --check; do not use --diff with secret-bearing resources. Then run the
playbook normally. It builds with the official launcher, pushes the configured
image tag, and deploys the isolated Kubernetes resources.
The first run does not copy or reuse Bitnami PostgreSQL files. Wait for the
new forum to become Ready, then use the Discourse admin backup/restore flow to
restore the tested archive, which carries the database and uploads. You can
access the isolated Service via a temporary kubectl port-forward to
service/discourse in namespace discourse-next. Verify login, admin access,
uploads, email, billing/subscriptions, OIDC callback
/auth/oidc/callback, LDAP, ActivityPub, Prometheus, webhooks, and forum URLs.
Reapply/check plugin configuration and external credentials; plugins alone do
not migrate their settings or secrets.
3. Cut over
Once the restored forum is accepted, schedule downtime and stop writes to the
old forum. Take and verify the final backup, restore it into discourse-next,
and check the target again. Then run the same migration playbook with
discourse_migration_cutover=true, discourse_ingress_enabled=true, and
discourse_onion_enabled=true, while setting discourse_build_enabled=false.
This explicit cutover waits for the target to be Ready, scales the old Bitnami
Deployment to zero, removes its Ingress and optional OnionService, and creates
the target routes. The old release and PVCs remain for rollback; do not uninstall
the release or delete claims until the rollback/retention period has elapsed.
The old Deployment name and Ingress name default to discourse; override the
discourse_migration_source_* variables if the live Helm release uses different
names. Verify the actual rendered resource names before cutover.
The cutover action affects only the named old Deployment, Ingress, and optional
OnionService. It does not uninstall Helm, scale down PostgreSQL/Redis, or delete
any source PVC. Keep a tested rollback plan: traffic can be returned to the old
release, but it may need to be scaled back up and the old Ingress/OnionService
recreated. Avoid accepting writes on both instances.
The Tor operator may issue a new .onion address when the OnionService moves
to the new namespace. Preserve its identity only by following that operator's
documented key/Secret migration procedure; otherwise publish the newly assigned
address after cutover.
The old EOM Bitnami task is now a retirement guard, and the shared EOM Tor task
no longer reconciles Discourse. Do not re-enable the old Helm task after
cutover.
EOM variables and secrets
Site-specific settings are deliberately kept in the EOM playbooks, not role defaults. Supply the following through encrypted inventory/group vars or an Ansible Vault file; never commit the secret values:
vault_discourse_image: immutable registry destination, including tag, for exampleregistry.example.invalid/community/discourse:<tested-build>.vault_discourse_application_version: tested Discourse Git revision to build with the current official templates.vault_discourse_launcher_revision: reviewed commit of the officialdiscourse_dockerrepository used for the launcher and templates.vault_discourse_postgres_image: pinned PostgreSQL image. Match the selected target version to the tested restore plan; do not reuse a data directory across PostgreSQL major versions.vault_discourse_redis_image: pinned Redis image used by the migration and subsequent deploys.vault_discourse_database_password,vault_discourse_redis_password, andvault_discourse_smtp_password: unique credentials, not reused from the Bitnami deployment.vault_discourse_plugin_refs: mapping with reviewed commit/tag refs fordocker_manager,activity_pub,ldap_auth, andprometheus.- Optional
vault_discourse_image_pull_secrets: Kubernetes Secret names for a private image registry.
Current upstream Discourse bundles several plugins previously cloned from GitHub (including subscriptions, OIDC, math, post-voting, reactions, and the ad plugin). Do not clone those into a current image; verify the bundled plugin list for the chosen app revision. LDAP auth, ActivityPub, and Prometheus are external in this site's configuration and need compatibility testing and pinned refs.
Secrets and Kubernetes access
Kubernetes Secret manifests are created from Vault-backed variables and tasks
suppress secret output. Kubernetes Secrets are base64-encoded, not encrypted by
default: enable API-at-rest encryption, restrict RBAC, and avoid logging
rendered Secret resources. The launcher build template uses only a throwaway
placeholder for the DB/Redis password; runtime credentials are injected from
Kubernetes Secrets. The official Discourse image runs its runit supervisor as
root and needs a small capability set for service-user switching, volume
ownership, and binding port 80; the Pod drops all other capabilities and uses
the runtime-default seccomp profile. Enforce an appropriate Pod Security policy
for this workload rather than assuming it satisfies the restricted profile.
Ongoing deployment and upgrades
Use playbooks/deploy-eom.yml after cutover. It reconciles the same namespace and resource names against the configured image and keeps ingress/Tor enabled. Do not change the app image tag to a new build until that image has been built and pushed.
For an intentional app/plugin upgrade, test the target revisions against a
restored staging backup, take a fresh encrypted production backup, then run the
EOM playbook with discourse_build_enabled=true and
discourse_backup_confirmed=true. Change vault_discourse_application_version,
vault_discourse_launcher_revision, plugin refs, and vault_discourse_image
to a new immutable tag together. The
role builds via the upstream launcher, pushes, and updates the Deployment. A
Discourse rebuild may run database migrations; expect downtime and retain the
previous image and backups for rollback.
Generic role defaults and optional behaviors are in defaults/main.yml. Instances default to a private ClusterIP Service and disabled ingress/Tor. The role refuses multi-replica configuration, supports configurable storage/classes/resources/node placement, and never deletes PVCs. Scaling, PostgreSQL major upgrades, backup scheduling, network policies, and external ingress/TLS setup remain operator responsibilities.
Tests
tests/run.sh checks playbook syntax and renders role manifests locally without
connecting to a cluster. Use the supplied test Dockerfile on a controller with
Docker, or install dependencies and run the script directly.
License
BSD-3-Clause; see LICENSE.