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
- Push the code to a GitHub repository (public, or connect the account with
connect_github). - Make sure
npm run buildworks and writes todist/(Vite's default). Nothing else is needed: without a Dockerfile the platform builds with Railpack and servesdist/with SPA fallback. Create the app:
create_app(app="glosboken", source_repo="https://github.com/<owner>/glosboken")It gets
https://glosboken.shipholm.dev(orglosboken-01… when the name is taken –check_host(host="glosboken")tells you first). It buildsmain; passbranch=if the work lives on another branch. Check which one has the newest code first.- Call
app_status(app=...)untilready=true(the first build takes a few minutes). Every later push to the branch deploys by itself. 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/pngWith SPA fallback, a file that did not make it into the build comes back as
index.htmlwith 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:
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
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:
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:
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=truesaves 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=truegives 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 withset_env(..., secret=true).
Use when: 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.
For agents: get_skill("shipholm-static-site") over MCP, or the SKILL.md at https://api.shipholm.com/skills/shipholm-static-site/SKILL.md.