Deployment

What the host must be able to do#

Four capabilities, and nothing else. Any host that has them will do.

The shipped configuration#

A created site ships one adapter per family of hosts. None of them holds a rule: the routes are declared once, in src/lib/api.ts. The folders of a host you do not use can be deleted without breaking anything.

Configuring the first one takes three lines. Nothing else in the code depends on the host.

# No secret here: variables are declared in .dev.vars locally and in the
# project configuration in production.
name = "martin-bakery"
compatibility_date = "2026-08-17"
pages_build_output_dir = "dist"

Deploying, step by step#

1. Create the project, wired to the repository

   Build command	npm run build
   Output folder	dist
   Production branch	main — the same as GIT_BRANCH
   Node version	20 or later (NODE_VERSION variable if needed)

2. Set the variables as runtime secrets

   Not as build variables. A build variable can end up in the served files; a runtime secret is readable only by the function.

   EDITOR_KEY_HASH=$argon2id$v=19$m=19456,t=2,p=1$…
   SESSION_SECRET=…
   EDITOR_NAME=Site editor
   EDITOR_EMAIL=contact@martin-bakery.com
   GIT_PROVIDER=github
   GIT_REPO=agency/martin-bakery
   GIT_BRANCH=main
   GIT_TOKEN=…

3. Declare the RATE_LIMIT key-value binding

   Create a key-value store, then bind it to the project under the exact name RATE_LIMIT — that is the name the code looks for.

4. Deploy, then verify

   See the checklist below. Three commands and two manual trials.

Without the counting binding#

Counting falls back to an in-memory counter. It works, it raises no error, and it protects nothing in production: each instance counts on its own, and a cold start resets it. Exactly the kind of gap that only shows up during an incident.

The check is simple: five wrong keys in a row on /admin must end with a wait message. If the sixth attempt is still refused with “incorrect key”, the limit is not active. Do not ship.

The domain#

• Add the client's domain to the project, and wait for the certificate.
• HTTPS is required, not merely desirable: the session cookie carries the Secure attribute, so it is not sent in the clear. Over HTTP, authentication cannot work.
• Check the redirect from the domain without www to the one with, or the other way round — a single canonical address.
• Update site in astro.config.mjs: it is what builds canonical URLs and hreflang links.

Another host#

Netlify and a plain Node process already ship — see the table above. For a platform without its adapter, there is a single file to write, and it decides nothing: api.handle picks the route and the method, the logic stays in the package.

import { api } from '../../src/lib/api';

// The platform provides (request, context); the router expects (request, env).
export default async (request: Request) => api.handle(request, process.env);

export const config = { path: '/api/*' };

Serving locally, like production#

npm run build
npm run serve:functions     # site + functions on http://127.0.0.1:8788

That is the only mode that actually runs /functions. npm run dev serves the site without the routes: useful for layout, useless for editing.

Checks before shipping#

# 1. The functions are running — check this before anything else
curl -s -o /dev/null -w "%{http_code}
" https://the-site.com/api/auth          # → 405

# 2. Content is in the raw HTML
curl -s https://the-site.com/en/ | grep -c "a page title"                 # → 1

# 3. Writing is closed without a session
curl -s -o /dev/null -w "%{http_code}\n" -X POST https://the-site.com/api/save   # → 401

# 4. Unexpected methods are refused
curl -s -o /dev/null -w "%{http_code}\n" https://the-site.com/api/save           # → 405

# 5. No secret in the served files
curl -s https://the-site.com/en/ | grep -Ec "argon2|github_pat|GIT_TOKEN"         # → 0

• The five commands above give the expected result.
• Five wrong keys in a row end with a wait message.
• The RATE_LIMIT binding is declared and bound to the right project.
• Variables are runtime secrets, not build variables.
• The token is restricted to the site's repository only.
• A test publish from /admin produces a commit, then a rebuild.
• The domain is on HTTPS, with a single canonical address.
• site in astro.config.mjs points at the real domain.
• Previews do not carry the production secrets.

Rolling back#

Monitoring#

Function logs are the only place to read a write failure. You will find:

[save] écriture impossible (unauthorized)     → token expired or revoked
[save] écriture impossible (not_found)        → wrong repository, branch or path
[save] contenu refusé par le schéma [ … ]     → invalid content was submitted
[auth] débit dépassé                          → five attempts, the limit kicked in
[upload] format refusé : svg                  → a non-image file was sent

None of these messages contains a secret: no token, no hash, no cookie, no client content. That is verified by check-logs.mjs on every commit.