Deployment

A production build is a directory of static files. There is no server process, no database and no runtime to keep alive.

Build

agno check
agno build --clean --minify

--clean is the right default in CI: a fresh checkout has no cache anyway, and it removes any doubt about stale output.

What gets uploaded

Upload the contents of dist/, not the dist/ directory itself:

dist/
├── index.html
├── 404.html
├── rss.xml
├── sitemap.xml
├── robots.txt
├── search-index.json
├── style.css
├── favicon.svg
├── docs/
│   └── installation/index.html
├── tags/
└── categories/

Never upload .agno-cache/ or content/. They are build inputs, not site output.

Hosts

Hosted build images do not all ship Rust. If agno is not available in the build image, build in CI and upload the artifact, or install a prebuilt binary in the build step.

GitHub Pages

name: Deploy

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - uses: Swatinem/rust-cache@v2
      - run: cargo install agno
      - run: agno check
      - run: agno build --clean --minify
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

If you prefer a prebuilt binary over cargo install, download the release archive in a step and put agno on PATH; the build itself is identical.

Nginx

Because pages are written as path/index.html, a directory index and a 404 rule are all you need:

server {
    listen 80;
    server_name example.com;
    root /var/www/example/dist;
    index index.html;

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

    error_page 404 /404.html;
    location = /404.html {
        internal;
    }
}

Cache headers

agno does not hash asset filenames, so do not mark CSS or JS as immutable for a year. A new deploy would keep serving the old file.

When you need aggressive caching, add a content hash to asset filenames in your own build step and reference the hashed name from templates. agno leaves that decision to you.

Preview the production build locally

agno build --clean
python3 -m http.server 8000 --directory dist

Open http://localhost:8000. This catches path issues that the dev server hides, especially absolute links and 404 handling.

Checklist

• base_url is the production domain.
• agno check passes with no broken links.
• agno build --clean succeeds.
• 404 page is served for unknown paths.
• RSS and sitemap open with absolute URLs.
• Search index is present if search is enabled.
• robots.txt points at the correct sitemap.
• Draft pages are excluded.
• .agno-cache/ and content/ are not uploaded.

Next

For every command and flag, see the CLI reference.