From 6868fc0fb12f29a898e784e01e6ea9745fa9d8b6 Mon Sep 17 00:00:00 2001
From: Xing Liu <xing@57blocks.com>
Date: Tue, 9 Jun 2026 11:12:27 +0800
Subject: [PATCH] feat(infra): Auto-provision shared S3 bucket per generated
 app

Add S3 to the kickoff-infra auto-provisioning flow alongside Postgres
and Redis. Unlike PG/Redis (one Dokploy container each), S3 uses a
single shared bucket configured once on the server; every generated app
gets an isolated folder (key prefix = app slug).

- types: InfraServiceKind gains "s3"; RequiredServices gains needsS3;
  InfraServiceInfo gains optional `env` map for multi-key services
- detect: regex + LLM service-detector now classify S3 (file/image/media
  upload, object storage, presigned URLs)
- s3.ts: reads BLUEPRINT_S3_* shared-bucket config, allocates per-app
  prefix, emits the AWS_S3_* env bundle (no Dokploy call)
- index: S3 provisioning runs independently of Dokploy; adds s3EnvFrom()
- coding/route + deploy/pipeline: inject S3 env into backend/.env and the
  deployed compose env
- generated-code-env: add generic upsertEnvVars for multi-key sets
- InfraSection UI: S3 chip (skips ping / port display)
- .env.example: document BLUEPRINT_S3_* (AWS / R2 / MinIO compatible)

Secrets only land in gitignored .blueprint/kickoff-infra.json and the
generated .env; UI/metadata expose only the s3://bucket/prefix string.

Tests: detect + s3 unit suites (34 passing).
---
 .env.example                                  |  17 ++
 src/app/api/agents/coding/route.ts            |   7 +-
 src/components/kickoff/InfraSection.tsx       |  27 ++-
 src/lib/agents/infra/service-detector.ts      |  19 +-
 src/lib/deploy/__tests__/pipeline.test.ts     |   1 +
 src/lib/deploy/pipeline.ts                    |   9 +
 src/lib/pipeline/generated-code-env.ts        |  26 +++
 .../kickoff-infra/__tests__/detect.test.ts    |  54 ++++-
 .../kickoff-infra/__tests__/s3.test.ts        | 147 +++++++++++++
 src/lib/pipeline/kickoff-infra/detect.ts      |  12 ++
 src/lib/pipeline/kickoff-infra/index.ts       | 193 +++++++++++-------
 src/lib/pipeline/kickoff-infra/s3.ts          | 127 ++++++++++++
 src/lib/pipeline/kickoff-infra/types.ts       |  20 +-
 13 files changed, 550 insertions(+), 109 deletions(-)
 create mode 100644 src/lib/pipeline/kickoff-infra/__tests__/s3.test.ts
 create mode 100644 src/lib/pipeline/kickoff-infra/s3.ts

diff --git a/.env.example b/.env.example
index 731ce225..72ca412a 100644
--- a/.env.example
+++ b/.env.example
@@ -106,6 +106,23 @@ CODE_OUTPUT_DIR=generated-code
 # Use a URL-encoded password if it contains @ (e.g. p%40ssword for p@ssword).
 # BLUEPRINT_GENERATED_DATABASE_URL=postgresql://user:pass@localhost:5432/dbname
 
+# --- Infra auto-provisioning (kickoff) ---
+# Postgres/Redis: one Dokploy container per generated app. Set both to enable.
+# DOKPLOY_URL=https://dokploy.example.com
+# DOKPLOY_TOKEN=
+#
+# S3 object storage: ONE shared bucket for all generated apps; each app gets an
+# isolated folder (key prefix = app slug). Set BLUEPRINT_S3_BUCKET to enable;
+# the kickoff "service detector" then auto-wires AWS_S3_* into the app's .env
+# whenever the PRD/TRD implies file/image/media upload. Works with AWS S3 or any
+# S3-compatible store (MinIO, Cloudflare R2) via the optional endpoint vars.
+# BLUEPRINT_S3_BUCKET=my-shared-test-bucket
+# BLUEPRINT_S3_ACCESS_KEY_ID=
+# BLUEPRINT_S3_SECRET_ACCESS_KEY=
+# BLUEPRINT_S3_REGION=us-east-1
+# BLUEPRINT_S3_ENDPOINT=                 # e.g. https://<account>.r2.cloudflarestorage.com (S3-compatible only)
+# BLUEPRINT_S3_FORCE_PATH_STYLE=         # set to 1 for MinIO / path-style addressing
+
 # --- Project kick-off: Git / Jira (optional; webhooks OR direct API) ---
 # If a webhook URL is set, it is used instead of the direct API for that integration.
 #
