feat(docker): include default templates for first-run seeding

Author: Chris Funderburg

.dockerignore

@@ -12,6 +12,7 @@ dist/
 .github/
 *.md
 !README.md
+!data/templates/**
 .env*
 .DS_Store
 *.log

Dockerfile

@@ -43,6 +43,9 @@ RUN npm ci --omit=dev
 COPY --from=builder /app/server/dist ./server/dist
 COPY --from=builder /app/client/dist ./client/dist
 
+# Include default templates in the image for first-run seeding into the mounted data volume
+COPY data/templates ./seed/templates
+
 # Create data directory and set permissions
 RUN mkdir -p /app/data && chown -R codex:codex /app
 
@@ -55,6 +58,11 @@ EXPOSE 3001
 # Set environment variables
 ENV NODE_ENV=production
 ENV PORT=3001
+ENV DATA_DIR=/app/data
+
+# Seed templates into the data volume on first run (only if data/templates is missing or empty)
+ENV CODEX_SEED_TEMPLATES=true
+ENV CODEX_SEED_TEMPLATES_DIR=/app/seed/templates
 
 # Health check
 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \

README.md

@@ -550,6 +550,9 @@ docker stop codex && docker rm codex
 **Volume Mounting**:
 - `./data:/app/data` - Persists your wiki data outside the container
 
+**Templates on first run**:
+- The Docker image includes built-in starter templates; on first startup, if `data/templates/` is missing or empty, Codex will copy the defaults into it.
+
 ### Authentication in Docker
 
 **Important**: Due to secure cookie requirements, there are two ways to run Codex with authentication:

server/src/services/fileSystem.ts

@@ -120,6 +120,67 @@ export class FileSystemService {
     } catch {
       await fs.mkdir(this.dataDir, { recursive: true });
     }
+
+    await this.seedTemplatesIfConfigured();
+  }
+
+  private async seedTemplatesIfConfigured(): Promise<void> {
+    if (process.env.CODEX_SEED_TEMPLATES !== "true") {
+      return;
+    }
+
+    const seedDir = process.env.CODEX_SEED_TEMPLATES_DIR;
+    if (!seedDir) {
+      return;
+    }
+
+    const templatesDir = this.validatePath("templates");
+
+    let shouldSeed = false;
+    try {
+      const entries = await fs.readdir(templatesDir, { withFileTypes: true });
+      // Seed only when the directory is empty (ignore dotfiles like .DS_Store)
+      const visibleEntries = entries.filter((entry) => !entry.name.startsWith("."));
+      shouldSeed = visibleEntries.length === 0;
+    } catch (error: any) {
+      if (error?.code === "ENOENT") {
+        shouldSeed = true;
+      } else {
+        return;
+      }
+    }
+
+    if (!shouldSeed) {
+      return;
+    }
+
+    try {
+      await fs.mkdir(templatesDir, { recursive: true });
+      const seedEntries = await fs.readdir(seedDir, { withFileTypes: true });
+      const templateFiles = seedEntries
+        .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".md"))
+        .map((entry) => entry.name);
+
+      for (const filename of templateFiles) {
+        const sourcePath = path.join(seedDir, filename);
+        const destPath = path.join(templatesDir, filename);
+        try {
+          await fs.access(destPath);
+          // Don't overwrite existing files
+          continue;
+        } catch {
+          // ok
+        }
+
+        await fs.copyFile(sourcePath, destPath);
+      }
+
+      // Invalidate caches that might be affected
+      this.cache.invalidate("folder-tree:");
+      this.cache.invalidate("pages:templates");
+    } catch {
+      // Best-effort seeding; ignore failures to avoid blocking startup
+    }
   }
 
   async getFolderTree(relativePath: string = ""): Promise<FolderNode> {