From f5f7db6c2a207260f2847426589597091a5d93d4 Mon Sep 17 00:00:00 2001 From: Masahiko AMANO Date: Thu, 11 Jun 2026 10:52:27 +0300 Subject: [PATCH] feat(project): containerize as a single image serving SPA + API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .dockerignore | 29 +++++++ .env.example | 10 +++ Dockerfile | 89 +++++++++++++++++++++ backend/cmd/server/main.go | 1 + backend/internal/config/config.go | 7 ++ backend/internal/handler/router.go | 10 ++- backend/internal/handler/static.go | 74 +++++++++++++++++ backend/internal/integration/server_test.go | 1 + 8 files changed, 220 insertions(+), 1 deletion(-) create mode 100644 .dockerignore create mode 100644 Dockerfile create mode 100644 backend/internal/handler/static.go diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..94f1424 --- /dev/null +++ b/.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 diff --git a/.env.example b/.env.example index dd0edb7..698ae16 100644 --- a/.env.example +++ b/.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= diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..85492c6 --- /dev/null +++ b/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"] diff --git a/backend/cmd/server/main.go b/backend/cmd/server/main.go index 939ef60..650292d 100644 --- a/backend/cmd/server/main.go +++ b/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 diff --git a/backend/internal/config/config.go b/backend/internal/config/config.go index acdeab5..a871660 100644 --- a/backend/internal/config/config.go +++ b/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 { diff --git a/backend/internal/handler/router.go b/backend/internal/handler/router.go index acc3eb4..1dce3ea 100644 --- a/backend/internal/handler/router.go +++ b/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 -} \ No newline at end of file +} diff --git a/backend/internal/handler/static.go b/backend/internal/handler/static.go new file mode 100644 index 0000000..986b3f6 --- /dev/null +++ b/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" + } +} diff --git a/backend/internal/integration/server_test.go b/backend/internal/integration/server_test.go index aa50b3b..eb58397 100644 --- a/backend/internal/integration/server_test.go +++ b/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)