create-volt 0.15.1 → 0.17.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to `create-volt` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [0.17.0] - 2026-06-29
+
+### Added
+- **PaaS deploy targets** — every scaffold now ships a `Dockerfile`,
+  `.dockerignore`, `render.yaml`, `fly.toml`, and `Procfile`, so a Volt app
+  deploys to Render / Fly.io / Railway / DO App Platform (which handle the
+  server, DNS, and TLS) with config supplied as platform env vars. New
+  `/docs/deploy` guide covering the PaaS and PM2+nginx paths.
+
+### Changed
+- The server boots straight into app mode (no setup wizard) when
+  `NODE_ENV=production` or `VOLT_ADDONS` is set via env — so a container/PaaS
+  runs the app from platform env vars without a committed `.env`.
+
+## [0.16.0] - 2026-06-29
+
+### Added
+- **`media` add-on** — file uploads with a swappable storage driver: `local`
+  (disk, served at `/media`) or `s3` (any S3-compatible store: AWS S3,
+  DigitalOcean Spaces, …). `POST /api/media` is auth-gated (depends on the auth
+  add-on); uploads are size-capped (`MEDIA_MAX_MB`, default 10), restricted to
+  raster images + PDF (SVG rejected), stored under a random key, and returned as
+  a public URL. Driver + S3 settings are configured in the setup wizard. Pulls in
+  `busboy` (and `@aws-sdk/client-s3` when `MEDIA_DRIVER=s3`), both tracked by the
+  dependency auto-updater and exercised by the smoke gate.
+
 ## [0.15.1] - 2026-06-29
 
 ### Fixed
@@ -230,6 +256,8 @@ All notable changes to `create-volt` are documented here. The format follows
   watching and full-page hot reload. Supports `--skip-install` and `--force`,
   and auto-detects npm / pnpm / yarn / bun for the install step.
 
+[0.17.0]: https://github.com/MIR-2025/volt/releases/tag/v0.17.0
+[0.16.0]: https://github.com/MIR-2025/volt/releases/tag/v0.16.0
 [0.15.1]: https://github.com/MIR-2025/volt/releases/tag/v0.15.1
 [0.15.0]: https://github.com/MIR-2025/volt/releases/tag/v0.15.0
 [0.14.0]: https://github.com/MIR-2025/volt/releases/tag/v0.14.0

package/addons/media/files/lib/media.js

