Deployment Guide
Relevant source files
The following files were used as context for generating this wiki page:This guide outlines the standardized methodology for planning, documenting, and executing deployment within the project. The approach is integrated into the three-phase Spec-Driven Development workflow, ensuring that deployment is a well-documented and automated process. It covers the guiding principles, documentation requirements, task planning, and tooling that form the project's deployment strategy.
The overall process emphasizes defining deployment strategies during the Design Phase, codifying environment and build standards in Steering Documents, breaking down work into actionable Implementation Tasks, and automating the process using CI/CD Tooling.
Core Deployment Principles: The Twelve-Factor App
The project's deployment methodology is founded on the principles of the Twelve-Factor App, which are designed to enable robust, scalable, and maintainable applications.
Sources: spec-process-guide/resources/standards.md
The following diagram highlights key principles relevant to deployment:
Key principles include:
- Build, Release, Run: Maintain strict separation between the build, release, and run stages. The build stage converts code into an executable bundle, the release stage combines it with configuration, and the run stage executes the release.
- Config: Store all configuration in environment variables, never in the code. This allows the same build to be deployed across different environments (development, staging, production).
- Processes: Execute the app as one or more stateless processes. This facilitates scaling and resilience.
- Port Binding: Export services via port binding, making them self-contained.
- Disposability: Maximize robustness with fast startup and graceful shutdown. Processes should be disposable and able to be started or stopped at a moment's notice.
- Dev/Prod Parity: Keep development, staging, and production environments as similar as possible to reduce bugs and simplify deployments.
Sources: spec-process-guide/resources/standards.md
Documenting the Deployment Strategy
Deployment planning is a formal part of the project's documentation process, captured in both the Design Document and specific Steering Documents.
Design Phase Documentation
During the Design Phase, the high-level deployment strategy is defined within the Design Template. This ensures that operational concerns are considered early in the development lifecycle.
Sources: spec-process-guide/templates/design-template.md
| Section | Description |
|---|---|
| Deployment Strategy | The chosen approach for deploying the feature (e.g., blue-green, rolling update, canary). Includes environment progression and rollback procedures. |
| Configuration Management | The approach for managing environment-specific settings and secrets. |
| Monitoring and Alerting | Definition of health checks, key metrics to monitor, and alert conditions. |
| Maintenance Procedures | Outlines regular maintenance tasks, backup/recovery plans, and update strategies. |
Sources: spec-process-guide/templates/design-template.md
Steering Documents for Deployment
For ongoing project-wide standards, a development-environment.md steering document is created. This file provides contextual guidance for AI assistants and developers on environment setup, build, and deployment processes.
Sources: commands/create-steering-documents-standalone.md, skills/create-steering-documents/SKILL.md
The development-environment.md file is conditionally included when files like package.json, Dockerfile, or docker-compose.yml are part of the context. It typically contains the following sections:
| Section | Purpose |
|---|---|
| Local Development | Instructions for setting up a local environment, including Node.js versions and dependency installation (npm ci). |
| Environment Variables | Rules for managing environment variables, such as using .env.example files and never committing .env files. |
| Build and Deployment | Guidelines for ensuring reproducible builds, using multi-stage Docker builds for optimization, and including health checks in containers. |
| Debugging and Logging | Standards for structured logging, correlation IDs for tracing, and error monitoring. |
Sources: commands/create-steering-documents-standalone.md:162-199
Deployment Implementation Plan
The high-level strategy from the Design Document is broken down into concrete, actionable steps during the Tasks Phase, using the Tasks Template.
Sources: spec-process-guide/templates/tasks-template.md
Phase 6: Deployment and Documentation
This final phase of the implementation plan focuses on preparing the feature for release.
This flowchart shows the typical tasks within the deployment phase:
Tooling and Automation (CI/CD)
The project advocates for using CI/CD tools to automate the build, test, and deployment pipeline.
Sources: spec-process-guide/resources/tools.md
Recommended Tools
| Tool | Best For |
|---|---|
| GitHub Actions | GitHub-integrated CI/CD, workflow automation. |
| Jenkins | Enterprise CI/CD, complex pipelines. |
| GitLab CI | GitLab-integrated CI/CD, DevOps workflows. |
Sources: spec-process-guide/resources/tools.md
Conceptual CI/CD Pipeline
A typical CI/CD pipeline automates the steps from code commit to deployment, ensuring quality and consistency.
This diagram illustrates a conceptual CI/CD flow, where code changes are automatically built, tested, and deployed to various environments.
Sources: spec-process-guide/resources/tools.md, spec-process-guide/templates/design-template.md:158-176
Example GitHub Actions Workflow
The following is an example of a GitHub Actions workflow snippet that could be adapted for deployment. It triggers on a pull request, checks out the code, and runs tests. A deployment workflow would extend this to include build and deploy steps.
name: Requirement Validation
on:
pull_request:
paths:
- 'src/requirements/**'
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Run requirement tests
run: npm test -- --grep "Requirement"