Skip to content

CONTRIBUTING_DOCS.md

Latest commit

 

History

History
69 lines (51 loc) · 3.29 KB

CONTRIBUTING_DOCS.md

File metadata and controls

69 lines (51 loc) · 3.29 KB

Contributing to Daemonless Documentation

This guide explains how the documentation for Daemonless images and the daemonless.io website is managed. We use an automated, template-driven approach to ensure consistency across 50+ repositories.

The Architecture

Our documentation follows a "Single Source of Truth" pattern:

  1. Metadata (compose.yaml): Each image repository contains a compose.yaml file with an x-daemonless section. This is the Brain of the image. It defines the title, description, ports, volumes, and AppJail-specific options.
  2. Central Template (README.j2): The logic for how documentation looks (tabs, code blocks, interactive placeholders) is defined in a single file located in the dbuild repository at dbuild/templates/README.j2.
  3. Local README (README.md): Running dbuild generate in an image repo renders the template using that repo's metadata to create the README.md you see on GitHub.
  4. The Website (daemonless.io): The website is automatically generated by pulling the metadata and READMEs from all repositories and rendering them using the same central template.

Common Tasks

1. Fixing a Typo or Updating Metadata

If you find a typo in a description, a missing environment variable, or want to update a port:

  • Action: Edit compose.yaml in the specific image repository.
  • Sync: Run dbuild generate to update the local README.md.
  • Result: Once merged, both GitHub and the website will be updated automatically.

2. Adding a New Deployment Method (e.g., AppJail)

If you want to add support for a new tool across the entire fleet:

  • Action: Edit the central template in the dbuild repository: dbuild/templates/README.j2.
  • Result: Every image in the Daemonless project will instantly receive a new documentation tab for that tool.

3. Adding AppJail Support to an Image

To enable the AppJail Director tab for a specific image, add the appjail section to its compose.yaml:

x-daemonless:
  appjail:
    director:
      options:
        - "alias:"
        - "ip4_inherit:"

For complex stacks (like Immich), you can define dependencies:

x-daemonless:
  appjail:
    depends_on:
      - name: database
        image: ghcr.io/daemonless/postgres:latest
        env:
          POSTGRES_PASSWORD: "!ENV '${DB_PASSWORD}'"

4. Manual Overrides

If an image requires a completely custom README that doesn't fit the template:

  • Action: Set docs: manual in the x-daemonless section of compose.yaml.
  • Result: The automation will stop overwriting your README.md, and the website will pull your manual file as-is.

Tools

  • dbuild: The primary tool for building images and generating documentation.
    • dbuild generate: Reconciles compose.yaml metadata into README.md and Containerfile.
  • generate_docs.py: The script that builds the website. It imports dbuild to ensure identical parsing logic.

Summary

Don't edit .md files directly unless the repo is marked as docs: manual. Always edit the compose.yaml or the central README.j2 template.