Example modules

These modules validate with ordo-state validate and ship with every Ordo release. Each is a complete, working starting point — copy one, adjust it for your fleet, and apply it. They are rendered here verbatim from the published files, so what you read is exactly what ships. For how the pieces fit together, see Writing state modules.

caddy-site

# caddy-site — worked example module
#
# Hosts a static site with Caddy, modelled entirely with Ordo's first-class
# resource types: the package installed with the right manager per distro,
# config and content files, and a systemd service. Plan and drift diff every
# piece. See examples/README.md for the walkthrough and the trade-offs.
name: caddy-site
# Linux + systemd, on the distros we package Caddy for below. Caddy ships a
# `caddy.service` unit we adopt. To support another distro, add it here; if it
# needs a different package manager, add an override variant to `caddy-pkg`.
supports:
  - {platform: linux, distro: debian, init_system: systemd}
  - {platform: linux, distro: ubuntu, init_system: systemd}
  - {platform: linux, distro: fedora, init_system: systemd}
templates:
  - id: caddyfile
    content: |
      # Serve the static site on port 80. Swap `:80` for a real domain
      # (e.g. `site.example.com`) and Caddy provisions HTTPS automatically.
      :80 {
        root * /var/www/caddy-site
        file_server
      }
  - id: index
    content: |
      <!doctype html>
      <html><body><h1>Served by an Ordo-managed Caddy</h1></body></html>
resources:
  # apt is the default for every supported agent; fedora is more specific, so
  # its variant wins and installs with dnf. The package name is the same — only
  # the manager differs, which is what variant selection is for.
  - id: caddy-pkg
    variants:
      - when: {platform: linux}
        resource:
          package-apt:
            name: caddy
      - when: {platform: linux, distro: fedora}
        resource:
          package-dnf:
            name: caddy
  - id: site-dir
    resource:
      directory-unix:
        path: /var/www/caddy-site
        mode: "0755"
  - id: index-file
    depends_on: [site-dir]
    resource:
      file-unix:
        path: /var/www/caddy-site/index.html
        template: index
        mode: "0644"
  - id: caddyfile
    depends_on: [caddy-pkg]
    resource:
      file-unix:
        path: /etc/caddy/Caddyfile
        template: caddyfile
        mode: "0644"
  # Adopt the unit the package ships: no `exec_start`, so Ordo manages enablement
  # and running state of the existing `caddy.service` rather than writing a unit.
  # `reload_on` reloads Caddy (no dropped connections) whenever the Caddyfile
  # changes — including the first apply, where installing the package pre-starts
  # the unit with its default config before Ordo writes ours. This replaces the
  # separate always-running reload script the example used before (0027).
  - id: caddy-service
    depends_on: [caddyfile, index-file]
    resource:
      service-systemd:
        name: caddy
        enabled: true
        running: true
        reload_on: [caddyfile]

demo-compose-stack

# demo-compose-stack — worked example module
#
# Demonstrates running a Docker Compose stack under Ordo. Ordo owns the stack's
# files (the compose file and the served content) as `file-unix` resources, and
# a single checkless `script` resource drives `docker compose up -d` so Compose
# itself does the reconciliation. See examples/README.md for the walkthrough and
# the trade-offs this shape makes.
name: demo-compose-stack
# Linux agents only — this stack runs under Docker Compose.
supports:
  - {platform: linux}
templates:
  - id: compose
    content: |
      services:
        web:
          image: nginx:stable
          restart: unless-stopped          # Docker handles reboot persistence
          ports:
            - "8080:80"
          volumes:
            - ./html:/usr/share/nginx/html:ro
  - id: index
    content: |
      <!doctype html>
      <html><body><h1>Served by an Ordo-managed Compose stack</h1></body></html>
resources:
  - id: stack-dir
    resource: {directory-unix: {path: /opt/ordo-demo-stack, mode: "0755"}}
  - id: html-dir
    depends_on: [stack-dir]
    resource: {directory-unix: {path: /opt/ordo-demo-stack/html, mode: "0755"}}
  - id: compose-file
    depends_on: [stack-dir]
    resource:
      file-unix: {path: /opt/ordo-demo-stack/docker-compose.yaml, template: compose, mode: "0644"}
  - id: index-file
    depends_on: [html-dir]
    resource:
      file-unix: {path: /opt/ordo-demo-stack/html/index.html, template: index, mode: "0644"}
  - name: bring the stack up
    depends_on: [compose-file, index-file]
    resource:
      script:
        program: bash
        manages: demo-compose-stack
        # Re-run only when the compose or content files change, rather than on
        # every apply (0027). On first apply they are created, so the stack
        # comes up; later applies that change nothing leave it alone.
        rerun_on: [compose-file, index-file]
        apply: |
          cd /opt/ordo-demo-stack || exit 1
          docker compose up -d --remove-orphans
        undo: |
          cd /opt/ordo-demo-stack || exit 1
          docker compose down