decidim-runbook

The following repository contains a series of instructions, as well as automation scripts, for installing Decidim 0.31.7 on Ubuntu Server 24.04 (Noble).

The instructions support a variety of DNS methods, ranging from tunnelling for security and privacy, for cases, where censorship or network blocks may be a problem, to setting up on Namecheap, a provider commonly used by the NWD Co-op. Provided additionally are "optional" instructions for specific fringe cases such as multi-instance setup, a reset plan in case of instance damage/corruption, and detailed instructions for migration across hosts, or local docker containers. Each step is documented in-depth to explain individual commands and flags, to ensure that anyone with basic Linux/Unix CLI knowledge can fully comprehend every instruction.

---

Documents

Read in order. Steps 2 and 3 each offer more than one document — pick the one matching your situation, not all of them.

Step	Document	Purpose
1	1-installation.md	Bare Ubuntu 24.04 server through to a working Decidim instance, confirmed locally
2	2-cloudflare-dns.md	Publish it — domain's nameservers on Cloudflare, public IPv4
2	2-namecheap-dns.md	Publish it — domain on Namecheap, public IPv4
2	2-cloudflared-tunnels.md	Publish it — Cloudflare Tunnel, for when port-forwarding isn't possible
3	3-smtp.md	Configure real SMTP delivery through a third-party provider*
3	3-smtp-skip.md	Console workaround for an admin account before SMTP is configured — optimal for "test" runs

* Self-hosted SMTP is not covered by these instructions, and isn't recommended unless operating at a scale that makes it preferable or necessary — a third-party transactional provider is the practical choice for effectively every deployment this repository is meant for. See 3-smtp.md itself for the reasoning.

Optional

Not part of the linear path — reach for these as the situation comes up.

Document	Purpose
opt-multi-instance.md	Run a second, independent Decidim instance on a machine that already has one
opt-migration-and-backups.md	Move an instance's data to another instance or a separate machine, and back it up (same pg_dump mechanism either way)
opt-reset-and-preserve.md	Rebuild an instance's containers from scratch without losing its data

---

Layout

decidim-runbook/
  README.md              this file
  instructions/           every document in the table above
  scripts/                 the automation this repo installs and runs
    new-instance.sh        generates a Decidim instance (run once per instance directory)
    .env.example            documented, commented instance configuration
    deploy/
      Dockerfile              production image build
      docker-compose.yml       the four-service stack
      entrypoint.sh             container startup (waits for the database)