Deployer

Remote-friendly deployment runner that triggers predefined shell commands through an HTTP API and lightweight dashboard.

Overview

Deployer lets you run repeatable deployment scripts on a server by calling a secure HTTP endpoint. You define each application once—its working directory, the commands to run, and who should be notified—and Deployer orchestrates the run, streams the output to a log file, and optionally emails the results. It is built with TypeScript, Hono, and the Resend email API, making it easy to host on any Node.js-compatible environment.

Key features

• 📦 Manage any number of applications with their own command pipelines.
• 🌐 Trigger deployments remotely via a REST endpoint or from the bundled HTML console.
• ✉️ Receive success and failure alerts by email through Resend.
• 🔐 Protect the endpoint with optional HTTP basic authentication.
• 🪵 Inspect per-application logs generated for every deployment attempt.
• ⚙️ Ships as plain TypeScript—no build step required, runs with tsx.

Requirements

• Node.js 18.0.0 or newer (required by tsx).
• npm, pnpm, or yarn for installing dependencies (examples below use pnpm).
• Resend API Key, if you want to enable email notifications. You can sign up for a free account at resend.com.

Getting started

1. Install dependencies

# npm
npm install

# pnpm
pnpm install

# yarn
yarn install

2. Configure environment variables

Create a .env file in the project root. All variables are optional; sensible defaults are used when omitted. However, email notifications require a Resend API key and sender address.

PORT=12345                      # Port the Hono server listens on (defaults to 12345)

# Resend email configuration (optional, required for notifications)
RESEND_API_KEY=your_api_key
RESEND_EMAIL_SENDER="Deployer <[email protected]>"

# Basic auth credentials (optional)
BASIC_AUTH_USERNAME=admin
BASIC_AUTH_PASSWORD=super-secret

Variable	Required	Description
PORT	No	Port exposed by the HTTP server. Defaults to 12345.
RESEND_API_KEY	Required for email	API key generated in Resend. Without it, emails are skipped.
RESEND_EMAIL_SENDER	Required for email	Sender address used in notification emails.
BASIC_AUTH_USERNAME / BASIC_AUTH_PASSWORD	No	If both are set, every request must authenticate with basic auth.

3. Register applications

Applications are defined in apps.json at the project root. The file is created automatically with an empty list the first time the server runs.

[
  {
    "name": "frontend",
    "path": "/var/www/frontend",
    "cmd": [
      "git pull",
      "npm install --frozen-lockfile",
      "npm run build",
      "pm2 restart frontend"
    ],
    "notify": {
      "email": ["[email protected]", "[email protected]"]
    }
  }
]

Field notes:

• name: Display name and identifier used in API requests.
• path: Directory that should be used as the working directory before executing commands.
• cmd: Ordered list of shell commands. They run sequentially via &&.
• notify.email: List of recipients who should be notified about success or failure.

Running locally

• Production mode:

  # npm
  npm run start
  
  # pnpm
  pnpm start
  
  # yarn
  yarn start

• Development mode (auto-reload):

  # npm
  npm run dev
  
  # pnpm
  pnpm dev
  
  # yarn
  yarn dev

The server prints the URL once it is ready. Visit http://localhost:12345/ (or your configured port) to access the dashboard.

Triggering deployments

Web console

Open / in a browser to access the included HTML dashboard. Pick the application from the dropdown and click Deploy to send the request.

API reference

Method	Endpoint	Description
POST	/redeploy	Trigger the deployment pipeline for a registered application.

Request body

• Content type: application/x-www-form-urlencoded or multipart/form-data.
• Fields:
  • app (string, required): Matches the name value defined in apps.json.

Responses

• 200 OK – Deployment accepted and running in the background.
• 400 Bad Request – A deployment is already running for this app.
• 404 Not Found – The requested app name does not exist.
• 401 Unauthorized – Basic auth is enabled and the client sent invalid credentials.

The command pipeline executes asynchronously. The endpoint responds immediately while the process continues in the background.

Logs

All output is collected per application in ./logs/<app-name>.log. The log file is cleared each time a new deployment starts and includes stdout, stderr, and timeout messages. Review these files when investigating failures.

Email notifications

If Resend credentials and recipient emails are configured, Deployer sends either a success or failure email once the pipeline finishes. Failure emails include the captured log output to speed up debugging.

Authentication

Set both BASIC_AUTH_USERNAME and BASIC_AUTH_PASSWORD to enforce HTTP basic authentication on every request. When omitted, the server remains open.

Production deployment tips

• Run pnpm start under a process manager such as pm2, systemd, or Docker.
• Ensure the user running Deployer has permissions to execute the commands defined in apps.json.
• Keep the logs/ directory writable; Deployer relies on it when composing failure emails.
• Consider serving the app behind a reverse proxy (Nginx, Traefik, etc.) with HTTPS.

Troubleshooting

• "App not found" – Confirm the app field in the request matches a name in apps.json exactly.
• No emails sent – Verify RESEND_API_KEY, RESEND_EMAIL_SENDER, and the recipient list. The service silently skips email delivery if credentials are missing.
• Command exits early – Commands run with a 5-minute timeout. Inspect the log file for details and adjust your script to finish within the limit.
• 401 Unauthorized – When basic auth is enabled, include the credentials in every request.
• Empty logs – The file is cleared at the start of each deployment. Wait for the run to finish or check that the process user can write to the logs/ directory.

Roadmap ideas

• Support for concurrent command stages with richer status reporting.
• WebSocket or SSE streaming for real-time log updates in the dashboard.
• Additional notification channels (Slack, Teams, etc.).