@@ -0,0 +1,99 @@
+// media.js — media uploads with a swappable storage driver: `local` (disk,
+// served at /media) or `s3` (any S3-compatible store: AWS S3, DigitalOcean
+// Spaces, etc.). POST /api/media is auth-gated; objects are stored under a
+// random key and a public URL is returned. express/busboy/aws-sdk are imported
+// lazily so the pure helpers below load without those deps installed.
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+// allowlist — raster images + PDF (no SVG: it can carry script). Extend via code.
+const ALLOWED = { "image/jpeg": "jpg", "image/png": "png", "image/gif": "gif", "image/webp": "webp", "image/avif": "avif", "application/pdf": "pdf" };
+export const extFor = (mime) => ALLOWED[mime] || null;
+export const isAllowed = (mime) => !!ALLOWED[mime];
+export const genKey = (mime) => `${crypto.randomBytes(10).toString("hex")}.${extFor(mime)}`;
+
+function localDriver({ dir }) {
+  fs.mkdirSync(dir, { recursive: true });
+  return {
+    name: "local",
+    async put(key, buf) {
+      fs.writeFileSync(path.join(dir, key), buf);
+      return `/media/${key}`;
+    },
+  };
+}
+
+async function s3Driver(env) {
+  const { S3Client, PutObjectCommand } = await import("@aws-sdk/client-s3");
+  const endpoint = (env.S3_ENDPOINT || "").replace(/\/$/, "");
+  const bucket = env.S3_BUCKET;
+  const client = new S3Client({
+    endpoint: endpoint || undefined,
+    region: env.S3_REGION || "us-east-1",
+    credentials: { accessKeyId: env.S3_KEY, secretAccessKey: env.S3_SECRET },
+    forcePathStyle: true, // safest across S3-compatible endpoints (e.g. Spaces)
+  });
+  const base = (env.S3_PUBLIC_BASE || (endpoint ? `${endpoint}/${bucket}` : "")).replace(/\/$/, "");
+  return {
+    name: "s3",
+    async put(key, buf, mime) {
+      await client.send(new PutObjectCommand({ Bucket: bucket, Key: key, Body: buf, ContentType: mime, ACL: "public-read" }));
+      return `${base}/${key}`;
+    },
+  };
+}
+
+export async function mediaRouter({ requireAuth, dir, env = process.env }) {
+  const express = (await import("express")).default;
+  const busboy = (await import("busboy")).default;
+  const driver = env.MEDIA_DRIVER === "s3" ? await s3Driver(env) : localDriver({ dir });
+  const maxMb = Number(env.MEDIA_MAX_MB) || 10;
+  const r = express.Router();
+
+  if (driver.name === "local") r.use("/media", express.static(dir)); // public reads
+
+  r.post("/api/media", requireAuth, (req, res) => {
+    let bb;
+    try {
+      bb = busboy({ headers: req.headers, limits: { files: 1, fileSize: maxMb * 1024 * 1024 } });
+    } catch {
+      return res.status(400).json({ ok: false, error: "bad upload" });
+    }
+    let done = false;
+    const finish = (code, body) => {
+      if (!done) {
+        done = true;
+        res.status(code).json(body);
+      }
+    };
+    bb.on("file", (_name, stream, info) => {
+      if (!isAllowed(info.mimeType)) {
+        stream.resume();
+        return finish(415, { ok: false, error: "unsupported file type" });
+      }
+      const chunks = [];
+      let tooBig = false;
+      stream.on("data", (c) => chunks.push(c));
+      stream.on("limit", () => {
+        tooBig = true;
+        finish(413, { ok: false, error: `file exceeds ${maxMb}MB` });
+      });
+      stream.on("end", async () => {
+        if (tooBig || done) return;
+        try {
+          const key = genKey(info.mimeType);
+          const url = await driver.put(key, Buffer.concat(chunks), info.mimeType);
+          finish(200, { ok: true, url, key, driver: driver.name });
+        } catch (e) {
+          finish(500, { ok: false, error: e.message });
+        }
+      });
+    });
+    bb.on("error", () => finish(500, { ok: false, error: "upload failed" }));
+    bb.on("close", () => finish(400, { ok: false, error: "no file uploaded" }));
+    req.pipe(bb);
+  });
+
+  return r;
+}

package/addons/media/meta.json

@@ -0,0 +1,8 @@
+{
+  "description": "Media uploads to local disk or any S3-compatible store (AWS S3, DigitalOcean Spaces, etc.). POST /api/media (signed-in only) returns a public URL. Choose the driver in the wizard.",
+  "dependsOn": ["auth"],
+  "sentinel": "lib/media.js",
+  "install": ["busboy"],
+  "optional": { "s3": ["@aws-sdk/client-s3"] },
+  "wiring": "Set MEDIA_DRIVER=local|s3. For s3 set S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_KEY, S3_SECRET (and optionally S3_PUBLIC_BASE for a CDN URL). Uploads require a signed-in user; uploaded objects are public-read."
+}

package/index.js

@@ -250,6 +250,11 @@ const shippedEnv = path.join(targetDir, "env");
 if (fs.existsSync(shippedEnv)) {
   fs.renameSync(shippedEnv, path.join(targetDir, ".env"));
 }
