Skip to content

Static Sites

github-actions[bot] edited this page Nov 22, 2026 · 1 revision

Static sites

A site that is only files, such as a marketing site, a docs site or an app that runs in the browser, runs on Spotcraft as a static site (ADR 0052). Its image holds the built files, and Spotcraft serves them with its own server. What a site gets is in the contract.

The image

Build the site, then put the output in an image with two lines:

FROM scratch
COPY dist /site

dist is wherever your build writes its files (build, out, public…). The image has nothing else: no server, no shell. It needs a 404.html for the default fallback below, and an index.html.

Add it

In the dashboard, choose Add app, then Static site. Give it a name, the image and a tag. It is served at <name>.<apps domain>, and at your own domain if you add one.

Unknown paths is the site's one setting:

  • Static: 404.html (the default): a path the site doesn't have gets its 404.html, with status 404.
  • Single-page app: index.html: every such path gets its index.html, so the app can route in the browser.

Deploy from CI

Turn on the site's deploy hook and save the token as SPOTCRAFT_DEPLOY_TOKEN, as in Deploy from CI. This job builds the site, builds the image for both platforms, pushes it to Docker Hub, and deploys it. A scratch image with only COPY costs nothing to build for a second platform, and the server's platform always matches.

name: Deploy

on:
  push:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: deploy
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: pnpm/action-setup@73e46992e05b19abd31f2f3c20e0e7370d762115 # v6.1.1
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version-file: .nvmrc
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm build

      - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
      - uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550 # v4.8.0
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      - id: meta
        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
        with:
          images: ${{ vars.DOCKERHUB_USERNAME }}/website
          tags: type=sha,format=short
      - uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ steps.meta.outputs.tags }}

      - name: Deploy to Spotcraft
        timeout-minutes: 20
        env:
          URL: https://dash.example.com/hooks/deploy/website
          TOKEN: ${{ secrets.SPOTCRAFT_DEPLOY_TOKEN }}
          WAIT_MINUTES: 15
        run: |
          TAG="sha-${GITHUB_SHA::7}"
          auth="Authorization: Bearer $TOKEN"
          curl -fsS --retry 5 --retry-all-errors -X POST "$URL" -H "$auth" \
            -H 'content-type: application/json' -d "{\"tag\":\"$TAG\"}"
          deadline=$((SECONDS + WAIT_MINUTES * 60))
          while [ "$SECONDS" -lt "$deadline" ]; do
            sleep 5
            result=$(curl -fsS "$URL" -H "$auth") || continue
            case $(echo "$result" | jq -r '.state + " " + .tag') in
              "live $TAG") exit 0 ;;
              live*) echo "Another tag is live: $result"; exit 1 ;;
              failed*) echo "$result"; exit 1 ;;
            esac
          done
          echo "Not live after $WAIT_MINUTES minutes"; exit 1

Change the build steps to your site's, website to your image's name, and the hook's URL to the one the dashboard shows on the site's Settings page. Keep the .dockerignore from leaving out the build output.

A deploy starts the new version next to the old one, and moves traffic once it answers, as for any app. To roll back, deploy the previous tag from the dashboard.

Headers and the CSP

A site can't send headers of its own. Spotcraft sends the security headers for it. Put the site's Content Security Policy in a <meta> tag in each page's <head>:

<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'" />

A <meta> CSP can't set frame-ancestors; the platform's X-Frame-Options: DENY keeps the site out of frames instead.

Clone this wiki locally