One-click deploy templates for app platforms (DigitalOcean, Railway, Render, Fly)

[rumblefrog]

Background

Follow-up to #1381 (production Docker image + production docker-compose.prod.yml). This issue tracks the application of those outputs to specific app-platform deploy formats — surfacing a "Deploy to X" button on the README and the docker quickstart docs page so users with no Linux box of their own can self-host SourceBans++ in a few clicks.

Blocked by #1381. Every template here references the GHCR image #1381 publishes — without a published, multi-arch, env-driven image there is nothing to deploy. The cross-cutting "one-click-deploy friendliness" properties (PORT honouring, DATABASE_URL parsing, headless-install default, trusted-proxy headers, etc.) are tracked as design constraints on #1381 itself rather than as deliverables here, so this issue stays a thin wrapper.

Revenue intent. Each one-click deploy button is a referral surface that funnels users to a hosting platform; in return the platform pays a referral fee. This issue's referral-program selection (deliverable 5) explicitly biases toward recurring revenue share over one-time bounties because the project's monetization constraints (full-time-employed maintainer, zero support capacity) make recurring/passive income the only sustainable shape. Referral revenue is treated as project revenue, transparently disclosed on the docs page that introduces the buttons.

Scope

For each platform: a spec file under deploy/<platform>/, a per-platform README.md documenting the env vars + any platform-specific gotchas + the referral terms in effect, and the README / docs button snippet referencing the platform's deploy URL with the referral code attached. The image reference is pinned to a major-version tag (e.g. ghcr.io/sbpp/sourcebans-pp:2) for deploy stability, with the per-platform README documenting the opt-in to :latest for users who want auto-updates.

1. DigitalOcean App Platform — deploy/digitalocean/app.yaml

Spec reference. Defines:

• services[0] — the web service pointing at image: ghcr.io/sbpp/sourcebans-pp:<major>, http_port: 80, env vars from secrets bindings.
• databases[0] — engine: MYSQL (DO ships MySQL 8 as their managed offering; verify panel compatibility against the existing 5.6+ floor) with production: false for the dev/$15 tier.
• The README links the "Create App from Spec" UI flow + the [![Deploy to DO](https://www.deploytodo.com/do-btn-blue.svg)](https://cloud.digitalocean.com/apps/new?repo=...&refcode=...) button shape with the project's referral code attached.

2. Railway — deploy/railway/template.json

Templates documentation. Railway templates are JSON-defined and reference both a service image + plugins (their MariaDB plugin is the right fit). The template URL https://railway.app/template/<id> is what the README button links to. Railway also supports railway.toml for repo-level config, which is the form the per-deploy/railway/README.md documents.

3. Render — deploy/render/render.yaml

Blueprint spec. Defines a web service pointing at image: ghcr.io/sbpp/sourcebans-pp:<major> + a databases[0] block for the managed MySQL offering. Render injects DATABASE_URL automatically when a database service is referenced — #1381's entrypoint handles the parsing per the friendliness constraints, so this template is just three blocks of YAML. Render's "Deploy to Render" button format: [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=...).

4. Fly.io — deploy/fly/fly.toml

Configuration reference. Web-only template — Fly's managed Postgres doesn't fit (panel is MySQL/MariaDB only); the per-deploy/fly/README.md documents the recommended path of pointing at an external managed MariaDB (DO Database, PlanetScale, Aiven, etc.) via the DATABASE_URL env. Fly's flyctl launch --from <repo> flow is the closest analog to a one-click button; the README documents the two-command setup.

5. Referral / revenue-share program selection

Each per-platform deploy/<platform>/README.md documents the platform's referral program (if any) and the action that wires the referral code into the deploy button URL. Referral revenue is project revenue, transparently disclosed on the docs page section that introduces the buttons (one line, plain language, no dark patterns).

Decision contract for future contributors:

• Prefer recurring revenue share over one-time bounty when both are available for the same platform. Recurring share converts long-running deployments into ongoing project revenue without per-customer support burden — the only sustainable monetization shape given the project's constraints (volunteer FT-employed maintainer, no support capacity to absorb managed-hosting overhead).
• Document the referral terms — rate, bounty/recurring shape, payout cadence, attribution mechanic — in each per-platform README. Programs change; future contributors switching to a better-paying program (or replacing one that's been retired) need the current state captured in-tree.
• Disclose the referral relationship in the docs page section that introduces the buttons. Single line, plain language, no dark patterns.
• Don't sacrifice user fit for revenue. A platform with a great referral program but bad user fit (e.g., locks users into a vendor that's hard to migrate off) doesn't belong here. The buttons are user features first; revenue is a side effect of doing right by users.

Platform notes at time of writing (subject to drift — verify before merge):

• DigitalOcean — one-time bounty $25-200/signup. Enable via ?refcode=<code> on the Create-App URL. Referral program.
• Render — one-time bounty per converted customer; Render's program is solo-dev focused but the deploy-button URL accepts referral codes.
• Railway — referral program currently invite-based; verify maintainer's status before merging.
• Fly.io — no public referral program at time of writing; document this and revisit if Fly ships one.

Additional partner (separate surface, not a one-click button):

• Cloudways — managed PHP/MariaDB hosting on top of DO/Vultr/Linode/AWS infrastructure; 7% recurring revenue share for the customer's lifetime (best terms in the PHP-hosting space and the only true recurring program in the candidate set). Not a "click-button" deploy target (Cloudways provisions a managed VPS rather than a containerized app), but the right operational fit for stateful PHP+MariaDB workloads — the panel is exactly the workload shape Cloudways is built for. Surface as a "Recommended managed host" callout on the docker quickstart docs page (deliverable 5 of Production Docker image + production docker-compose for self-hosters (and one-click-deploy gateway) #1381) with the affiliate link, separate from the four one-click buttons. The recurring shape makes this the most valuable single referral relationship in the set; treat it accordingly.

Non-goals

• Kubernetes Helm chart — separate audience, separate issue. The OCI image from Production Docker image + production docker-compose for self-hosters (and one-click-deploy gateway) #1381 is the prerequisite either way.
• AWS CloudFormation / Terraform modules / Pulumi programs — same shape, different consumers; the GHCR image makes any of these straightforward follow-ups but they're not in this issue.
• Heroku buildpack — Heroku dropped its free tier; the use case is fully covered by Render and Railway, both of which accept the OCI image directly with no buildpack indirection.
• AWS App Runner / Google Cloud Run / Azure Container Apps — same shape as the four covered here; can be added in a follow-up if there's user demand. The four chosen platforms cover the vast majority of self-hosters who don't run their own Linux box.
• Selling managed hosting ourselves. Out of scope here and tracked nowhere — the project's constraints rule it out (see "Revenue intent" above). The referral relationships in deliverable 5 are the substitute.

Acceptance

• Each platform's spec file lives under deploy/<platform>/ with its own README.md covering required env vars, the secrets pattern that platform uses, persistent-volume / managed-DB setup, the referral program in effect, and any platform-specific gotchas.
• The docker quickstart docs page (created by Production Docker image + production docker-compose for self-hosters (and one-click-deploy gateway) #1381 deliverable 5) gains a "Deploy with one click" section linking each platform + a "Recommended managed host" callout for Cloudways.
• The repo root README gains a "Deploy" subsection with the four buttons.
• Each template has been smoke-tested against the actual platform — or, for templates we can't smoke-test in CI (Railway / Fly require auth tokens), the per-platform README documents the manual verification flow we ran before merge.
• Referral disclosure line is present and unambiguous on the docs page that introduces the buttons.

Open questions

• Default tier sizing. Each platform's spec needs a default instance size + DB size. Err small (cheapest tier the panel actually runs on) and document the upgrade path in the per-platform README.
• Image tag strategy for templates. :<major> (e.g. :2) gives users automatic minor / patch updates without breaking semver. :latest is friendlier for one-click but risks breaking deploys on a major bump. Recommend :<major> as the default, with the README explaining how to switch.

References

• Parent: Production Docker image + production docker-compose for self-hosters (and one-click-deploy gateway) #1381 (production Docker image + production docker-compose).
• Sibling revenue track: the sponsor-visibility issue (panel chrome footer + Open Collective + corporate tiers) and the commercial-license issue (web-panel CC BY-NC-SA commercial-use offering) cover the non-referral revenue paths.
• AGENTS.md "Where to find what" rows on the existing release / docker pipelines.

[zp6]

I've submitted a PR to address this: #1389

Wallet: zp6

[mr-magaia]

Taking this on now. I will keep the fix focused and open a PR against this issue.