+// ship "dockerignore" → ".dockerignore" (same npm-safety dance)
+const shippedDockerignore = path.join(targetDir, "dockerignore");
+if (fs.existsSync(shippedDockerignore)) {
+  fs.renameSync(shippedDockerignore, path.join(targetDir, ".dockerignore"));
+}
 
 // Bundle the add-on sources so the app's setup wizard can enable them later
 // (only for templates that ship the wizard, i.e. have a setup/ dir).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-volt",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "Scaffold a new Volt app — no-build, signals-based UI with Socket.io hot reload.",
   "type": "module",
   "bin": {

package/templates/default/Dockerfile

@@ -0,0 +1,20 @@
+# Volt app — production container. Runs on Render, Fly.io, Railway, DO App
+# Platform, and any container host. They handle the server, DNS, and TLS; you
+# just set config as env vars.
+#
+# Configure via the platform's env vars (NOT a committed .env):
+#   VOLT_ADDONS=db,auth,...      DB_DRIVER=...   MONGODB_URI / DATABASE_URL
+#   MEDIA_DRIVER=s3   S3_ENDPOINT/S3_REGION/S3_BUCKET/S3_KEY/S3_SECRET   etc.
+#
+# Tip: run the local wizard first (`npm run dev`) so the add-on packages are
+# saved into package.json; commit package.json, then deploy and set the same
+# config as env vars here. NODE_ENV=production makes the app boot straight up
+# (no setup wizard).
+FROM node:22-alpine
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package*.json ./
+RUN npm install --omit=dev
+COPY . .
+EXPOSE 8080
+CMD ["node", "server.js"]

package/templates/default/Procfile

@@ -0,0 +1 @@
+web: node server.js

package/templates/default/dockerignore

@@ -0,0 +1,6 @@
+node_modules
+.git
+.env
+*.log
+npm-debug.log*
+.DS_Store

package/templates/default/fly.toml

@@ -0,0 +1,15 @@
+# Fly.io — run `fly launch` (it uses the Dockerfile), then set config:
+#   fly secrets set VOLT_ADDONS=db,auth DB_DRIVER=mongodb MONGODB_URI=...
+app = "volt-app"
+
+[build]
+
+[http_service]
+  internal_port = 8080
+  force_https = true
+  auto_stop_machines = true
+  auto_start_machines = true
+
+[env]
+  PORT = "8080"
+  NODE_ENV = "production"

package/templates/default/render.yaml

@@ -0,0 +1,15 @@
+# Render blueprint — https://render.com/docs/blueprint-spec
+# Push this repo to GitHub, then in Render: New → Blueprint → pick the repo.
+# Render builds the Dockerfile, gives you HTTPS + a domain, and runs it.
+services:
+  - type: web
+    name: volt-app
+    runtime: docker
+    plan: starter
+    envVars:
+      - key: VOLT_ADDONS
+        sync: false # set your add-ons (e.g. "db,auth") in the dashboard
+      # Add the rest in the dashboard as needed:
+      #   DB_DRIVER, MONGODB_URI / DATABASE_URL,
+      #   MEDIA_DRIVER, S3_ENDPOINT/S3_REGION/S3_BUCKET/S3_KEY/S3_SECRET,
+      #   SMTP_URL, MAIL_FROM

package/templates/default/server.js

@@ -21,8 +21,8 @@ const ENV_PATH = path.join(__dirname, ".env");
 const PKG_PATH = path.join(__dirname, "package.json");
 const ADDONS_DIR = path.join(__dirname, ".volt", "addons"); // bundled add-on sources
 const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
-const PKG_VERSIONS = { mongodb: "^6.21.0", mysql2: "^3.22.5", pg: "^8.22.0", nodemailer: "^6.10.1", marked: "^18.0.5" };
-const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", pages: "pages.js" };
+const PKG_VERSIONS = { mongodb: "^6.21.0", mysql2: "^3.22.5", pg: "^8.22.0", nodemailer: "^6.10.1", marked: "^18.0.5", busboy: "^1.6.0", "@aws-sdk/client-s3": "^3.1075.0" };
+const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", pages: "pages.js", media: "media.js" };
 
 // --- tiny .env loader (no dependency); never overrides an existing env var ---
 function readEnvFile() {
@@ -111,6 +111,12 @@ async function startApp() {
 
   app.get("/", (_req, res) => res.sendFile(path.join(__dirname, "views", "index.html")));
 
+  // media uploads (POST /api/media, auth-gated; local files served at /media)
+  if (enabled.has("media") && store) {
+    const requireAuth = (await addonMod("auth")).requireAuth(store);
+    app.use(await (await addonMod("media")).mediaRouter({ requireAuth, dir: path.join(__dirname, "media") }));
+  }
+
   // markdown pages (/<slug> ← pages/<slug>.md) — mounted last, so app routes win
   if (enabled.has("pages")) app.use(await (await addonMod("pages")).pagesRouter({ dir: path.join(__dirname, "pages") }));
 
@@ -160,6 +166,8 @@ function neededPackages(env) {
   if (driver === "postgres") want.push("pg");
   if (/^\s*SMTP_URL\s*=\s*\S/m.test(env)) want.push("nodemailer");
   if (/^\s*VOLT_ADDONS\s*=.*\bpages\b/m.test(env)) want.push("marked");
+  if (/^\s*VOLT_ADDONS\s*=.*\bmedia\b/m.test(env)) want.push("busboy");
+  if (/^\s*MEDIA_DRIVER\s*=\s*s3\b/m.test(env)) want.push("@aws-sdk/client-s3");
   return want.filter((p) => !deps[p]);
 }
 
@@ -389,9 +397,13 @@ async function startStudio() {
 
 // --- gate: studio / setup (first run, --edit) / the app ---
 const editMode = process.argv.includes("--edit") || process.argv.includes("-e");
+// In production / on a PaaS there's no interactive wizard: config comes from the
+// platform's env vars (a Dockerfile sets NODE_ENV=production). Only fall back to
+// the first-run wizard when nothing is configured and we're not in production.
+const configured = fs.existsSync(ENV_PATH) || process.env.VOLT_ADDONS != null || process.env.NODE_ENV === "production";
 if (process.argv.includes("--studio")) {
   startStudio();
-} else if (editMode || !fs.existsSync(ENV_PATH)) {
+} else if (editMode || !configured) {
   startSetup();
 } else {
   loadEnv();

package/templates/default/setup/setup.js

@@ -17,6 +17,13 @@ const state = signal({
   dbUrl: current.DATABASE_URL || "",
   smtpUrl: current.SMTP_URL || "",
   mailFrom: current.MAIL_FROM || "",
+  mediaDriver: current.MEDIA_DRIVER || "local",
+  s3Endpoint: current.S3_ENDPOINT || "",
+  s3Region: current.S3_REGION || "",
+  s3Bucket: current.S3_BUCKET || "",
+  s3Key: current.S3_KEY || "",
+  s3Secret: current.S3_SECRET || "",
+  s3PublicBase: current.S3_PUBLIC_BASE || "",
   port: current.PORT || String(defaultPort),
 });
 const set = (patch) => state({ ...state(), ...patch });
@@ -53,6 +60,17 @@ function genEnv(s) {
     else out.push("# SMTP_URL=        # unset → emails print to the console");
     if (s.mailFrom) out.push(`MAIL_FROM=${clean(s.mailFrom)}`);
   }
+  if (eff.includes("media")) {
+    out.push(`MEDIA_DRIVER=${clean(s.mediaDriver)}`);
+    if (s.mediaDriver === "s3") {
+      out.push(`S3_ENDPOINT=${clean(s.s3Endpoint)}`);
+      out.push(`S3_REGION=${clean(s.s3Region)}`);
+      out.push(`S3_BUCKET=${clean(s.s3Bucket)}`);
+      out.push(`S3_KEY=${clean(s.s3Key)}`);
+      out.push(`S3_SECRET=${clean(s.s3Secret)}`);
+      if (s.s3PublicBase) out.push(`S3_PUBLIC_BASE=${clean(s.s3PublicBase)}`);
+    }
+  }
   return out.join("\n") + "\n";
 }
 const env = computed(() => genEnv(state()));
@@ -134,6 +152,19 @@ const dbSettings = () =>
           : null}
     ${() => (state().dbDriver !== "memory" ? html`<button class="btn btn-sm btn-outline-secondary mb-2" onclick=${testDb}>Test connection</button>` : null)}`;
 
+const mediaSettings = () =>
+  html`<div class="mb-2">
+      <label class="form-label small mb-1">Media storage (MEDIA_DRIVER)</label>
+      <select class="form-select" value=${() => state().mediaDriver} onchange=${(e) => set({ mediaDriver: e.target.value })}>
+        <option value="local">local (disk)</option>
+        <option value="s3">s3 — AWS S3 / DigitalOcean Spaces</option>
+      </select>
+    </div>
+    ${() =>
+      state().mediaDriver === "s3"
+        ? html`${field("S3_ENDPOINT", "s3Endpoint", "https://nyc3.digitaloceanspaces.com")}${field("S3_REGION", "s3Region", "us-east-1")}${field("S3_BUCKET", "s3Bucket", "my-space")}${field("S3_KEY", "s3Key", "access key")}${field("S3_SECRET", "s3Secret", "secret key")}${field("S3_PUBLIC_BASE (optional CDN base)", "s3PublicBase", "https://cdn.example.com")}`
+        : null}`;
+
 mount(
   "#app",
   available.length
@@ -148,6 +179,7 @@ mount(
     ${field("PORT", "port", String(defaultPort))}
     ${() => (eff().includes("db") ? dbSettings() : null)}
     ${() => (eff().includes("mailer") ? html`${field("SMTP_URL (optional)", "smtpUrl", "smtp://user:pass@smtp.host:587")}${field("MAIL_FROM", "mailFrom", "App <no-reply@you.com>")}` : null)}
+    ${() => (eff().includes("media") ? mediaSettings() : null)}
   </div>`,
   html`<div class="card-x p-4 mb-3">
     <div class="d-flex justify-content-between align-items-center mb-2">

package/templates/guestbook/Dockerfile

@@ -0,0 +1,20 @@
+# Volt app — production container. Runs on Render, Fly.io, Railway, DO App
+# Platform, and any container host. They handle the server, DNS, and TLS; you
+# just set config as env vars.
+#
+# Configure via the platform's env vars (NOT a committed .env):
+#   VOLT_ADDONS=db,auth,...      DB_DRIVER=...   MONGODB_URI / DATABASE_URL
+#   MEDIA_DRIVER=s3   S3_ENDPOINT/S3_REGION/S3_BUCKET/S3_KEY/S3_SECRET   etc.
+#
+# Tip: run the local wizard first (`npm run dev`) so the add-on packages are
+# saved into package.json; commit package.json, then deploy and set the same
+# config as env vars here. NODE_ENV=production makes the app boot straight up
+# (no setup wizard).
+FROM node:22-alpine
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package*.json ./
+RUN npm install --omit=dev
+COPY . .
+EXPOSE 8080
+CMD ["node", "server.js"]

package/templates/guestbook/Procfile

@@ -0,0 +1 @@
+web: node server.js

package/templates/guestbook/dockerignore

@@ -0,0 +1,6 @@
+node_modules
+.git
+.env
+*.log
+npm-debug.log*
+.DS_Store

package/templates/guestbook/fly.toml

@@ -0,0 +1,15 @@
+# Fly.io — run `fly launch` (it uses the Dockerfile), then set config:
+#   fly secrets set VOLT_ADDONS=db,auth DB_DRIVER=mongodb MONGODB_URI=...
+app = "volt-app"
+
+[build]
+
+[http_service]
+  internal_port = 8080
+  force_https = true
+  auto_stop_machines = true
+  auto_start_machines = true
+
+[env]
+  PORT = "8080"
+  NODE_ENV = "production"

package/templates/guestbook/render.yaml

@@ -0,0 +1,15 @@
+# Render blueprint — https://render.com/docs/blueprint-spec
+# Push this repo to GitHub, then in Render: New → Blueprint → pick the repo.
+# Render builds the Dockerfile, gives you HTTPS + a domain, and runs it.
+services:
+  - type: web
+    name: volt-app
+    runtime: docker
+    plan: starter
+    envVars:
+      - key: VOLT_ADDONS
+        sync: false # set your add-ons (e.g. "db,auth") in the dashboard
+      # Add the rest in the dashboard as needed:
+      #   DB_DRIVER, MONGODB_URI / DATABASE_URL,
+      #   MEDIA_DRIVER, S3_ENDPOINT/S3_REGION/S3_BUCKET/S3_KEY/S3_SECRET,
+      #   SMTP_URL, MAIL_FROM

package/templates/starter/Dockerfile

@@ -0,0 +1,20 @@
+# Volt app — production container. Runs on Render, Fly.io, Railway, DO App
+# Platform, and any container host. They handle the server, DNS, and TLS; you
+# just set config as env vars.
+#
+# Configure via the platform's env vars (NOT a committed .env):
+#   VOLT_ADDONS=db,auth,...      DB_DRIVER=...   MONGODB_URI / DATABASE_URL
+#   MEDIA_DRIVER=s3   S3_ENDPOINT/S3_REGION/S3_BUCKET/S3_KEY/S3_SECRET   etc.
+#
+# Tip: run the local wizard first (`npm run dev`) so the add-on packages are
+# saved into package.json; commit package.json, then deploy and set the same
+# config as env vars here. NODE_ENV=production makes the app boot straight up
+# (no setup wizard).
+FROM node:22-alpine
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package*.json ./
+RUN npm install --omit=dev
+COPY . .
+EXPOSE 8080
+CMD ["node", "server.js"]

package/templates/starter/Procfile

@@ -0,0 +1 @@
+web: node server.js

package/templates/starter/dockerignore

@@ -0,0 +1,6 @@
+node_modules
+.git
+.env
+*.log
+npm-debug.log*
+.DS_Store

package/templates/starter/fly.toml

@@ -0,0 +1,15 @@
+# Fly.io — run `fly launch` (it uses the Dockerfile), then set config:
+#   fly secrets set VOLT_ADDONS=db,auth DB_DRIVER=mongodb MONGODB_URI=...
+app = "volt-app"
+
+[build]
+
+[http_service]
+  internal_port = 8080
+  force_https = true
+  auto_stop_machines = true
+  auto_start_machines = true
+
+[env]
+  PORT = "8080"
+  NODE_ENV = "production"

package/templates/starter/render.yaml

@@ -0,0 +1,15 @@
+# Render blueprint — https://render.com/docs/blueprint-spec
+# Push this repo to GitHub, then in Render: New → Blueprint → pick the repo.
+# Render builds the Dockerfile, gives you HTTPS + a domain, and runs it.
+services:
+  - type: web
+    name: volt-app
+    runtime: docker
+    plan: starter
+    envVars:
+      - key: VOLT_ADDONS
+        sync: false # set your add-ons (e.g. "db,auth") in the dashboard
+      # Add the rest in the dashboard as needed:
+      #   DB_DRIVER, MONGODB_URI / DATABASE_URL,
+      #   MEDIA_DRIVER, S3_ENDPOINT/S3_REGION/S3_BUCKET/S3_KEY/S3_SECRET,
+      #   SMTP_URL, MAIL_FROM

package/templates/starter/server.js

@@ -22,8 +22,8 @@ const ENV_PATH = path.join(__dirname, ".env");
 const PKG_PATH = path.join(__dirname, "package.json");
 const ADDONS_DIR = path.join(__dirname, ".volt", "addons"); // bundled add-on sources
 const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
-const PKG_VERSIONS = { mongodb: "^6.21.0", mysql2: "^3.22.5", pg: "^8.22.0", nodemailer: "^6.10.1", marked: "^18.0.5" };
-const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", pages: "pages.js" };
+const PKG_VERSIONS = { mongodb: "^6.21.0", mysql2: "^3.22.5", pg: "^8.22.0", nodemailer: "^6.10.1", marked: "^18.0.5", busboy: "^1.6.0", "@aws-sdk/client-s3": "^3.1075.0" };
+const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", pages: "pages.js", media: "media.js" };
 
 // --- tiny .env loader (no dependency); never overrides an existing env var ---
 function readEnvFile() {
@@ -137,6 +137,12 @@ async function startApp() {
 
   app.get("/", (_req, res) => res.sendFile(path.join(__dirname, "views", "index.html")));
 
+  // media uploads (POST /api/media, auth-gated; local files served at /media)
+  if (enabled.has("media") && store) {
+    const requireAuth = (await addonMod("auth")).requireAuth(store);
+    app.use(await (await addonMod("media")).mediaRouter({ requireAuth, dir: path.join(__dirname, "media") }));
+  }
+
   // markdown pages (/<slug> ← pages/<slug>.md) — mounted last, so app routes win
   if (enabled.has("pages")) app.use(await (await addonMod("pages")).pagesRouter({ dir: path.join(__dirname, "pages") }));
 
@@ -186,6 +192,8 @@ function neededPackages(env) {
   if (driver === "postgres") want.push("pg");
   if (/^\s*SMTP_URL\s*=\s*\S/m.test(env)) want.push("nodemailer");
   if (/^\s*VOLT_ADDONS\s*=.*\bpages\b/m.test(env)) want.push("marked");
+  if (/^\s*VOLT_ADDONS\s*=.*\bmedia\b/m.test(env)) want.push("busboy");
+  if (/^\s*MEDIA_DRIVER\s*=\s*s3\b/m.test(env)) want.push("@aws-sdk/client-s3");
   return want.filter((p) => !deps[p]);
 }
 
@@ -415,9 +423,13 @@ async function startStudio() {
 
 // --- gate: studio / setup (first run, --edit) / the app ---
 const editMode = process.argv.includes("--edit") || process.argv.includes("-e");
+// In production / on a PaaS there's no interactive wizard: config comes from the
+// platform's env vars (a Dockerfile sets NODE_ENV=production). Only fall back to
+// the first-run wizard when nothing is configured and we're not in production.
+const configured = fs.existsSync(ENV_PATH) || process.env.VOLT_ADDONS != null || process.env.NODE_ENV === "production";
 if (process.argv.includes("--studio")) {
   startStudio();
-} else if (editMode || !fs.existsSync(ENV_PATH)) {
+} else if (editMode || !configured) {
   startSetup();
 } else {
   loadEnv();

package/templates/starter/setup/setup.js

@@ -17,6 +17,13 @@ const state = signal({
   dbUrl: current.DATABASE_URL || "",
   smtpUrl: current.SMTP_URL || "",
   mailFrom: current.MAIL_FROM || "",
+  mediaDriver: current.MEDIA_DRIVER || "local",
+  s3Endpoint: current.S3_ENDPOINT || "",
+  s3Region: current.S3_REGION || "",
+  s3Bucket: current.S3_BUCKET || "",
+  s3Key: current.S3_KEY || "",
+  s3Secret: current.S3_SECRET || "",
+  s3PublicBase: current.S3_PUBLIC_BASE || "",
   port: current.PORT || String(defaultPort),
 });
 const set = (patch) => state({ ...state(), ...patch });
@@ -53,6 +60,17 @@ function genEnv(s) {
     else out.push("# SMTP_URL=        # unset → emails print to the console");
     if (s.mailFrom) out.push(`MAIL_FROM=${clean(s.mailFrom)}`);
   }
+  if (eff.includes("media")) {
+    out.push(`MEDIA_DRIVER=${clean(s.mediaDriver)}`);
+    if (s.mediaDriver === "s3") {
+      out.push(`S3_ENDPOINT=${clean(s.s3Endpoint)}`);
+      out.push(`S3_REGION=${clean(s.s3Region)}`);
+      out.push(`S3_BUCKET=${clean(s.s3Bucket)}`);
+      out.push(`S3_KEY=${clean(s.s3Key)}`);
+      out.push(`S3_SECRET=${clean(s.s3Secret)}`);
+      if (s.s3PublicBase) out.push(`S3_PUBLIC_BASE=${clean(s.s3PublicBase)}`);
+    }
+  }
   return out.join("\n") + "\n";
 }
 const env = computed(() => genEnv(state()));
@@ -134,6 +152,19 @@ const dbSettings = () =>
           : null}
     ${() => (state().dbDriver !== "memory" ? html`<button class="btn btn-sm btn-outline-secondary mb-2" onclick=${testDb}>Test connection</button>` : null)}`;
 
+const mediaSettings = () =>
+  html`<div class="mb-2">
+      <label class="form-label small mb-1">Media storage (MEDIA_DRIVER)</label>
+      <select class="form-select" value=${() => state().mediaDriver} onchange=${(e) => set({ mediaDriver: e.target.value })}>
+        <option value="local">local (disk)</option>
+        <option value="s3">s3 — AWS S3 / DigitalOcean Spaces</option>
+      </select>
+    </div>
+    ${() =>
+      state().mediaDriver === "s3"
+        ? html`${field("S3_ENDPOINT", "s3Endpoint", "https://nyc3.digitaloceanspaces.com")}${field("S3_REGION", "s3Region", "us-east-1")}${field("S3_BUCKET", "s3Bucket", "my-space")}${field("S3_KEY", "s3Key", "access key")}${field("S3_SECRET", "s3Secret", "secret key")}${field("S3_PUBLIC_BASE (optional CDN base)", "s3PublicBase", "https://cdn.example.com")}`
+        : null}`;
+
 mount(
   "#app",
   available.length
@@ -148,6 +179,7 @@ mount(
     ${field("PORT", "port", String(defaultPort))}
     ${() => (eff().includes("db") ? dbSettings() : null)}
     ${() => (eff().includes("mailer") ? html`${field("SMTP_URL (optional)", "smtpUrl", "smtp://user:pass@smtp.host:587")}${field("MAIL_FROM", "mailFrom", "App <no-reply@you.com>")}` : null)}
+    ${() => (eff().includes("media") ? mediaSettings() : null)}
   </div>`,
   html`<div class="card-x p-4 mb-3">
     <div class="d-flex justify-content-between align-items-center mb-2">