getting-started.md

Back to README · Development →

Getting Started

Prerequisites

• Docker
• A built SPA bundle (for example, dist/ from Vite, Webpack, or similar)

Run a Local Build (Docker)

# Serve ./dist at http://localhost:8080
docker run --rm -p 8080:8080 -v $(pwd)/dist:/code devforth/spa-to-http:latest

Open http://localhost:8080 in your browser.

Basic Auth (Docker)

docker run --rm -p 8080:8080 \
  -e BASIC_AUTH="admin:secret" \
  -e BASIC_AUTH_REALM="SPA Server" \
  -v $(pwd)/dist:/code \
  devforth/spa-to-http:latest

Build + Run in One Dockerfile

Use this pattern when you want to build the SPA and ship a small runtime image:

FROM node:20-alpine AS builder
WORKDIR /code
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM devforth/spa-to-http:latest
COPY --from=builder /code/dist/ .

Build and run:

docker build -t my-spa .
docker run --rm -p 8080:8080 my-spa

Next Steps

• Configure compression, cache settings, and ports in Configuration
• Deploy behind Traefik or another reverse proxy in Deployment
• For source-based local runs and contributor workflow, see Development

See Also

• Development — Local setup, source runs, and fixture usage
• Configuration — Environment variables and CLI flags
• Deployment — Docker and reverse proxy setup
• Architecture — Project structure and request flow