Repository navigation
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.
Build the site, then put the output in an image with two lines:
FROM scratch
COPY dist /sitedist 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.
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.
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 1Change 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.
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.
Published from docs/. Edit the files there; changes here are overwritten.