Deployment

Overview

dossiers build produces a plain static site — just HTML, CSS, and a little JavaScript. There is no server-side runtime to operate, so the output can be hosted on any static hosting service, CDN, or web server. This page shows the most common setups.

Building your site

Generate the static site from your specification repository:

dossiers build ./specs -o ./dist

The ./dist directory now contains the complete site. Everything below is just a matter of getting that directory onto a host.

Because Dossiers reads creation and update dates from Git history, make sure builds run in a full clone — a shallow checkout will make all documents look freshly created.

GitHub Pages

The most common setup for repositories already on GitHub: rebuild and publish the site on every push to main. Create .github/workflows/publish.yml in your specification repository:

name: Publish specs

on:
  push:
    branches: [main]

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # full history, so Git timestamps are accurate
      - run: cargo install dossiers
      - run: dossiers build ./specs -o ./dist
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment: github-pages
    steps:
      - uses: actions/deploy-pages@v4

Then enable Pages in your repository settings and select GitHub Actions as the source. Your specs will be live at https://<org>.github.io/<repo>/ after the next push.

Netlify and Vercel

Both platforms can serve the build output directly. The simplest approach is to build in CI (or locally) and deploy the ./dist directory with the platform CLI:

# Netlify
netlify deploy --prod --dir ./dist

# Vercel
cd dist && vercel --prod

You can also connect the repository in the platform dashboard and configure the build command (dossiers build ./specs -o ./dist) and publish directory (dist) there. Note that the build image needs a Rust toolchain to run cargo install — building in your own CI and deploying the finished directory avoids that requirement entirely.

Your own server

Copy the output directory to your server and point any web server at it. A minimal nginx configuration:

server {
    listen 80;
    server_name specs.example.com;

    root /var/www/specs;
    index index.html;
}

For internal documentation, this works equally well behind your VPN or an authenticating reverse proxy such as Cloudflare Access.

The hosted service

If you'd rather not run any of this yourself, the upcoming hosted service at dossie.rs updates automatically from your repository and adds authentication and full-text search on top. See pricing for details.

Next steps