Pongreay

Secure Docker deployment CLI for modern applications.

Pongreay simplifies the process of building, uploading, and deploying Docker containers to remote servers via SSH. It includes built-in safety checks, health monitoring, and automatic rollback capabilities.

Features

• Branch Protection: Ensures deployments only happen from the correct Git branches.
• Git Safety: Requires a clean Git state before deployment.
• Automated Tests: Runs your test suite before building the image.
• Zero-Downtime-ish Deployment: Stops the old container and starts the new one, with quick health checks.
• Automatic Rollback: If the new container fails its health check, Pongreay automatically rolls back to the previous version.
• Simple Configuration: Single YAML file to manage all your environments.
• Operational Commands: Inspect status, stream logs, run diagnostics, and trigger manual rollback.
• Safer Env Handling: Blocks deploys when local .env files could enter the Docker image.

Installation

npm install -g pongreay

(Note: Ensure you have docker, ssh, and scp installed on your machine and accessible via CLI.)

Quick Start

1. Initialize Configuration

Run the following command in your project root to create a pongreay.config.yml file:

# Using defaults (deploy@your-ip-address)
pongreay init

# Or with custom server details
pongreay init --hostname deploy --ip 192.168.0.1

2. Configure Your Environments

Edit pongreay.config.yml to match your server details:

project: my-awesome-app
healthPath: /health

environments:
  uat:
    server: [email protected]
    branch: develop
    appName: my-app-uat
    imageName: my-app
    envFileOnServer: /etc/pongreay/my-app/uat.env
    hostPort: 3000
    containerPort: 3000

  production:
    server: [email protected]
    branch: main
    appName: my-app-prod
    imageName: my-app
    envFileOnServer: /etc/pongreay/my-app/prod.env
    hostPort: 8080
    containerPort: 3000

3. Deploy

Deploy to UAT:

pongreay uat

Deploy to Production (requires confirmation):

pongreay production --confirm

Commands

pongreay init

Creates a default pongreay.config.yml in the current directory.

Options:

• --hostname <hostname>: The SSH user/hostname to use (default: deploy).
• --ip <ip>: The server IP address (default: your-ip-address).

pongreay [environment]

Deploys the application to the specified environment.

Options:

• --confirm: Required for deploying to the production environment.
• --dry-run: Shows the deployment plan without executing any remote commands.
• --skip-tests: Skips running npm test before the build process.
• --no-cache: Builds the Docker image without using cache.
• --build-arg <arg>: Passes a non-secret Docker build argument, for example --build-arg NODE_ENV=production. Secret-like names such as TOKEN, PASSWORD, SECRET, or API_KEY are blocked. Can be used multiple times.
• --build-secret <secret>: Passes a Docker BuildKit secret, for example --build-secret id=npmrc,src=.npmrc. Can be used multiple times.
• --timeout <seconds>: Sets health-check timeout duration. Default: 30.
• --keep-images <count>: Keeps the newest matching remote images after successful deploy. Default: 5.

Build Secrets

Do not pass secrets through --build-arg; Docker may store build args in image metadata, build cache, or history.

Use --build-secret with a Dockerfile BuildKit secret mount:

pongreay uat --build-secret id=npmrc,src=.npmrc

RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci

pongreay config validate

Validates pongreay.config.yml, required environment fields, secure env-file paths, and .dockerignore env exclusions.

pongreay config validate

pongreay doctor [environment]

Checks local tools (git, docker, ssh, scp), validates config, and optionally checks remote Docker/env-file status.

pongreay doctor
pongreay doctor uat

pongreay env setup <environment>

Prints secure server setup commands for the configured env file.

pongreay env setup uat

Example output:

sudo mkdir -p '/etc/pongreay/my-app'
sudo nano '/etc/pongreay/my-app/uat.env'
sudo chown 'deploy:deploy' '/etc/pongreay/my-app/uat.env'
sudo chmod 600 '/etc/pongreay/my-app/uat.env'

pongreay status <environment>

Shows the remote container, current image, mapped ports, and health-check result.

pongreay status uat

pongreay logs <environment>

Streams remote Docker logs for the configured container.

pongreay logs uat
pongreay logs uat --tail 500

pongreay rollback <environment>

Rolls back to the previous image recorded during the last Pongreay deploy.

pongreay rollback uat

Environment File Security

Pongreay does not upload your local .env file and does not copy it into the Docker image. The container receives environment variables at runtime from envFileOnServer.

Before deployment, Pongreay requires:

• .dockerignore contains .env and .env.*.
• envFileOnServer is under /etc/pongreay/, outside the app directory.
• The server env file exists and is readable by the deploy user.
• The server env file owner is the deploy user or root.
• The server env file permissions are 600 or 400; Pongreay attempts chmod 600 before enforcing this.

Example server setup:

sudo mkdir -p /etc/pongreay/my-app
sudo nano /etc/pongreay/my-app/production.env
sudo chown deploy:deploy /etc/pongreay/my-app/production.env
sudo chmod 600 /etc/pongreay/my-app/production.env

Requirements

• Local Machine:
  • Docker
  • SSH / SCP
  • Git
  • Node.js (for running the CLI)
• Remote Server:
  • Docker
  • A protected environment file under /etc/pongreay/ specified by envFileOnServer.

Supply Chain Security

Pongreay is a deployment CLI and intentionally invokes local tools such as git, docker, ssh, and scp. It does not use npm install hooks, and runtime dependencies are kept minimal.

Install Pongreay from the official npm package and review your pongreay.config.yml before deploying. See SECURITY.md for vulnerability reporting.

How it Works

1. Pre-flight Checks: Verifies the current Git branch and ensures there are no uncommitted changes.
2. Testing: Runs npm test to ensure code quality.
3. Build: Builds a Docker image tagged with the current environment and commit hash.
4. Export: Saves and compresses the Docker image.
5. Upload: Transfers the image to the remote server via scp.
6. Remote Execution:
   • Loads the Docker image on the server.
   • Stops and removes the existing container.
   • Starts the new container with the specified ports, environment file, and rollback labels.
   • Performs a health check against the healthPath.
7. Cleanup/Rollback:
   • On success: Removes the temporary image file from the server and prunes old matching images according to --keep-images.
   • On failure: Restarts the previous container and exits with an error.

License

MIT