Skip to content

docs: standardize image deployment guides - #17

Merged
enwaiax merged 4 commits into
mainfrom
docs/standardize-image-guides
Aug 15, 2026
Merged

enwaiax merged 4 commits into
mainfrom
docs/standardize-image-guides

Conversation

@enwaiax

@enwaiax enwaiax commented Aug 15, 2026

Copy link
Copy Markdown
Owner

Summary

Defines and applies a reusable image-guide contract so future images enter the catalog with complete, safe, and operationally useful documentation.

This PR is stacked on #16 because the standardized Maddy guide documents the v0.9.5 paths and commands introduced there. Merge #16 first, then retarget this PR to main.

Guide standard

Adds docs/image-guide-template.md with required sections for:

  • lifecycle, image version, architectures, and verification date;
  • overview and deployment recommendation;
  • prerequisites;
  • Docker CLI and Docker Compose quick starts;
  • environment variables, ports, volumes, networking, and privileges;
  • first-run verification;
  • logs, upgrade, backup/restore, and uninstall;
  • security, troubleshooting, and known limitations.

Adds scripts/validate-image-guides.py and a required CI job. It validates all five catalog guides and rejects dangerous patterns such as recursive world-writable permissions, hard-coded aria2 RPC secrets, destructive database-reset advice, and legacy Compose commands. It also checks repository-owned Compose policy.

Guide and Compose updates

  • Maddy: complete v0.9.5 deployment, DNS/TLS, verification, backup, restore, upgrade, and troubleshooting guide.
  • Download Bot: fixes the wrong title, documents config fields and secrets, removes the hard-coded RPC secret, replaces host networking/PWD mounts with an isolated Compose network and relative paths.
  • Netease Music Tasks: converts the page to an archived-user maintenance and credential-cleanup guide.
  • X-UI: makes Moved status explicit, explains host-network risk, and removes destructive “delete the database to reset password” advice in Chinese and English.
  • Firefox Send: adds the previously missing Archived guide and modernizes the historical Compose network syntax.
  • RainLoop: archives the add-on guide, removes insecure permission/default-password deployment instructions, and restricts its historical HTTP binding to localhost.

All repository-owned Compose files now omit obsolete top-level version keys and use consistent logging/volume syntax.

Verification

  • image guide contract: 5/5 pass;
  • all repository-owned Compose files parse;
  • Maddy and Download Bot Dockerfiles pass Buildx checks;
  • Download Bot AMD64 image builds;
  • Astro check and seven-page production build pass;
  • npm production audit reports 0 vulnerabilities;
  • actionlint and Python syntax checks pass;
  • repository-owned guide links pass.

Publishing impact

No Docker image is published or deleted. Documentation and historical Compose behavior are made safer, but archived entries remain explicitly unsupported for new deployments.

@enwaiax
enwaiax changed the base branch from feat/maddy-0.9.5 to main August 15, 2026 12:42
@enwaiax
enwaiax merged commit 9a50c38 into main Aug 15, 2026
12 checks passed
@enwaiax
enwaiax deleted the docs/standardize-image-guides branch August 15, 2026 12:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant