Docs menu

Deploy and run

Static sites

Serve a site that's only files (Vite, Astro, Next export, Hugo) from CLI's origin with CDN cache headers. No container, billed for bandwidth only.

Explain it

Many sites are just files once they're built: a React or Vite app, a Hugo or Astro site, a landing page. Make it a static site and CLI serves the files directly, with nothing running in between, so you only pay for the bandwidth people use.

How to do it: CLI usually notices a static site by itself when you deploy. Otherwise open the app's Settings and turn on Static site, with the folder your build writes to.

New versions show up straight away, and files are cached for speed.

Plenty of sites are only files once they're built: a Vite or Create React App bundle, an Astro or Hugo site, a Next.js static export, a landing page. They don't need a container running all day. Make the service a static site and CLI builds it as usual, then serves the output folder itself.

  • No container, so nothing runs while nobody visits. You pay for bandwidth only (5 cents per GB unless the operator changes it).
  • Cache headers a CDN can use. Asset names with a content hash (index-BkX9q2a1.js) are cached by browsers and CDNs for a year. HTML is revalidated every minute, so a new version shows up straight away.
  • Instant rollbacks. Each version is kept as its own set of files, and a rollback publishes the old version's files again.

Turn it on

On the service's settings, under Static site, give the folder your build writes to, then deploy.

API
PUT /v1/services/:id/static-site {"outputDir": "dist", "spa": false}
POST /v1/services/:id/deploys
FrameworkOutput folder
Vite, Vue, SvelteKit (static adapter)dist or build
Create React Appbuild
Next.js with output: "export"out
Astrodist
Hugo, Jekyll (_site)public

Set spa: true for single-page apps with client-side routing. Unknown paths like /dashboard/settings then get index.html (missing files with an extension, like /logo.png, still return 404).

How paths are served

  • / and /docs/ serve index.html from that folder.
  • /pricing serves pricing.html if there is one. /docs redirects to /docs/ when docs/index.html exists.
  • A missing page serves your 404.html with status 404 if you have one.
  • Only GET and HEAD are answered. Requests with If-None-Match get a 304 when nothing has changed.

The output folder must contain index.html. If it doesn't, the deploy fails with STATIC_PUBLISH_FAILED and the previous version keeps serving. Limits are 20,000 files and 1 GB per site.

Domains and the CDN

Custom domains work as they do for any app (/docs/domains-and-networking). If the operator puts Cloudflare in front of CLI and sets CLI_CDN_CLOUDFLARE_TOKEN and CLI_CDN_CLOUDFLARE_ZONE, CLI purges the site's hostnames on every publish.

GET /v1/services/:id/static-site shows the live files and the last day's requests, bytes and cost.

Back to a container

Run as a container instead (or PUT … {"enabled": false}) stops serving the files. The next deploy runs the app normally. Agents can do all of this with cli_static_site.