Deployment and CI/CD
Relevant source files
The following files were used as context for generating this wiki page:The PRPM project utilizes a container-based deployment strategy orchestrated with Docker Compose for production environments, with services hosted on AWS Elastic Beanstalk. The CI/CD process is managed through GitHub Actions, and releases are semi-automated with shell scripts. The command-line interface (CLI) is distributed to end-users via Homebrew.
This system is designed to be robust, with clear separation of services and documented procedures for development, deployment, and recovery. For more detailed guides, refer to the internal documentation on Deployment and GitHub Workflows.
Sources: docker-compose.prod.yml, scripts/create-release.sh, scripts/fix-beanstalk-rollback.sh, Formula/prmp.rb, DOCUMENTATION_MAP.md
Production Environment Architecture
The production environment is defined in docker-compose.prod.yml and consists of several containerized services that work together to run the PRPM platform. Caddy is used as the reverse proxy and entry point for web traffic.
Sources: docker-compose.prod.yml
Services Overview
The following diagram illustrates the relationships between the production services.
This diagram shows the flow of traffic from the internet through the Caddy reverse proxy to the web and api services, and the api service's connections to the db and redis data stores.
Sources: docker-compose.prod.yml
The services are configured as follows:
| Service | Image | Build Context | Description | Dependencies |
|---|---|---|---|---|
caddy | caddy:2-alpine | N/A | Acts as the reverse proxy, handling HTTPS and routing traffic to the web and api services. | web, api |
web | prpm-web | . (Dockerfile.web.prod) | The Next.js frontend application. | api |
api | prpm-api | . (Dockerfile.api.prod) | The backend API service. | db, redis |
db | postgres:16-alpine | N/A | The PostgreSQL database for persistent data storage. | N/A |
redis | redis:7-alpine | N/A | Redis instance used for caching and session management. | N/A |
Sources: docker-compose.prod.yml:5-66
Configuration Details
- Networking: All services communicate over a custom bridge network named
caddy-net. Caddy is the only service that exposes ports (80,443) to the host. - Environment Variables: Service configurations (e.g., database credentials, application secrets) are loaded from a
.env.prodfile. - Data Persistence: The PostgreSQL database uses a named volume
postgres-datato persist data across container restarts. - Builds: The
webandapiservices are built fromDockerfile.web.prodandDockerfile.api.prodrespectively, using the root of the repository as the build context.
Sources: docker-compose.prod.yml
Release Management and CI/CD
The release process is managed through a combination of a shell script and GitHub Actions. The create-release.sh script facilitates the versioning and tagging process locally.
Sources: scripts/create-release.sh, DOCUMENTATION_MAP.md
Release Creation Workflow
The create-release.sh script automates the steps required to prepare a new release.
This flowchart outlines the local release preparation process, from checking the git status to opening the GitHub UI for release finalization.
Sources: scripts/create-release.sh
The script performs the following actions:
- Validates Git Status: Ensures the working directory is clean before proceeding.
- Gets New Version: Prompts the developer to enter the new version number.
- Bumps Version: Updates the
versionfield in the rootpackage.jsonfile. - Commits Change: Creates a git commit with the message
chore: release v[VERSION]. - Tags Release: Creates a git tag (e.g.,
v1.2.3) and pushes it to the remote repository. - Opens GitHub: Opens the default web browser to the "New Release" page on GitHub, pre-filled with the new tag.
Sources: scripts/create-release.sh:4-31
CI/CD with GitHub Actions
The project uses GitHub Actions for CI/CD. While the specific workflow files are not provided, the documentation map and other files confirm their use for tasks like testing, deployment, and publishing. The beanstalk-deploy skill mentions deployment via GitHub Actions, indicating that the deployment process to AWS is automated.
Sources: DOCUMENTATION_MAP.md:12, CLAUDE.md:162, CONTRIBUTING.md:60
AWS Elastic Beanstalk Deployment
The application is deployed to AWS Elastic Beanstalk. The project includes tooling and defined expertise for managing these deployments, including handling rollbacks.
Sources: scripts/fix-beanstalk-rollback.sh, CLAUDE.md
Deployment Strategy
The project maintains an internal beanstalk-deploy skill, which suggests a robust deployment pattern using GitHub Actions and potentially Pulumi for infrastructure as code. This indicates a sophisticated, automated deployment pipeline.
Sources: CLAUDE.md:161-163
Handling Failed Deployments
A utility script, fix-beanstalk-rollback.sh, provides a semi-automated way to recover from a failed deployment on Elastic Beanstalk. This is crucial for maintaining service availability.
The recovery process is as follows:
This sequence diagram shows the interaction between a developer, the rollback script, and the AWS CLI to redeploy a previously successful application version.
Sources: scripts/fix-beanstalk-rollback.sh
The script first identifies the version label of the last successful deployment and the current (failed) one. It then prompts the user for confirmation before using the AWS CLI to redeploy the last known good version, effectively rolling back the failed update.
Sources: scripts/fix-beanstalk-rollback.sh:10-39
CLI Distribution via Homebrew
The prpm CLI tool is distributed to macOS users via a custom Homebrew formula.
Sources: Formula/prmp.rb
Homebrew Formula Details
The file Formula/prmp.rb defines the package for Homebrew.
| Field | Value/Description |
|---|---|
desc | "The Prompt Package Manager" |
homepage | "https://prpm.dev" |
url | The URL to the source tarball for a specific release. |
sha256 | The checksum to verify the integrity of the downloaded tarball. |
license | "MIT" |
depends_on | node |
Sources: Formula/prmp.rb:2-8
Installation Process
When a user runs brew install prpm, the formula executes the following steps:
- Installs the
nodedependency if it's not already present. - Runs
npm installto fetch all Node.js dependencies. - Runs
npm run buildto compile the project. - Copies the necessary files (e.g.,
packages/cli/dist,node_modules) into the Homebrew cellar. - Creates a launch script at
bin/"prpm"that executes the CLI using the installed Node.js runtime.
Sources: Formula/prmp.rb:11-17
The formula also includes a test block that verifies the installation by running prpm --version.
Sources: Formula/prmp.rb:20-22
Conclusion
The deployment and CI/CD infrastructure for prpm is a well-rounded system that leverages modern development practices. Containerization with Docker Compose ensures a consistent production environment. Release management is streamlined with helper scripts and automated through GitHub Actions. Hosting on AWS Elastic Beanstalk provides a scalable platform, with thoughtful tooling for recovery from failed deployments. Finally, Homebrew is used for user-friendly distribution of the CLI, making it easily accessible to developers on macOS.