bootstrap-vapor-service

Bootstrap Vapor Service

Purpose

Create a new Vapor service repository from nothing to a consistent, database-backed local baseline.

The practical decision is not whether Vapor should use the CLI, Fluent, PostgreSQL, Docker, or its built-in Environment system. The default is already chosen: start with the official Vapor CLI, use Vapor's Environment API for runtime environment and process settings, choose Fluent ORM with PostgreSQL, and preserve the CLI-generated Dockerfile and Docker Compose Postgres surface during bootstrap.

When To Use

• Use this skill when the user wants to start, begin, create, scaffold, or bootstrap a new Vapor service.
• Use this skill when a new Vapor service should receive durable repo-local AGENTS.md guidance.
• Use this skill when the user asks for the standard Vapor service baseline, including Fluent ORM, PostgreSQL, and local container support.
• Use this skill when maintaining the bootstrap defaults for future Vapor services.
• Do not use this skill for ordinary routes, controllers, middleware, commands, migrations, or tests in an existing Vapor service. Use vapor-server-workflow.
• Do not use this skill for existing persistence changes that are not part of initial bootstrap. Use persistence-workflow.
• Do not use this skill for generic Docker image production work. Use docker-workflow.
• Do not substitute a manual SwiftPM scaffold, discard the CLI-generated Docker files, use a non-Fluent database layer, use SQLite, or use non-container local database setup unless the user explicitly approves that exception for the project.

Source Check

Use repo-local Swift files, checked-out dependency sources, Dash MCP or Dash HTTP for installed Vapor DocC first, then official Vapor documentation when Dash/local coverage is missing or stale:

• Vapor installation
• Vapor Hello, world
• Vapor Environment
• Vapor Fluent overview
• Vapor Fluent migrations
• Vapor Docker deploys
• Vapor GitHub organization

Use SwiftPM and Swift.org documentation for package, toolchain, and Linux behavior when Vapor docs do not own the rule being used.

Single-Path Workflow

1. Collect the required inputs:
   • name
   • destination
   • optional database_name
   • optional database_user
   • optional database_password
   • optional skip_validation
2. Verify prerequisites:
   • swift
   • git
   • vapor
   • Docker-compatible runtime only when Compose validation is requested
3. Create the service with the official CLI:

   vapor new <name>
   

4. Answer the CLI prompts using the standard default:
   • include Fluent
   • choose PostgreSQL as the database driver
   • keep Vapor 4 as the stable default unless the user explicitly asks for Vapor 5 alpha evaluation
5. Preserve Vapor's generated application structure:
   • Sources/App/configure.swift
   • Sources/App/routes.swift
   • generated model, migration, and test shape when present
6. Use Vapor Environment for runtime behavior:
   • keep environment-specific branching on app.environment
   • use Environment.get or Environment.process for process settings
   • keep committed .env content as a safe template only
   • keep .env.* overrides ignored when they may contain local or secret values
7. Preserve and verify the CLI-generated container support:
   • keep the Vapor-generated .dockerignore, Dockerfile, and Compose file
   • preserve the generated app, migrate, revert, and database services when present
   • adapt generated service names and database defaults only when needed for the project name or repo conventions
   • use safe development-only defaults
   • use a named volume for database storage
   • align host, port, database, user, and password with Vapor's local .env template
8. Install generated repo guidance:
   • copy assets/AGENTS.md into the new repository root
   • update placeholders for project name, database name, and validation commands
   • keep the generated guidance local to the new service because this plugin's own AGENTS.md is not visible inside ordinary service repositories
9. Install Codex GUI local environment guidance when desired:
   • copy templates/codex-local-environments/vapor.toml into .codex/environments/vapor.toml
   • adjust the executable name only when the app target is not App
10. Validate the scaffold:

• swift build
• swift test
• docker compose config
• optional docker build .
• optional docker compose up -d postgres
• optional swift run App migrate after confirming the generated database config and migration list
• optional swift run App serve only when runtime startup validation is requested

11. Return the created path, exact commands, environment source, database defaults, validation results, and next handoff.

Defaults

• service framework: Vapor
• creation command: vapor new <name>
• Vapor version posture: Vapor 4 stable default; Vapor 5 alpha only by explicit request
• persistence: Fluent ORM
• database: PostgreSQL
• local dependency runtime: Docker Compose Postgres service
• service image baseline: preserve the CLI-generated Dockerfile
• generated guidance: root AGENTS.md
• app configuration: Vapor Environment
• development database defaults:
  • host: localhost
  • port: 5432
  • database: normalized service name
  • username: normalized service name
  • password: development-password
• validation runs unless skip_validation is requested

Outputs

• status
  • success: service scaffold, repo guidance, and requested validation completed
  • blocked: prerequisites, target-directory constraints, or unsupported CLI choices prevented the run
  • failed: the scaffold started but generation, dependency wiring, or validation failed
• path_type
  • primary: official Vapor CLI bootstrap path
  • fallback: non-mutating guidance only because the CLI path could not safely run
• output
  • resolved service path
  • Vapor app target name
  • Vapor Environment and dotenv source
  • Fluent and PostgreSQL dependencies added or confirmed
  • compose.yaml shape
  • generated AGENTS.md installed
  • validation result
  • one concise next handoff

Guardrails

• Strong default: use vapor new, Vapor Environment, Fluent ORM, PostgreSQL, and Docker Compose for every fresh Vapor service unless the user explicitly approves a project-specific exception.
• Do not hand-roll a new SwiftPM project as the default Vapor bootstrap path.
• Do not remove or postpone Docker files generated by vapor new; validate and keep them in the initial scaffold.
• Do not bypass Vapor Environment with a second settings framework for standard runtime configuration.
• Do not choose SQLite, MySQL, direct SQL, or non-Fluent persistence as the default bootstrap path.
• Do not commit secrets, real database passwords, .env.* files with sensitive values, machine-local paths, or private dependency URLs.
• Do not run destructive migrations, database drops, volume deletion, or migration reverts without explicit user approval.
• Do not claim Vapor CLI behavior, generated file layouts, Fluent driver names, or migration commands from memory; check current Vapor docs, vapor --help, or generated scaffold files.
• Use docker-workflow only when changing beyond the CLI-generated Docker baseline, such as adding nonstandard services, registry publishing, CI image builds, deployment-runtime tuning, or image hardening.

Fallbacks And Handoffs

• If vapor is missing and Homebrew is acceptable, install with:

  brew install vapor
  

• If vapor is unavailable and cannot be installed, stop with a non-mutating fallback plan. Do not silently switch to a manual SwiftPM scaffold.
• After successful bootstrap, use vapor-server-workflow for routes, controllers, middleware, commands, app configuration, and Vapor tests.
• Use persistence-workflow for models, migrations, query design, transactions, and database-backed tests after the initial baseline exists.
• Use docker-workflow for production Dockerfiles, multi-stage images, image validation, registries, or container deployment.
• Use fly-io-deployment-workflow for Fly.io apps, Fly Postgres, secrets, health checks, and deploy validation.

References

• assets/AGENTS.md