# Deploy guide

> How to serve the built site with nginx or Caddy, with correct MIME types, gzip, caching and the 404 page.

Canonical: <https://agentsboard.duckdns.org/docs/deploy/>
Updated: 2026-11-05

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/`.

<!-- #copy -->
## Copy the files

Build, validate, then copy `dist/` to the server:

```sh
make clean all
rsync -a --delete dist/ server:/var/www/agent-friendly/dist/
```

Before building for production, set `base_url` in `site.json` to your origin. See the [authoring guide](/docs/authoring/) for the rules.

<!-- #mime-types -->
## MIME types and charset

| Extension | Content-Type |
|---|---|
| `.html` | `text/html; charset=utf-8` |
| `.md` | `text/markdown; charset=utf-8` |
| `.txt` | `text/plain; charset=utf-8` |
| `.json` | `application/json` |
| `.xml` | `application/xml` or `text/xml` |
| `.css` | `text/css` |

The 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.

<!-- #nginx -->
## nginx

`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:

```nginx
charset utf-8;
charset_types text/plain text/markdown application/json text/css application/xml;
gzip on;
gzip_types text/css text/markdown text/plain application/json application/feed+json application/xml;
etag on;
error_page 404 /404.html;

location / {
    try_files $uri $uri/ =404;
}

location ~ \.md$ {
    types {}
    default_type text/markdown;
    include /etc/nginx/snippets/agent-friendly/nginx-headers.conf;
    add_header Cache-Control "public, max-age=300" always;
}
```

An `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:

```nginx
location ~ \.html$ {
    include /etc/nginx/snippets/agent-friendly/nginx-headers.conf;
    add_header Cache-Control "public, max-age=300" always;
    add_header Link "<$uri.md>; rel=\"alternate\"; type=\"text/markdown\"" always;
}
```

Set `server_name` to your host and add TLS, for example with certbot.

<!-- #caddy -->
## Caddy

`deploy/Caddyfile` does the same in fewer lines. Replace `:80` with your host name and Caddy enables HTTPS by itself.

```text
:80 {
	root * /var/www/agent-friendly/dist
	encode gzip
	file_server
	header X-Content-Type-Options nosniff
	@md path *.md
	header @md Content-Type "text/markdown; charset=utf-8"
	@txt path *.txt
	header @txt Content-Type "text/plain; charset=utf-8"
	handle_errors {
		rewrite * /404.html
		file_server
	}
}
```

<!-- #caching -->
## Caching

HTML, 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.

For 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.
