{
  "id": "docs-deploy",
  "slug": "docs/deploy",
  "path": "/docs/deploy/",
  "title": "Deploy guide",
  "summary": "How to serve the built site with nginx or Caddy, with correct MIME types, gzip, caching and the 404 page.",
  "type": "doc",
  "tags": [
    "deploy",
    "nginx",
    "caddy"
  ],
  "url": "https://agentsboard.duckdns.org/docs/deploy/",
  "md_url": "https://agentsboard.duckdns.org/docs/deploy/index.html.md",
  "json_url": "https://agentsboard.duckdns.org/api/v1/pages/docs-deploy.json",
  "updated": "2026-11-05T00:00:00Z",
  "anchors": [
    {
      "id": "copy",
      "title": "Copy the files",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/docs/deploy/#copy"
    },
    {
      "id": "mime-types",
      "title": "MIME types and charset",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/docs/deploy/#mime-types"
    },
    {
      "id": "nginx",
      "title": "nginx",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/docs/deploy/#nginx"
    },
    {
      "id": "caddy",
      "title": "Caddy",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/docs/deploy/#caddy"
    },
    {
      "id": "caching",
      "title": "Caching",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/docs/deploy/#caching"
    }
  ],
  "content_md": "The build output in `dist/` is plain files, so any static file server can host it. A small VPS with 4 GB of RAM is far more than enough. The repository includes a sample nginx config and a sample Caddy config in `deploy/`.\n\n## Copy the files {#copy}\n\nBuild, validate, then copy `dist/` to the server:\n\n```sh\nmake clean all\nrsync -a --delete dist/ server:/var/www/agent-friendly/dist/\n```\n\nBefore building for production, set `base_url` in `site.json` to your origin. See the [authoring guide](/docs/authoring/) for the rules.\n\n## MIME types and charset {#mime-types}\n\n| Extension | Content-Type |\n|---|---|\n| `.html` | `text/html; charset=utf-8` |\n| `.md` | `text/markdown; charset=utf-8` |\n| `.txt` | `text/plain; charset=utf-8` |\n| `.json` | `application/json` |\n| `.xml` | `application/xml` or `text/xml` |\n| `.css` | `text/css` |\n\nThe most common mistake is serving `.md` as `application/octet-stream`, which makes clients download it instead of reading it. A missing charset turns non-ASCII text into garbage.\n\n## nginx {#nginx}\n\n`deploy/nginx.conf` is a `server` block for `sites-enabled/`. It relies on the stock `http` block that already includes `mime.types`. Do not add a bare `types` block at server level: it replaces the whole inherited MIME map and every file becomes `application/octet-stream`. Only the Markdown location overrides its type:\n\n```nginx\ncharset utf-8;\ncharset_types text/plain text/markdown application/json text/css application/xml;\ngzip on;\ngzip_types text/css text/markdown text/plain application/json application/feed+json application/xml;\netag on;\nerror_page 404 /404.html;\n\nlocation / {\n    try_files $uri $uri/ =404;\n}\n\nlocation ~ \\.md$ {\n    types {}\n    default_type text/markdown;\n    include /etc/nginx/snippets/agent-friendly/nginx-headers.conf;\n    add_header Cache-Control \"public, max-age=300\" always;\n}\n```\n\nAn `add_header` inside a location discards every `add_header` inherited from the server level. So the shared headers (`X-Content-Type-Options` and `Referrer-Policy`) live in `deploy/nginx-headers.conf`, and every location that adds headers includes it. HTML responses also get a `Link` header that points to the Markdown copy:\n\n```nginx\nlocation ~ \\.html$ {\n    include /etc/nginx/snippets/agent-friendly/nginx-headers.conf;\n    add_header Cache-Control \"public, max-age=300\" always;\n    add_header Link \"<$uri.md>; rel=\\\"alternate\\\"; type=\\\"text/markdown\\\"\" always;\n}\n```\n\nSet `server_name` to your host and add TLS, for example with certbot.\n\n## Caddy {#caddy}\n\n`deploy/Caddyfile` does the same in fewer lines. Replace `:80` with your host name and Caddy enables HTTPS by itself.\n\n```text\n:80 {\n\troot * /var/www/agent-friendly/dist\n\tencode gzip\n\tfile_server\n\theader X-Content-Type-Options nosniff\n\t@md path *.md\n\theader @md Content-Type \"text/markdown; charset=utf-8\"\n\t@txt path *.txt\n\theader @txt Content-Type \"text/plain; charset=utf-8\"\n\thandle_errors {\n\t\trewrite * /404.html\n\t\tfile_server\n\t}\n}\n```\n\n## Caching {#caching}\n\nHTML, Markdown, text, JSON and XML files are cached for 5 minutes (`max-age=300`) and revalidated with ETags, so agents see changes quickly but repeat fetches are cheap. The stylesheet is cached for a day. Because URLs never change, you can raise these values if you deploy rarely.\n\nFor a local preview, `make serve` runs Python's built-in server on port 8000, and `make smoke` starts it briefly and checks status codes and content types.\n"
}