diff --git a/src/app/api/agents/coding/route.ts b/src/app/api/agents/coding/route.ts
index 339c8a50..48a4117e 100644
--- a/src/app/api/agents/coding/route.ts
+++ b/src/app/api/agents/coding/route.ts
@@ -35,6 +35,7 @@ import {
   resolveBackendPort,
   upsertBackendPrivyAppIdMirror,
   resolvePrivyAppIdMirrorFromFilledResources,
+  upsertEnvVars,
 } from "@/lib/pipeline/generated-code-env";
 import {
   normalizeProjectTier,
@@ -48,6 +49,7 @@ import {
   readKickoffInfraMetadata,
   databaseUrlFrom,
   redisUrlFrom,
+  s3EnvFrom,
 } from "@/lib/pipeline/kickoff-infra";
 import {
   readResourceRequirements,
@@ -1401,7 +1403,10 @@ export async function POST(request: NextRequest) {
     const withRedisUrl = redisUrlForEnv
       ? upsertRedisUrlEnv(withDbUrl, redisUrlForEnv)
       : withDbUrl;
-    const withJwt = upsertJwtEnvVars(withRedisUrl);
+    // S3 credential bundle (shared bucket + per-app folder) from kickoff infra.
+    const s3Env = s3EnvFrom(kickoffInfra);
+    const withS3 = s3Env ? upsertEnvVars(withRedisUrl, s3Env) : withRedisUrl;
+    const withJwt = upsertJwtEnvVars(withS3);
     const withPort = upsertBackendPortEnv(withJwt);
     const withResources = upsertResourceEnvVars(withPort, backendResources);
     const privyMirror =
diff --git a/src/components/kickoff/InfraSection.tsx b/src/components/kickoff/InfraSection.tsx
index 9b7d67ec..d5bf06bb 100644
--- a/src/components/kickoff/InfraSection.tsx
+++ b/src/components/kickoff/InfraSection.tsx
@@ -3,7 +3,7 @@
 import { useCallback, useEffect, useState } from "react";
 
 export interface InfraServiceMeta {
-  kind: "postgres" | "redis";
+  kind: "postgres" | "redis" | "s3";
   appName: string;
   externalPort: number;
   publicUrl: string;
@@ -27,11 +27,13 @@ interface Props {
 const KIND_ICON: Record<InfraServiceMeta["kind"], string> = {
   postgres: "🐘",
   redis: "🟥",
+  s3: "🪣",
 };
 
 const KIND_LABEL: Record<InfraServiceMeta["kind"], string> = {
   postgres: "Postgres",
   redis: "Redis",
+  s3: "S3",
 };
 
 type PingStatus =
@@ -72,9 +74,12 @@ export default function InfraSection({ infra, dokployBaseUrl }: Props) {
     setPings((p) => ({ ...p, [key]: result }));
   }, []);
 
-  // Initial probe — fires once per service when the panel mounts.
+  // Initial probe — fires once per service when the panel mounts. S3 is an
+  // external bucket reached over HTTPS with credentials, not a pingable TCP
+  // endpoint, so we skip the reachability probe for it.
   useEffect(() => {
     for (const svc of services) {
+      if (svc.kind === "s3") continue;
       const key = `${svc.kind}-${svc.appName}`;
       runPing(key, svc.publicUrl);
     }
@@ -156,13 +161,17 @@ export default function InfraSection({ infra, dokployBaseUrl }: Props) {
                   <span className="text-[13px] font-semibold text-zinc-900">
                     {KIND_LABEL[svc.kind]}
                   </span>
-                  <span className="rounded bg-zinc-100 px-1.5 py-0.5 font-mono text-[11px] text-zinc-700">
-                    :{svc.externalPort}
-                  </span>
-                  <PingBadge
-                    status={ping}
-                    onRetry={() => runPing(key, svc.publicUrl)}
-                  />
+                  {svc.kind !== "s3" && (
+                    <span className="rounded bg-zinc-100 px-1.5 py-0.5 font-mono text-[11px] text-zinc-700">
+                      :{svc.externalPort}
+                    </span>
+                  )}
+                  {svc.kind !== "s3" && (
+                    <PingBadge
+                      status={ping}
+                      onRetry={() => runPing(key, svc.publicUrl)}
+                    />
+                  )}
                 </div>
                 <button
                   type="button"
diff --git a/src/lib/agents/infra/service-detector.ts b/src/lib/agents/infra/service-detector.ts
index 96c198c7..c456502f 100644
--- a/src/lib/agents/infra/service-detector.ts
+++ b/src/lib/agents/infra/service-detector.ts
@@ -20,8 +20,9 @@ Output STRICT JSON — no prose, no markdown fences:
 {
   "needsPostgres": true|false,
   "needsRedis":    true|false,
+  "needsS3":       true|false,
   "evidence": [
-    { "service": "postgres"|"redis", "quote": "<≤120 chars from the docs>" }
+    { "service": "postgres"|"redis"|"s3", "quote": "<≤120 chars from the docs>" }
   ]
 }
 
@@ -30,12 +31,16 @@ Rules:
   if it's only mentioned in passing or compared in a tech selection discussion.
 - Redis is needed only when the project requires cache, session store, queue,
   rate-limiting, or pub/sub. Mentioning "Redis" in passing is not enough.
+- S3 (object storage) is needed only when the project stores/serves user files,
+  images, avatars, documents, media, or attachments — i.e. binary blobs that
+  don't belong in Postgres. File upload / download / presigned-URL flows count.
+  A purely text/CRUD app with no file handling does NOT need S3.
 - Every "true" decision MUST have at least one matching evidence entry.
 - "false" decisions should have no evidence entries for that service.
 - Quotes must come from the input docs verbatim (or trimmed to ≤120 chars).`;
 
 const EvidenceSchema = z.object({
-  service: z.enum(["postgres", "redis"]),
+  service: z.enum(["postgres", "redis", "s3"]),
   quote: z.string().min(1).max(200),
 });
 
@@ -43,11 +48,17 @@ const ServiceDecisionSchema = z
   .object({
     needsPostgres: z.boolean(),
     needsRedis: z.boolean(),
+    needsS3: z.boolean().default(false),
     evidence: z.array(EvidenceSchema).default([]),
   })
   .superRefine((d, ctx) => {
-    for (const svc of ["postgres", "redis"] as const) {
-      const flag = svc === "postgres" ? d.needsPostgres : d.needsRedis;
+    const flagByService = {
+      postgres: d.needsPostgres,
+      redis: d.needsRedis,
+      s3: d.needsS3,
+    } as const;
+    for (const svc of ["postgres", "redis", "s3"] as const) {
+      const flag = flagByService[svc];
       const has = d.evidence.some((e) => e.service === svc);
       if (flag && !has) {
         ctx.addIssue({
diff --git a/src/lib/deploy/__tests__/pipeline.test.ts b/src/lib/deploy/__tests__/pipeline.test.ts
index 051e5a81..1ad8bce5 100644
--- a/src/lib/deploy/__tests__/pipeline.test.ts
+++ b/src/lib/deploy/__tests__/pipeline.test.ts
@@ -8,6 +8,7 @@ vi.mock("@/lib/pipeline/kickoff-infra", () => ({
   readKickoffInfraMetadata: vi.fn(),
   internalDatabaseUrlFrom: vi.fn(),
   internalRedisUrlFrom: vi.fn(),
+  s3EnvFrom: vi.fn(),
   persistComposeOnInfra: vi.fn(),
 }));
 vi.mock("../dokploy", () => ({
diff --git a/src/lib/deploy/pipeline.ts b/src/lib/deploy/pipeline.ts
index 83a82490..a610366a 100644
--- a/src/lib/deploy/pipeline.ts
+++ b/src/lib/deploy/pipeline.ts
@@ -5,6 +5,7 @@ import {
   readKickoffInfraMetadata,
   internalDatabaseUrlFrom,
   internalRedisUrlFrom,
+  s3EnvFrom,
   persistComposeOnInfra,
 } from "@/lib/pipeline/kickoff-infra";
 import { createDokployProject, createDokployCompose, createDokployDomain, updateDokployCompose, deployDokployCompose, pollDeployStatus, getDokployCompose } from "./dokploy";
@@ -75,6 +76,7 @@ async function buildDokployEnv(
   generatedCodePath: string,
   databaseUrl: string,
   redisInternalUrl: string | null,
+  s3Env: Record<string, string> | null,
 ): Promise<{ env: string; count: number; sourcedFromBackendEnv: boolean }> {
   const backendEnvPath = path.resolve(generatedCodePath, "backend", ".env");
   const fileEnv = await readEnvFile(backendEnvPath);
@@ -83,6 +85,11 @@ async function buildDokployEnv(
   // local `pnpm dev`); deployed containers must use internal DNS.
   fileEnv.DATABASE_URL = databaseUrl;
   if (redisInternalUrl) fileEnv.REDIS_URL = redisInternalUrl;
+  // S3 is a shared external bucket — same access from local dev and the
+  // deployed container, so the values are identical (no internal/public split).
+  if (s3Env) {
+    for (const [k, v] of Object.entries(s3Env)) fileEnv[k] = v;
+  }
   const lines: string[] = [];
   for (const [k, v] of Object.entries(fileEnv)) {
     // Keep `KEY=VALUE` plain (no quoting) — Dokploy parses the same way
@@ -165,6 +172,7 @@ export async function runDeployPipeline(params: PipelineParams): Promise<void> {
   const infraMeta = await readKickoffInfraMetadata(projectRoot);
   const databaseUrl: string | null = internalDatabaseUrlFrom(infraMeta);
   const redisInternalUrl = internalRedisUrlFrom(infraMeta);
+  const s3Env = s3EnvFrom(infraMeta);
   const reusedDokployProjectId: string | null = infraMeta?.dokployProjectId ?? null;
   const reusedDokployEnvId: string | null = infraMeta?.dokployEnvironmentId ?? null;
   if (!databaseUrl) {
@@ -249,6 +257,7 @@ export async function runDeployPipeline(params: PipelineParams): Promise<void> {
       generatedCodePath,
       databaseUrl,
       redisInternalUrl,
+      s3Env,
     );
     console.log(
       `[deploy] Compose env: ${envBlock.count} key(s) (${envBlock.sourcedFromBackendEnv ? "sourced from backend/.env" : "backend/.env not found — only DATABASE_URL/REDIS_URL"})`,
diff --git a/src/lib/pipeline/generated-code-env.ts b/src/lib/pipeline/generated-code-env.ts
index c71a9115..1b89a6ee 100644
--- a/src/lib/pipeline/generated-code-env.ts
+++ b/src/lib/pipeline/generated-code-env.ts
@@ -143,6 +143,32 @@ export function upsertRedisUrlEnv(
   return `${normalized}${serialized}\n`;
 }
 
+/**
+ * Upsert an arbitrary set of `KEY=value` pairs into an existing .env payload,
+ * preserving every other key. Replaces existing keys in place, appends new
+ * ones. Values are JSON-quoted so special characters survive. Used for the S3
+ * credential bundle (AWS_S3_BUCKET, AWS_S3_PREFIX, AWS_ACCESS_KEY_ID, …) which
+ * — unlike DATABASE_URL/REDIS_URL — is a multi-key set, not a single URL.
+ */
+export function upsertEnvVars(
+  envContent: string,
+  vars: Record<string, string>,
+): string {
+  let result =
+    envContent.endsWith("\n") || envContent === "" ? envContent : `${envContent}\n`;
+  for (const [key, value] of Object.entries(vars)) {
+    if (!key) continue;
+    const serialized = `${key}=${JSON.stringify(value)}`;
+    const re = new RegExp(`^\\s*${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*=.*$`, "m");
+    if (re.test(result)) {
+      result = result.replace(re, serialized);
+    } else {
+      result = `${result}${serialized}\n`;
+    }
+  }
+  return result;
+}
+
 /** Upsert PORT (and align frontend VITE_API_BASE_URL) into an existing .env. */
 export function upsertBackendPortEnv(
   envContent: string,
diff --git a/src/lib/pipeline/kickoff-infra/__tests__/detect.test.ts b/src/lib/pipeline/kickoff-infra/__tests__/detect.test.ts
index 0516c67d..8360c84c 100644
--- a/src/lib/pipeline/kickoff-infra/__tests__/detect.test.ts
+++ b/src/lib/pipeline/kickoff-infra/__tests__/detect.test.ts
@@ -8,7 +8,7 @@ describe("detectRequiredServicesByRegex", () => {
   it("detects postgres by name", () => {
     expect(
       detectRequiredServicesByRegex("We use PostgreSQL for storage."),
-    ).toEqual({ needsPostgres: true, needsRedis: false });
+    ).toEqual({ needsPostgres: true, needsRedis: false, needsS3: false });
   });
   it("detects postgres via ORM mention", () => {
     expect(
@@ -23,6 +23,7 @@ describe("detectRequiredServicesByRegex", () => {
     expect(detectRequiredServicesByRegex("Sessions stored in Redis.")).toEqual({
       needsPostgres: false,
       needsRedis: true,
+      needsS3: false,
     });
   });
   it("detects redis via BullMQ / cache hints", () => {
@@ -36,19 +37,44 @@ describe("detectRequiredServicesByRegex", () => {
       true,
     );
   });
-  it("detects both", () => {
+  it("detects s3 by name", () => {
     expect(
-      detectRequiredServicesByRegex(
-        "PostgreSQL for the main store; Redis for session cache.",
-      ),
-    ).toEqual({ needsPostgres: true, needsRedis: true });
+      detectRequiredServicesByRegex("Store uploads in an S3 bucket."),
+    ).toEqual({ needsPostgres: false, needsRedis: false, needsS3: true });
+  });
+  it("detects s3 via upload / object-storage hints", () => {
+    expect(
+      detectRequiredServicesByRegex("Users can upload avatar images.")
+        .needsS3,
+    ).toBe(true);
+    expect(
+      detectRequiredServicesByRegex("Files persisted to object storage.")
+        .needsS3,
+    ).toBe(true);
+    expect(
+      detectRequiredServicesByRegex("Generate a presigned URL for downloads.")
+        .needsS3,
+    ).toBe(true);
+    expect(
+      detectRequiredServicesByRegex("Document upload with MinIO.").needsS3,
+    ).toBe(true);
   });
-  it("neither detected for a static site", () => {
+  it("does NOT flag s3 for a text-only CRUD app", () => {
+    expect(
+      detectRequiredServicesByRegex("A todo list app with PostgreSQL.").needsS3,
+    ).toBe(false);
+  });
+  it("detects all three", () => {
     expect(
       detectRequiredServicesByRegex(
-        "A simple static site rendered with Vite.",
+        "PostgreSQL for the main store; Redis for session cache; S3 for media uploads.",
       ),
-    ).toEqual({ needsPostgres: false, needsRedis: false });
+    ).toEqual({ needsPostgres: true, needsRedis: true, needsS3: true });
+  });
+  it("none detected for a static site", () => {
+    expect(
+      detectRequiredServicesByRegex("A simple static site rendered with Vite."),
+    ).toEqual({ needsPostgres: false, needsRedis: false, needsS3: false });
   });
 });
 
@@ -63,8 +89,14 @@ describe("detectRequiredServices (orchestration)", () => {
   });
 
   it("uses regex path when INFRA_DETECT_REGEX_ONLY is set", async () => {
-    const r = await detectRequiredServices("PostgreSQL with Redis caching.");
+    const r = await detectRequiredServices(
+      "PostgreSQL with Redis caching and S3 image uploads.",
+    );
     expect(r.source).toBe("regex");
-    expect(r.services).toEqual({ needsPostgres: true, needsRedis: true });
+    expect(r.services).toEqual({
+      needsPostgres: true,
+      needsRedis: true,
+      needsS3: true,
+    });
   });
 });
diff --git a/src/lib/pipeline/kickoff-infra/__tests__/s3.test.ts b/src/lib/pipeline/kickoff-infra/__tests__/s3.test.ts
new file mode 100644
index 00000000..b9ab8ddd
--- /dev/null
+++ b/src/lib/pipeline/kickoff-infra/__tests__/s3.test.ts
@@ -0,0 +1,147 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  readSharedS3Config,
+  deriveS3Prefix,
+  buildS3EnvVars,
+  provisionAppS3,
+} from "../s3";
+
+const S3_ENV_KEYS = [
+  "BLUEPRINT_S3_BUCKET",
+  "BLUEPRINT_S3_ACCESS_KEY_ID",
+  "BLUEPRINT_S3_SECRET_ACCESS_KEY",
+  "BLUEPRINT_S3_REGION",
+  "BLUEPRINT_S3_ENDPOINT",
+  "BLUEPRINT_S3_FORCE_PATH_STYLE",
+] as const;
+
+describe("deriveS3Prefix", () => {
+  it("slugifies and appends a trailing slash", () => {
+    expect(deriveS3Prefix("My Cool App")).toBe("my-cool-app/");
+  });
+  it("collapses non-alphanumerics and trims dashes", () => {
+    expect(deriveS3Prefix("--Foo__Bar!!--")).toBe("foo-bar/");
+  });
+  it("falls back to 'app' for an empty slug", () => {
+    expect(deriveS3Prefix("!!!")).toBe("app/");
+  });
+});
+
+describe("buildS3EnvVars", () => {
+  it("emits the core AWS keys without optional ones by default", () => {
+    const env = buildS3EnvVars(
+      {
+        bucket: "shared",
+        region: "eu-west-1",
+        accessKeyId: "AKIA",
+        secretAccessKey: "secret",
+        forcePathStyle: false,
+      },
+      "app-x/",
+    );
+    expect(env).toEqual({
+      AWS_REGION: "eu-west-1",
+      AWS_ACCESS_KEY_ID: "AKIA",
+      AWS_SECRET_ACCESS_KEY: "secret",
+      AWS_S3_BUCKET: "shared",
+      AWS_S3_PREFIX: "app-x/",
+    });
+  });
+  it("includes endpoint + path-style when set", () => {
+    const env = buildS3EnvVars(
+      {
+        bucket: "shared",
+        region: "us-east-1",
+        accessKeyId: "k",
+        secretAccessKey: "s",
+        endpoint: "https://minio.local",
+        forcePathStyle: true,
+      },
+      "p/",
+    );
+    expect(env.AWS_S3_ENDPOINT).toBe("https://minio.local");
+    expect(env.AWS_S3_FORCE_PATH_STYLE).toBe("true");
+  });
+});
+
+describe("readSharedS3Config", () => {
+  const saved: Record<string, string | undefined> = {};
+  beforeEach(() => {
+    for (const k of S3_ENV_KEYS) {
+      saved[k] = process.env[k];
+      delete process.env[k];
+    }
+  });
+  afterEach(() => {
+    for (const k of S3_ENV_KEYS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  });
+
+  it("returns null when no bucket is configured", () => {
+    expect(readSharedS3Config()).toBeNull();
+  });
+
+  it("throws when bucket is set but credentials are missing", () => {
+    process.env.BLUEPRINT_S3_BUCKET = "shared";
+    expect(() => readSharedS3Config()).toThrow(/credentials|ACCESS_KEY/i);
+  });
+
+  it("reads a complete config with defaults", () => {
+    process.env.BLUEPRINT_S3_BUCKET = "shared";
+    process.env.BLUEPRINT_S3_ACCESS_KEY_ID = "AKIA";
+    process.env.BLUEPRINT_S3_SECRET_ACCESS_KEY = "secret";
+    const cfg = readSharedS3Config();
+    expect(cfg).toEqual({
+      bucket: "shared",
+      region: "us-east-1",
+      accessKeyId: "AKIA",
+      secretAccessKey: "secret",
+      endpoint: undefined,
+      forcePathStyle: false,
+    });
+  });
+
+  it("honours forcePathStyle truthy strings", () => {
+    process.env.BLUEPRINT_S3_BUCKET = "shared";
+    process.env.BLUEPRINT_S3_ACCESS_KEY_ID = "AKIA";
+    process.env.BLUEPRINT_S3_SECRET_ACCESS_KEY = "secret";
+    process.env.BLUEPRINT_S3_FORCE_PATH_STYLE = "1";
+    expect(readSharedS3Config()?.forcePathStyle).toBe(true);
+  });
+});
+
+describe("provisionAppS3", () => {
+  const saved: Record<string, string | undefined> = {};
+  beforeEach(() => {
+    for (const k of S3_ENV_KEYS) {
+      saved[k] = process.env[k];
+      delete process.env[k];
+    }
+  });
+  afterEach(() => {
+    for (const k of S3_ENV_KEYS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  });
+
+  it("returns an InfraServiceInfo scoped to the app folder", () => {
+    process.env.BLUEPRINT_S3_BUCKET = "shared-test";
+    process.env.BLUEPRINT_S3_ACCESS_KEY_ID = "AKIA";
+    process.env.BLUEPRINT_S3_SECRET_ACCESS_KEY = "secret";
+    const info = provisionAppS3({ appName: "Photo Wall" });
+    expect(info.kind).toBe("s3");
+    expect(info.appName).toBe("shared-test");
+    expect(info.id).toBe("photo-wall/");
+    expect(info.publicUrl).toBe("s3://shared-test/photo-wall/");
+    expect(info.externalPort).toBe(0);
+    expect(info.env?.AWS_S3_BUCKET).toBe("shared-test");
+    expect(info.env?.AWS_S3_PREFIX).toBe("photo-wall/");
+  });
+
+  it("throws when S3 is not configured", () => {
+    expect(() => provisionAppS3({ appName: "x" })).toThrow(/not configured/i);
+  });
+});
diff --git a/src/lib/pipeline/kickoff-infra/detect.ts b/src/lib/pipeline/kickoff-infra/detect.ts
index 5b6031d3..c16864af 100644
--- a/src/lib/pipeline/kickoff-infra/detect.ts
+++ b/src/lib/pipeline/kickoff-infra/detect.ts
@@ -27,6 +27,16 @@ const REDIS_PATTERNS = [
   /\b(?:cache|session\s+store|rate\s*limit(?:er|ing)?|queue)\b/i,
 ];
 
+const S3_PATTERNS = [
+  /\bs3\b/i,
+  /\bminio\b/i,
+  /\bobject\s+storage\b/i,
+  /\bblob\s+storage\b/i,
+  /\bpresigned\s+url\b/i,
+  /\b(?:file|image|avatar|document|media|attachment)\s+(?:upload|storage)\b/i,
+  /\b(?:upload|store)\s+(?:files?|images?|avatars?|documents?|media|attachments?)\b/i,
+];
+
 function anyMatch(text: string, patterns: RegExp[]): boolean {
   return patterns.some((p) => p.test(text));
 }
@@ -37,6 +47,7 @@ export function detectRequiredServicesByRegex(
   return {
     needsPostgres: anyMatch(designDocs, POSTGRES_PATTERNS),
     needsRedis: anyMatch(designDocs, REDIS_PATTERNS),
+    needsS3: anyMatch(designDocs, S3_PATTERNS),
   };
 }
 
@@ -72,6 +83,7 @@ export async function detectRequiredServices(
         services: {
           needsPostgres: r.decision.needsPostgres,
           needsRedis: r.decision.needsRedis,
+          needsS3: r.decision.needsS3,
         },
         source: "llm",
         evidence: r.decision.evidence,
diff --git a/src/lib/pipeline/kickoff-infra/index.ts b/src/lib/pipeline/kickoff-infra/index.ts
index ad096cba..d6a31037 100644
--- a/src/lib/pipeline/kickoff-infra/index.ts
+++ b/src/lib/pipeline/kickoff-infra/index.ts
@@ -8,6 +8,7 @@ import {
 import { detectRequiredServices } from "./detect";
 import { provisionDatabase } from "./database";
 import { provisionRedis } from "./redis";
+import { provisionAppS3, readSharedS3Config } from "./s3";
 import type {
   InfraServiceInfo,
   KickoffInfraFile,
@@ -70,19 +71,7 @@ export async function provisionInfra(
 ): Promise<ProvisionInfraResult> {
   const baseUrl = process.env.DOKPLOY_URL?.trim();
   const token = process.env.DOKPLOY_TOKEN?.trim();
-  if (!baseUrl || !token) {
-    return {
-      ok: false,
-      skipped: true,
-      skipReason: "DOKPLOY_URL / DOKPLOY_TOKEN not set",
-      metadata: null,
-      markdownLines: [
-        "### Infra",
-        "_Skipped — set `DOKPLOY_URL` + `DOKPLOY_TOKEN` to provision per-app Postgres / Redis._",
-        "",
-      ],
-    };
-  }
+  const dokployConfigured = !!baseUrl && !!token;
 
   const detection = await detectRequiredServices(input.designDocs);
   const required = detection.services;
@@ -90,7 +79,8 @@ export async function provisionInfra(
     detection.source === "llm"
       ? `LLM${detection.costUsd ? ` $${detection.costUsd.toFixed(4)}` : ""}`
       : `regex${detection.fallbackReason ? ` (LLM fallback: ${detection.fallbackReason})` : ""}`;
-  if (!required.needsPostgres && !required.needsRedis) {
+
+  if (!required.needsPostgres && !required.needsRedis && !required.needsS3) {
     return {
       ok: true,
       skipped: true,
@@ -98,82 +88,113 @@ export async function provisionInfra(
       metadata: null,
       markdownLines: [
         "### Infra",
-        `_No managed services detected (${detectionTag}) — skipped Dokploy provisioning._`,
+        `_No managed services detected (${detectionTag}) — skipped provisioning._`,
         "",
       ],
     };
   }
 
-  const base: DokployBase = { baseUrl, token };
-  const portBase = Number(process.env.DOKPLOY_PORT_BASE ?? "");
-  const portBaseResolved =
-    Number.isFinite(portBase) && portBase > 0 ? portBase : undefined;
-  const publicHost = derivePublicHost(baseUrl);
-
+  // Postgres/Redis live in a per-app Dokploy project; S3 is a shared bucket and
+  // needs no Dokploy at all. When only S3 is needed (or Dokploy isn't
+  // configured) we still provision S3 and skip the Dokploy services.
+  const needsDokploy = required.needsPostgres || required.needsRedis;
+  const detectedLabel = [
+    required.needsPostgres && "postgres",
+    required.needsRedis && "redis",
+    required.needsS3 && "s3",
+  ]
+    .filter(Boolean)
+    .join(" + ");
   const lines: string[] = [
-    "### Infra (Dokploy managed services)",
-    `- Service detection: ${detectionTag} → ${[
-      required.needsPostgres && "postgres",
-      required.needsRedis && "redis",
-    ]
-      .filter(Boolean)
-      .join(" + ")}`,
+    "### Infra (managed services)",
+    `- Service detection: ${detectionTag} → ${detectedLabel}`,
   ];
 
-  let project;
-  try {
-    project = await createAppDokployProject({ base, appName: input.appName });
-    lines.push(`- Created Dokploy project \`${project.projectName}\` (id: \`${project.projectId}\`)`);
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    return {
-      ok: false,
-      error: msg,
-      metadata: null,
-      markdownLines: [...lines, `- ❌ Failed to create Dokploy project: ${msg}`, ""],
-    };
-  }
+  const services: InfraServiceInfo[] = [];
+  const errors: string[] = [];
 
-  const tasks: Promise<InfraServiceInfo>[] = [];
-  if (required.needsPostgres) {
-    tasks.push(
-      provisionDatabase({
-        base,
-        project,
-        appName: input.appName,
-        publicHost,
-        portBase: portBaseResolved,
-      }),
-    );
-  }
-  if (required.needsRedis) {
-    tasks.push(
-      provisionRedis({
-        base,
-        project,
-        appName: input.appName,
-        publicHost,
-        portBase: portBaseResolved,
-      }),
-    );
+  // ── S3 (shared bucket, per-app folder) — Dokploy-independent ──────────────
+  if (required.needsS3) {
+    try {
+      if (!readSharedS3Config()) {
+        lines.push(
+          "- ⚠️ S3 detected but skipped — set `BLUEPRINT_S3_BUCKET` (+ credentials) to enable shared-bucket provisioning.",
+        );
+      } else {
+        const s3 = provisionAppS3({ appName: input.appName });
+        services.push(s3);
+        lines.push(`- Provisioned s3 folder \`${s3.publicUrl}\``);
+      }
+    } catch (e) {
+      errors.push(e instanceof Error ? e.message : String(e));
+    }
   }
 
-  const settled = await Promise.allSettled(tasks);
-  const services: InfraServiceInfo[] = [];
-  const errors: string[] = [];
-  for (const r of settled) {
-    if (r.status === "fulfilled") {
-      services.push(r.value);
+  // ── Postgres / Redis (per-app Dokploy containers) ─────────────────────────
+  let project: Awaited<ReturnType<typeof createAppDokployProject>> | null = null;
+  if (needsDokploy) {
+    if (!dokployConfigured) {
+      lines.push(
+        "- ⚠️ Postgres/Redis detected but skipped — set `DOKPLOY_URL` + `DOKPLOY_TOKEN` to provision them.",
+      );
     } else {
-      errors.push(r.reason instanceof Error ? r.reason.message : String(r.reason));
+      const base: DokployBase = { baseUrl, token };
+      const portBase = Number(process.env.DOKPLOY_PORT_BASE ?? "");
+      const portBaseResolved =
+        Number.isFinite(portBase) && portBase > 0 ? portBase : undefined;
+      const publicHost = derivePublicHost(baseUrl);
+
+      try {
+        project = await createAppDokployProject({ base, appName: input.appName });
+        lines.push(
+          `- Created Dokploy project \`${project.projectName}\` (id: \`${project.projectId}\`)`,
+        );
+
+        const tasks: Promise<InfraServiceInfo>[] = [];
+        if (required.needsPostgres) {
+          tasks.push(
+            provisionDatabase({
+              base,
+              project,
+              appName: input.appName,
+              publicHost,
+              portBase: portBaseResolved,
+            }),
+          );
+        }
+        if (required.needsRedis) {
+          tasks.push(
+            provisionRedis({
+              base,
+              project,
+              appName: input.appName,
+              publicHost,
+              portBase: portBaseResolved,
+            }),
+          );
+        }
+
+        const settled = await Promise.allSettled(tasks);
+        for (const r of settled) {
+          if (r.status === "fulfilled") {
+            services.push(r.value);
+            lines.push(
+              `- Provisioned ${r.value.kind} \`${r.value.appName}\` on port ${r.value.externalPort}`,
+            );
+          } else {
+            errors.push(
+              r.reason instanceof Error ? r.reason.message : String(r.reason),
+            );
+          }
+        }
+      } catch (e) {
+        errors.push(
+          `Failed to create Dokploy project: ${e instanceof Error ? e.message : String(e)}`,
+        );
+      }
     }
   }
 
-  for (const svc of services) {
-    lines.push(
-      `- Provisioned ${svc.kind} \`${svc.appName}\` on port ${svc.externalPort}`,
-    );
-  }
   for (const err of errors) {
     lines.push(`- ❌ Provision failure: ${err}`);
   }
@@ -189,9 +210,12 @@ export async function provisionInfra(
   }
 
   const metadata = await saveKickoffInfraMetadata(input.projectRoot, {
-    dokployProjectId: project.projectId,
-    dokployEnvironmentId: project.environmentId,
-    appName: project.projectName,
+    // S3-only runs have no Dokploy project; empty strings make the deploy
+    // pipeline create a fresh project on first deploy (it treats falsy as
+    // "none yet"), which is exactly the desired behaviour.
+    dokployProjectId: project?.projectId ?? "",
+    dokployEnvironmentId: project?.environmentId ?? "",
+    appName: project?.projectName ?? input.appName,
     services,
   });
   return {
@@ -226,6 +250,19 @@ export function internalRedisUrlFrom(
   return urlForKind(meta.services, "redis")?.internalUrl ?? null;
 }
 
+/**
+ * The S3 credential bundle (bucket, region, keys, per-app prefix) the generated
+ * app needs in its `.env`. Returns null when no S3 service was provisioned.
+ * S3 access is identical from local dev and inside the deployed container, so
+ * there's no public/internal split like Postgres/Redis have.
+ */
+export function s3EnvFrom(
+  meta: KickoffInfraFile | null,
+): Record<string, string> | null {
+  if (!meta) return null;
+  return urlForKind(meta.services, "s3")?.env ?? null;
+}
+
 /**
  * Read-modify-write the `compose` field on `kickoff-infra.json`. Used by the
  * deploy pipeline after a fresh compose stack is created so subsequent
diff --git a/src/lib/pipeline/kickoff-infra/s3.ts b/src/lib/pipeline/kickoff-infra/s3.ts
new file mode 100644
index 00000000..a0666a80
--- /dev/null
+++ b/src/lib/pipeline/kickoff-infra/s3.ts
@@ -0,0 +1,127 @@
+import type { InfraServiceInfo } from "./types";
+
+/**
+ * S3 "provisioning" for generated apps.
+ *
+ * Unlike Postgres/Redis (each gets its own Dokploy container), S3 is a single
+ * SHARED bucket configured once on the Agentic Builder server. Every generated
+ * app gets an isolated FOLDER (key prefix) inside that one bucket — perfect for
+ * throwaway test projects where spinning up a bucket per app is overkill.
+ *
+ * Required server env (set in Agentic Builder `.env.local`):
+ *   BLUEPRINT_S3_BUCKET            — the shared bucket name (presence ENABLES S3)
+ *   BLUEPRINT_S3_ACCESS_KEY_ID     — IAM access key with rw on the bucket
+ *   BLUEPRINT_S3_SECRET_ACCESS_KEY — matching secret
+ *
+ * Optional server env:
+ *   BLUEPRINT_S3_REGION            — defaults to "us-east-1"
+ *   BLUEPRINT_S3_ENDPOINT          — for S3-compatible stores (MinIO, R2, etc.)
+ *   BLUEPRINT_S3_FORCE_PATH_STYLE  — "1"/"true" for path-style addressing
+ *
+ * The generated app reads the standard AWS SDK env names plus AWS_S3_BUCKET /
+ * AWS_S3_PREFIX so worker code can scope every object under its own folder.
+ */
+
+const DEFAULT_REGION = "us-east-1";
+
+export interface SharedS3Config {
+  bucket: string;
+  region: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  endpoint?: string;
+  forcePathStyle: boolean;
+}
+
+/**
+ * Read the shared S3 config from server env. Returns null when S3 is not
+ * configured (no bucket) so the caller can skip provisioning gracefully.
+ * Throws when a bucket is set but credentials are incomplete — a half-configured
+ * S3 is a deployment mistake we should surface, not silently skip.
+ */
+export function readSharedS3Config(): SharedS3Config | null {
+  const bucket = process.env.BLUEPRINT_S3_BUCKET?.trim();
+  if (!bucket) return null;
+
+  const accessKeyId = process.env.BLUEPRINT_S3_ACCESS_KEY_ID?.trim();
+  const secretAccessKey = process.env.BLUEPRINT_S3_SECRET_ACCESS_KEY?.trim();
+  if (!accessKeyId || !secretAccessKey) {
+    throw new Error(
+      "BLUEPRINT_S3_BUCKET is set but BLUEPRINT_S3_ACCESS_KEY_ID / " +
+        "BLUEPRINT_S3_SECRET_ACCESS_KEY are missing — cannot provision S3.",
+    );
+  }
+
+  const force = (process.env.BLUEPRINT_S3_FORCE_PATH_STYLE ?? "").trim();
+  return {
+    bucket,
+    region: process.env.BLUEPRINT_S3_REGION?.trim() || DEFAULT_REGION,
+    accessKeyId,
+    secretAccessKey,
+    endpoint: process.env.BLUEPRINT_S3_ENDPOINT?.trim() || undefined,
+    forcePathStyle: force === "1" || force.toLowerCase() === "true",
+  };
+}
+
+/**
+ * Per-app folder inside the shared bucket. Slug-style, trailing slash so it
+ * reads as a folder key prefix. Mirrors the postgres/redis name sanitiser.
+ */
+export function deriveS3Prefix(appName: string): string {
+  let s = appName.toLowerCase().replace(/[^a-z0-9-]/g, "-").slice(0, 40);
+  s = s.replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+  if (!s) s = "app";
+  return `${s}/`;
+}
+
+/**
+ * Build the env-var bundle the generated app needs to talk to its folder in
+ * the shared bucket. Uses canonical AWS SDK names so off-the-shelf S3 client
+ * code works without a custom config layer.
+ */
+export function buildS3EnvVars(
+  config: SharedS3Config,
+  prefix: string,
+): Record<string, string> {
+  const env: Record<string, string> = {
+    AWS_REGION: config.region,
+    AWS_ACCESS_KEY_ID: config.accessKeyId,
+    AWS_SECRET_ACCESS_KEY: config.secretAccessKey,
+    AWS_S3_BUCKET: config.bucket,
+    AWS_S3_PREFIX: prefix,
+  };
+  if (config.endpoint) env.AWS_S3_ENDPOINT = config.endpoint;
+  if (config.forcePathStyle) env.AWS_S3_FORCE_PATH_STYLE = "true";
+  return env;
+}
+
+export interface ProvisionS3Params {
+  appName: string;
+}
+
+/**
+ * "Provision" S3 for an app: allocate a per-app folder prefix inside the
+ * shared bucket and surface the credential bundle. No remote call — the bucket
+ * already exists; isolation is by key prefix. Throws if S3 isn't configured
+ * (caller should only invoke this when `readSharedS3Config()` is non-null).
+ */
+export function provisionAppS3(params: ProvisionS3Params): InfraServiceInfo {
+  const config = readSharedS3Config();
+  if (!config) {
+    throw new Error(
+      "S3 not configured — set BLUEPRINT_S3_BUCKET (+ credentials) to enable.",
+    );
+  }
+  const prefix = deriveS3Prefix(params.appName);
+  const env = buildS3EnvVars(config, prefix);
+  const display = `s3://${config.bucket}/${prefix}`;
+  return {
+    kind: "s3",
+    id: prefix,
+    appName: config.bucket,
+    publicUrl: display,
+    internalUrl: display,
+    externalPort: 0,
+    env,
+  };
+}
diff --git a/src/lib/pipeline/kickoff-infra/types.ts b/src/lib/pipeline/kickoff-infra/types.ts
index 94f46e73..3d3dacc7 100644
--- a/src/lib/pipeline/kickoff-infra/types.ts
+++ b/src/lib/pipeline/kickoff-infra/types.ts
@@ -5,20 +5,27 @@
  * `deploy/pipeline.ts` can read the same source of truth.
  */
 
-export type InfraServiceKind = "postgres" | "redis";
+export type InfraServiceKind = "postgres" | "redis" | "s3";
 
 export interface InfraServiceInfo {
   kind: InfraServiceKind;
-  /** Dokploy-side ID for delete/teardown. */
+  /** Dokploy-side ID for delete/teardown. For s3 this is the per-app prefix. */
   id: string;
-  /** Dokploy-side service `appName` — used as internal hostname. */
+  /** Dokploy-side service `appName` — used as internal hostname. For s3 it's the bucket name. */
   appName: string;
-  /** Public URL — what the developer's local `pnpm dev` reads from .env. */
+  /** Public URL — what the developer's local `pnpm dev` reads from .env. For s3 a display `s3://bucket/prefix`. */
   publicUrl: string;
-  /** Internal URL on dokploy-network — what compose services should use. */
+  /** Internal URL on dokploy-network — what compose services should use. For s3 same as publicUrl. */
   internalUrl: string;
-  /** Host port exposed by Dokploy. */
+  /** Host port exposed by Dokploy. 0 for s3 (no published port). */
   externalPort: number;
+  /**
+   * Extra env vars this service contributes to the generated app's `.env`.
+   * Postgres/Redis leave this unset (they map to a single DATABASE_URL /
+   * REDIS_URL derived from `publicUrl`/`internalUrl`). S3 sets the full
+   * credential bundle (bucket, region, keys, per-app prefix) here.
+   */
+  env?: Record<string, string>;
 }
 
 /**
@@ -53,6 +60,7 @@ export interface KickoffInfraFile {
 export interface RequiredServices {
   needsPostgres: boolean;
   needsRedis: boolean;
+  needsS3: boolean;
 }
 
 export interface ProvisionInfraInput {