DevOps Deployment Guidelines

This section holds deployment guides for ATech web sites. The guides support both human operators and agents. Follow the matching site-type and deployment pattern before you build or deploy a site.

Guide structure

Use this path pattern for new guides:

src/content/docs/devops/deployment-guidelines/<site-type>/<site-sub-type>.md

Examples:

• static-site/standalone-cloudflare-pages.md
• static-site/managed-cloud-hosting.md
• static-site/subsite-managed-cloud-hosting.md
• drupal-site/managed-cloud-hosting.md
• wordpress-site/managed-cloud-hosting.md

Add a sidebar group for each site type in astro.config.mjs. The group label uses the human-readable site type, and Starlight builds its child links from that type’s directory. Keep the file name short, lowercase, and hyphenated. Use the page title for the full site subtype name.

Required page sections

Each site-subtype guide must use these headings in this order:

1. Guidelines — scope, assumptions, local development, build output, security, verification, and rollback.
2. Docker build — explain the image and build steps, or state why Docker is not needed.
3. Docker Compose — explain local multi-service use, or state why it is not needed.
4. GitLab CI/CD
   • Build — checks, tools, artifacts, and build output path.
   • Deploy — target, credentials, branch rules, access control, and rollback.
5. References — link to official product docs and internal runbooks.

Do not remove a required section when it does not apply. Mark it Not applicable and explain why. This keeps guides easy to compare and helps agents find the same instructions in each page.

Writing for people and agents

• State the scope, prerequisites, expected result, and owner or escalation path.
• Use ordered steps for procedures. Put commands in code blocks and name the working directory when it matters.
• Name required variables. Use placeholders in examples; never put live tokens, passwords, or private data in a guide.
• Mark actions that change production. State who may approve them and how to verify success or recover from failure.
• Include full, copy-ready examples for applicable Dockerfiles, Compose files, and CI configs. Keep them aligned with working project files. Mark examples that do not apply and explain why.
• Separate required policy from examples and optional choices.
• Review the links and commands when the platform, CI template, or deployment changes.