feat(project): containerize as a single image serving SPA + API

Add a multi-stage Dockerfile that builds the SvelteKit SPA (adapter-static,
no Node runtime in the final image) and the Go server, then ships an Alpine
runtime that serves both the static frontend and the API on one port.

- Stage 1 (node): npm ci + build → static SPA (index.html, _app, fonts, sw)
- Stage 2 (golang): CGO_ENABLED=0 static binary (image processing is pure Go)
- Stage 3 (alpine): + ffmpeg for video thumbnails, non-root user, /data volume,
  healthcheck on /health; secrets passed at runtime, not baked in

To serve the SPA on the API port, the Go server now optionally hosts static
files behind a new STATIC_DIR env var: a request maps to a real file when one
exists, otherwise falls back to index.html for client-side routes; unknown
/api/ paths still return JSON 404. Empty STATIC_DIR (local dev) keeps the API
standalone while Vite serves the UI. Cache-Control is tuned to adapter-static
output (immutable hashed assets, no-cache service worker) and .webmanifest is
registered so nosniff doesn't reject the PWA manifest.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,29 @@
+# Keep the build context small and reproducible: never ship local state,
+# dependencies, or build outputs — they are rebuilt inside the image.
+
+# VCS / tooling
+.git
+.gitignore
+**/.DS_Store
+
+# Secrets and local env
+.env
+.env.*
+!.env.example
+
+# Node
+frontend/node_modules
+frontend/.svelte-kit
+frontend/build
+frontend/.vite
+
+# Go
+backend/server
+backend/**/*.test
+
+# Docs / reference (not needed to build the image)
+docs/reference
+
+# Editor / OS
+.vscode
+.idea

.env.example

@@ -42,3 +42,13 @@ PREVIEW_HEIGHT=1080
 # Import
 # ---------------------------------------------------------------------------
 IMPORT_PATH=/data/import
+
+# ---------------------------------------------------------------------------
+# Static SPA
+# ---------------------------------------------------------------------------
+# Directory of the built frontend (index.html, _app/, fonts, service worker).
+# When set, the server serves the SPA and the API on the same port, with a
+# fallback to index.html for client-side routes. Leave empty in local
+# development — the Vite dev server serves the UI separately. The Docker image
+# sets this to /app/static.
+STATIC_DIR=

Dockerfile

@@ -0,0 +1,89 @@
+# syntax=docker/dockerfile:1
+
+# =============================================================================
+# Tanabata File Manager — single-image build
+#
+# Produces one container that serves the SvelteKit SPA (built to static files)
+# and the Go API on the same port. There is no Node runtime in the final image:
+# the frontend uses adapter-static, so stage 1 emits plain HTML/CSS/JS that the
+# Go binary serves directly (see STATIC_DIR).
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Stage 1 — build the frontend (static SPA)
+# -----------------------------------------------------------------------------
+FROM node:22-alpine AS frontend
+
+WORKDIR /src/frontend
+
+# Install dependencies first so this layer is cached unless the lockfile changes.
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+
+# `npm run build` runs `generate:types`, which reads ../openapi.yaml relative to
+# the frontend directory — place the spec one level up to match the repo layout.
+COPY openapi.yaml /src/openapi.yaml
+COPY frontend/ ./
+
+RUN npm run build
+# Output: /src/frontend/build (index.html, _app/, fonts, service-worker.js, …)
+
+# -----------------------------------------------------------------------------
+# Stage 2 — build the Go server (static binary)
+# -----------------------------------------------------------------------------
+FROM golang:1.26-alpine AS backend
+
+WORKDIR /src/backend
+
+# Download modules first so this layer is cached unless go.mod/go.sum changes.
+COPY backend/go.mod backend/go.sum ./
+RUN go mod download
+
+COPY backend/ ./
+
+# CGO is disabled: image processing is pure Go (disintegration/imaging) and
+# video thumbnails shell out to the ffmpeg binary at runtime, so the resulting
+# binary is fully static and portable across base images.
+RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags="-s -w" -o /out/server ./cmd/server
+
+# -----------------------------------------------------------------------------
+# Stage 3 — minimal runtime
+#
+# Alpine (not distroless/scratch) because video thumbnailing invokes ffmpeg as
+# an external process; it must be present on the runtime image.
+# -----------------------------------------------------------------------------
+FROM alpine:3.21 AS runtime
+
+# ffmpeg: video frame extraction. ca-certificates/tzdata: TLS + time zones.
+RUN apk add --no-cache ffmpeg ca-certificates tzdata
+
+# Run as an unprivileged user.
+RUN addgroup -S app && adduser -S -G app -u 10001 app
+
+WORKDIR /app
+
+# The built SPA, served by the Go binary (matches STATIC_DIR below).
+COPY --from=frontend --chown=app:app /src/frontend/build /app/static
+# The server binary.
+COPY --from=backend --chown=app:app /out/server /app/server
+
+# Data directories (overridable via FILES_PATH/THUMBS_CACHE_PATH/IMPORT_PATH).
+# Created and owned by the app user so a fresh named volume inherits write access.
+RUN mkdir -p /data/files /data/thumbs /data/import && chown -R app:app /data
+
+# Non-secret defaults mirroring .env.example. Secrets (JWT_SECRET, ADMIN_PASSWORD,
+# DATABASE_URL) are intentionally NOT baked in — pass them at `docker run`.
+ENV LISTEN_ADDR=:8080 \
+    STATIC_DIR=/app/static \
+    FILES_PATH=/data/files \
+    THUMBS_CACHE_PATH=/data/thumbs \
+    IMPORT_PATH=/data/import
+
+EXPOSE 8080
+VOLUME ["/data"]
+USER app
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+    CMD wget -qO- http://127.0.0.1:8080/health >/dev/null 2>&1 || exit 1
+
+ENTRYPOINT ["/app/server"]

