---
name: shipholm-static-site
description: "Publish a frontend with no backend on Shipholm – a Vite, React, Vue or Svelte app, a game or plain HTML. Use when the app runs entirely in the browser and keeps no data on a server."
---

# Static site or frontend app
Publish a Vite/React/Vue/Svelte app, a game or plain HTML with no backend – the most common case.

## When this fits
The app runs entirely in the browser: no server code, no secrets, data only in `localStorage`
(or in an external API it calls from the browser). For data on the server, see `shipholm-sqlite-app`.

## Steps
1. Push the code to a GitHub repository (public, or connect the account with `connect_github`).
2. Make sure `npm run build` works and writes to `dist/` (Vite's default). Nothing else is needed:
   without a Dockerfile the platform builds with Railpack and serves `dist/` with SPA fallback.
3. Create the app:
   ```
   create_app(app="glosboken", source_repo="https://github.com/<owner>/glosboken")
   ```
   It gets `https://glosboken.shipholm.dev` (or `glosboken-01` … when the name is taken –
   `check_host(host="glosboken")` tells you first). It builds `main`; pass `branch=` if the work
   lives on another branch. Check which one has the newest code first.
4. Call `app_status(app=...)` until `ready=true` (the first build takes a few minutes). Every
   later push to the branch deploys by itself.
5. Check that the files are served as what they are, not only the page:
   ```
   curl -sI https://glosboken.shipholm.dev/favicon.png    # content-type: image/png
   ```
   With SPA fallback, a file that did not make it into the build comes back as `index.html` with
   status 200. The page looks right, but icons, card images and the manifest are broken.

## Your own Dockerfile (optional)
A plain nginx image works as is – `/run` and `/var/cache/nginx` are writable:
```dockerfile
FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:1.27-alpine
COPY deploy/nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=build /app/dist /usr/share/nginx/html
```
```nginx
server {
    listen 8080;
    root /usr/share/nginx/html;
    index index.html;
    gzip on;
    gzip_types text/css application/javascript application/json image/svg+xml;
    location /assets/ {                      # Vite's hashed files: cache for a year, never fall back
        expires 1y;
        add_header Cache-Control "public, immutable";
        try_files $uri =404;
    }
    location / {
        try_files $uri $uri/ /index.html;    # SPA; for plain HTML use: try_files $uri $uri/ =404;
        add_header Cache-Control "no-cache";
    }
}
```
Listen on port 8080 (`$PORT`). The container runs as a non-root user on a read-only filesystem.

Plain HTML (no build step): copy only the site, not the repository. `COPY . /usr/share/nginx/html`
also publishes the Dockerfile and `deploy/nginx.conf`. Put the site in a folder (`COPY site/ …`),
or remove what does not belong after the copy:
```dockerfile
FROM nginx:1.27-alpine
COPY deploy/nginx.conf /etc/nginx/conf.d/default.conf
COPY . /usr/share/nginx/html
RUN rm -rf /usr/share/nginx/html/deploy /usr/share/nginx/html/Dockerfile
```
`.dockerignore` decides what the build can see. Never list a file there that the Dockerfile
copies (`deploy/`): the build then fails with `failed to compute cache key … not found`.

Caddy works too, with one extra line. The official image's `caddy` binary carries a file
capability (to bind port 80), and the platform runs containers without privilege escalation, so
starting it fails with `caddy: Operation not permitted`. A plain copy of the binary drops the
capability:
```dockerfile
FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM caddy:2.10-alpine
RUN cp /usr/bin/caddy /tmp/caddy && mv /tmp/caddy /usr/bin/caddy   # drop the file capability
COPY Caddyfile /etc/caddy/Caddyfile
COPY --from=build /app/dist /srv
```
```
{
	auto_https off
	admin off
}
:8080 {
	root * /srv
	encode gzip
	try_files {path} /index.html
	file_server
}
```
HTTPS is handled in front of the app, so `auto_https off`; Caddy keeps its state in `/tmp`
(the platform points `XDG_CONFIG_HOME` and `XDG_DATA_HOME` there).

## Choices
- Apps are always on by default: about 50 ms per request. `scale_to_zero=true` saves resources
  for apps that are rarely used, but the first visit after about 10 idle minutes waits 5–15 s
  (we measured 12 s). That is too slow for games children open and tap right away.
- `previews=true` gives every pull request its own address.
- Build-time values (`VITE_…`) belong in the repository – runtime variables (`set_env`) do not
  reach a static bundle.

## Pitfalls
- Client-side routes 404 on reload: the server must fall back to `index.html` (Railpack and the
  nginx config above do).
- One source of truth: the repository. If the same app is also published elsewhere (a
  publish-folder service, Lovable's hosting), the copies drift apart. Pick one and push only there.
- Do not commit API keys into a frontend bundle – anyone can read them. Move such calls to a
  small server (`shipholm-sqlite-app`) and store the key with `set_env(..., secret=true)`.