backend/cmd/server/main.go

@@ -117,6 +117,7 @@ func main() {
 		authMiddleware, authHandler,
 		fileHandler, tagHandler, categoryHandler, poolHandler,
 		userHandler, aclHandler, auditHandler,
+		cfg.StaticDir,
 	)
 
 	// ReadHeaderTimeout bounds slow-header (Slowloris) attacks; body read/write

backend/internal/config/config.go

@@ -38,6 +38,11 @@ type Config struct {
 
 	// Import
 	ImportPath string
+
+	// Static SPA. When set, the server serves the built frontend (and falls
+	// back to index.html for client routes) on the same port as the API. Empty
+	// in local development, where the Vite dev server serves the UI separately.
+	StaticDir string
 }
 
 // Load reads a .env file (if present) then loads all configuration from
@@ -120,6 +125,8 @@ func Load() (*Config, error) {
 		PreviewHeight: parseInt("PREVIEW_HEIGHT", 1080),
 
 		ImportPath: requireStr("IMPORT_PATH"),
+
+		StaticDir: defaultStr("STATIC_DIR", ""),
 	}
 
 	if len(errs) > 0 {

backend/internal/handler/router.go

@@ -31,6 +31,7 @@ func NewRouter(
 	userHandler *UserHandler,
 	aclHandler *ACLHandler,
 	auditHandler *AuditHandler,
+	staticDir string,
 ) *gin.Engine {
 	r := gin.New()
 	r.Use(gin.Logger(), gin.Recovery(), securityHeaders())
@@ -179,5 +180,12 @@ func NewRouter(
 	// -------------------------------------------------------------------------
 	v1.GET("/audit", auth.Handle(), auditHandler.List)
 
+	// Serve the built single-page app on the same port as the API. When
+	// staticDir is empty (local development) the Vite dev server serves the UI
+	// instead, so the API runs standalone and unknown routes 404 normally.
+	if staticDir != "" {
+		r.NoRoute(spaHandler(staticDir))
+	}
+
 	return r
-}
+}

backend/internal/handler/static.go

@@ -0,0 +1,74 @@
+package handler
+
+import (
+	"mime"
+	"net/http"
+	"os"
+	"path"
+	"path/filepath"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+func init() {
+	// Go's mime table doesn't know .webmanifest; register it so the PWA manifest
+	// is served as JSON and isn't rejected by the X-Content-Type-Options header.
+	_ = mime.AddExtensionType(".webmanifest", "application/manifest+json")
+}
+
+// spaHandler serves the built single-page app from dir. It is wired as the
+// router's NoRoute handler, so it only sees requests that matched no API route.
+//
+// A request whose path maps to a real file on disk is served directly (with
+// cache headers tuned to SvelteKit's adapter-static output). Anything else
+// falls back to index.html so the client-side router can resolve deep links
+// like /pools/123. Unknown /api/ paths return a JSON 404 instead of the HTML
+// shell, keeping API error responses machine-readable.
+func spaHandler(dir string) gin.HandlerFunc {
+	indexPath := filepath.Join(dir, "index.html")
+
+	return func(c *gin.Context) {
+		reqPath := c.Request.URL.Path
+
+		if strings.HasPrefix(reqPath, "/api/") {
+			c.JSON(http.StatusNotFound, errorBody{
+				Code:    "not_found",
+				Message: "resource not found",
+			})
+			return
+		}
+
+		// Resolve the request to a path inside dir. Cleaning an absolute path
+		// collapses any "../" segments before the join, so the result can never
+		// escape dir — this is the traversal guard.
+		clean := path.Clean("/" + reqPath)
+		target := filepath.Join(dir, filepath.FromSlash(clean))
+
+		if info, err := os.Stat(target); err == nil && !info.IsDir() {
+			c.Header("Cache-Control", cacheControl(clean))
+			c.File(target)
+			return
+		}
+
+		// SPA fallback: serve the shell, never cached so a new deploy is picked
+		// up immediately on the next navigation.
+		c.Header("Cache-Control", "no-cache")
+		c.File(indexPath)
+	}
+}
+
+// cacheControl returns the Cache-Control value for a served static asset.
+// SvelteKit emits content-hashed files under /_app/immutable — those are safe
+// to cache forever. The service worker must never be cached, or clients pin to
+// a stale shell. Everything else gets a short, revalidated TTL.
+func cacheControl(p string) string {
+	switch {
+	case strings.HasPrefix(p, "/_app/immutable/"):
+		return "public, max-age=31536000, immutable"
+	case p == "/service-worker.js":
+		return "no-cache"
+	default:
+		return "public, max-age=3600"
+	}
+}

backend/internal/integration/server_test.go

@@ -152,6 +152,7 @@ func setupSuite(t *testing.T) *harness {
 		authMiddleware, authHandler,
 		fileHandler, tagHandler, categoryHandler, poolHandler,
 		userHandler, aclHandler, auditHandler,
+		"",
 	)
 
 	srv := httptest.NewServer(r)