DEV Community: DeployHQ

Self-Host n8n on a VPS: Docker, HTTPS, and Git-Based Updates

DeployHQ — Thu, 21 May 2026 09:40:22 +0000

Most n8n self-hosting tutorials stop at docker compose up. That gets you a running instance, but it leaves a real gap: where do your workflows live? How do you upgrade without losing them? How do you roll back a bad change? Treat your n8n server like any other application — workflows in Git, infrastructure in Docker Compose, deploys triggered from main — and self-hosting becomes a maintainable habit instead of a fragile pet project.

This guide walks through standing up n8n on a single VPS with Docker, putting it behind HTTPS, and wiring it to a DeployHQ project so every change to your workflow repo updates the server. By the end you'll have a production-ready instance with backups, version control, and one-click rollback when something goes wrong.

What you'll build

n8n running in Docker on a single Ubuntu VPS
Postgres alongside it as the data store (not SQLite — more on that below)
Nginx + Let's Encrypt in front for HTTPS on your own domain
A Git repository that holds the docker-compose.yml, environment template, and an exportable JSON copy of every workflow
DeployHQ wiring the repo to the server, so a git push to main reconfigures the stack and re-imports workflows

By the end you'll be able to develop a workflow locally (or on a staging instance), export it, commit, push, and watch DeployHQ deploy the change with rollback available if it misbehaves.

Why self-host n8n at all?

n8n Cloud is good. So why bother with a VPS?

Cost predictability. A $5-10/month VPS handles thousands of runs per day. Cloud pricing scales by execution.
Data stays on your infrastructure. Webhooks, credentials, and execution logs never leave the box.
Custom nodes. You can npm install community nodes the cloud version doesn't ship.
No execution limits. Long-running flows that hit cloud step caps just run.

The trade-off is operational ownership — you patch the OS, renew the certificate, watch the disk. Most of that is one-time setup. The rest of this guide is the one-time setup, done properly.

Prerequisites

A VPS with Ubuntu 22.04 or 24.04 and SSH access — any of Hetzner, DigitalOcean, Vultr, Linode work fine
A domain you control with an A record pointing at the VPS IP
A DeployHQ account (free trial — sign-up link at the end)
A GitHub or GitLab repository
Docker installed locally for testing

Step 1: Provision the VPS

SSH in as root, install Docker, and set up a deploy user:

ssh root@your-vps-ip
curl -fsSL https://get.docker.com | sh

adduser deploy
usermod -aG docker deploy
mkdir -p /home/deploy/n8n
chown deploy:deploy /home/deploy/n8n

From your local machine, copy your SSH key to the deploy user:

ssh-copy-id deploy@your-vps-ip

Confirm passwordless login works:

ssh deploy@your-vps-ip "docker --version"

You should see the installed Docker version. That's the account DeployHQ will use.

Step 2: The n8n Docker Compose stack

In your local repo, create docker-compose.yml:

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5

  n8n:
    image: n8nio/n8n:1.74.0 # pin to a specific tag — don't use :latest in prod
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "127.0.0.1:5678:5678" # localhost only — Nginx will proxy
    environment:
      DB_TYPE: postgresdb
      DB_POSTGRESDB_HOST: postgres
      DB_POSTGRESDB_PORT: 5432
      DB_POSTGRESDB_DATABASE: ${POSTGRES_DB}
      DB_POSTGRESDB_USER: ${POSTGRES_USER}
      DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
      N8N_HOST: ${N8N_HOST}
      N8N_PROTOCOL: https
      N8N_PORT: 5678
      WEBHOOK_URL: https://${N8N_HOST}/
      GENERIC_TIMEZONE: ${TIMEZONE:-Europe/London}
      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
    volumes:
      - n8n_data:/home/node/.n8n
      - ./workflows:/workflows:ro

volumes:
  postgres_data:
  n8n_data:

Four things matter here:

Postgres, not SQLite. SQLite is fine for kicking the tires. For anything you care about, Postgres handles concurrent executions, backups, and growth without complaint.
N8N_ENCRYPTION_KEY is sacred. It encrypts the credentials n8n stores in the database. Change it and every credential breaks — you'll have to re-enter every API key, OAuth token, and SSH credential. Generate it once with openssl rand -hex 32, store it in DeployHQ as a config file, and never lose it.
WEBHOOK_URL must be your public HTTPS URL. n8n bakes this into the URLs it gives webhook senders. If it's wrong, Stripe / GitHub / Slack will hit a dead address.
Port 5678 is bound to 127.0.0.1. Don't expose n8n directly to the internet — put it behind Nginx with TLS. Anyone hitting port 5678 from outside gets nothing.

Create .env.example to commit to the repo (without secrets):

POSTGRES_USER=n8n
POSTGRES_PASSWORD=
POSTGRES_DB=n8n
N8N_HOST=workflows.yourdomain.com
N8N_ENCRYPTION_KEY=
TIMEZONE=Europe/London

The real .env lives in DeployHQ's server config — never in the repo.

Step 3: Put Nginx in front with Let's Encrypt

On the VPS, install Nginx and Certbot:

sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx

Add a server block at /etc/nginx/sites-available/n8n:

server {
    server_name workflows.yourdomain.com;

    client_max_body_size 50M;

    location / {
        proxy_pass http://127.0.0.1:5678;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 3600; # long-running executions
        proxy_send_timeout 3600;
    }

    listen 80;
}

Enable it and run Certbot:

sudo ln -s /etc/nginx/sites-available/n8n /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d workflows.yourdomain.com

The proxy_read_timeout 3600 is important. n8n executions can run for minutes when a workflow waits on an external API — without that, Nginx kills the connection and the run appears to fail.

Step 4: First run

Back on your local machine, commit the repo and push it to GitHub:

git init && git add . && git commit -m "Initial n8n stack"
git remote add origin git@github.com:you/n8n-stack.git
git push -u origin main

For the very first deploy, SSH into the VPS, copy the .env over (DeployHQ will manage it from here on), and bring the stack up manually:

ssh deploy@your-vps-ip
cd /home/deploy/n8n
# (DeployHQ will populate docker-compose.yml on first deploy — for now scp it manually)
docker compose up -d

Visit https://workflows.yourdomain.com, create the admin account, and you're live.

Step 5: Wire up Git-based deploys with DeployHQ

This is the part most n8n tutorials skip. In DeployHQ:

Create a new project and point it at your repo. DeployHQ supports deploying directly from a GitHub repo to your server without you wiring webhooks by hand.
Add the VPS as a server. Username deploy, port 22, deployment path /home/deploy/n8n. Use the SSH key you authorised in Step 1.
Add the .env as a config file. In the server's config-files section, create /home/deploy/n8n/.env and paste the real values (Postgres password, N8N_ENCRYPTION_KEY, N8N_HOST). DeployHQ writes this file before every deploy — your secrets stay out of Git.
Configure the deploy SSH command: bash cd /home/deploy/n8n && \ docker compose pull && \ docker compose up -d && \ docker compose exec -T n8n n8n import:workflow --input=/workflows/ --separateThis pulls any new n8n image version, recreates containers with the new Compose config, and re-imports every workflow JSON from the mounted /workflows directory.
Enable auto-deploy on push to main. Every merge now triggers a deploy.

Push a no-op change to trigger the first run. Watch the DeployHQ log — you'll see the repo transferred, the env file written, the SSH commands executed. The site shouldn't blink: docker compose up -d only recreates containers if something actually changed.

If a deploy ever breaks something, DeployHQ's one-click rollback restores the previous repo state and re-runs the deploy command — a single button, no manual Compose juggling.

Step 6: Workflows as code

This is the payoff for everything above. Instead of the workflow is whatever I last clicked in the UI, your repo becomes the source of truth.

The flow:

Develop locally or on a staging instance. A spare n8n container on your laptop works fine.
Export the workflow. In the n8n UI: open the workflow → menu → Download → save the JSON to workflows/your-workflow-name.json in your repo.
Commit and push. bash git add workflows/your-workflow-name.json git commit -m "Add: Slack-to-Sheets sync workflow" git push
DeployHQ deploys. The deploy command runs n8n import:workflow --input=/workflows/ --separate, which upserts the workflow into the database. Existing workflows with the same ID are updated; new ones are created.

A few practical notes:

One JSON file per workflow. The --separate flag tells n8n's importer to treat each file independently. Easier diffs in PRs.
Credentials are not in the JSON. n8n stores them encrypted in the database, referenced by ID. Set up credentials once in the UI; the workflow JSON just references them. This is why N8N_ENCRYPTION_KEY matters — drop it and the references become unusable.
The UI is now read-only in your head. Anyone making changes in production goes back to staging, exports, commits. Drift kills you otherwise.

The same Compose pattern works for sidecar services — drop a Python agent or a Postgres backup container into the same docker-compose.yml, and DeployHQ deploys all of it together.

Step 7: Upgrade n8n safely

n8n releases often. The temptation is to use n8nio/n8n:latest and let it ride. Don't.

With a pinned tag, upgrading becomes a one-line PR:

- image: n8nio/n8n:1.74.0
+ image: n8nio/n8n:1.78.0

Push, DeployHQ deploys, the new image is pulled, the container recreated. If anything misbehaves, hit rollback and the previous tag is back in seconds. You get a git history of every n8n version that has ever run in production — handy when a workflow stops working and you need to find what changed.

Two upgrade hygiene tips:

Read the changelog before bumping a major. n8n occasionally deprecates nodes or changes execution semantics.
Snapshot Postgres before a major. A docker compose exec postgres pg_dump ... to a file in a backup directory takes seconds and saves hours.

For deploys in general, DeployHQ runs zero downtime deployments by default — when you eventually move to a multi-server setup, the rollout pattern stays the same.

Step 8: Backups

Two things to back up:

The Postgres database. Everything important — workflows, credentials, execution history — lives here.

docker compose exec -T postgres \
  pg_dump -U n8n -d n8n --no-owner --clean \
  > backup-$(date +%F).sql

Drop a small script in your repo at scripts/backup.sh that runs this and uploads the file to S3 (or B2, or any object store). Cron it nightly on the VPS.

The n8n_data volume. Holds binary attachments and custom nodes. Tar it once a week to the same store:

docker run --rm -v n8n_n8n_data:/data -v $PWD:/backup alpine \
  tar czf /backup/n8n-data-$(date +%F).tar.gz -C /data .

The workflows themselves are already in Git, so you don't need to back those up — that's the whole point of the workflows-as-code pattern.

Where to go from here

The pillar above gets you a single-node, production-ready n8n instance with version control and rollback. From here:

Drop a custom AI service next to n8n. The same docker-compose.yml handles a sidecar Python or Node service — expose it at http://agent:8000 and have any n8n workflow hit it as a webhook. Same VPS, same deploy pipeline, no extra infrastructure.
Compare with other self-hosted agent platforms. If n8n's node-based model isn't the right fit, look at alternatives covered on the blog: Paperclip as a self-hosted agent orchestrator, OpenClaw as a self-hosted AI assistant with a Skills plugin system, and Hermes Agent for self-improving agents on a VPS.
Run agents inside CI/CD. For a different shape of the same problem — agents that act on your repository — see how AI agents fit into CI/CD pipelines from GitHub issue to production deploy.
Drive deploys from a terminal agent. If you want Claude Code, Cursor, or Codex to trigger n8n redeploys for you, the DeployHQ CLI exposes a deployment trigger your AI agent can call.

Ready to put n8n on infrastructure you control, with a Git-driven deploy pipeline behind it? Start a free DeployHQ trial and wire your first push-to-deploy n8n stack in under twenty minutes.

Questions? Email us at support@deployhq.com or find us on X at @deployhq.

PR Radar vs GitHub Notifications vs Email: How Developers Actually Track Pull Requests

DeployHQ — Fri, 24 Apr 2026 12:32:48 +0000

If you've managed more than a handful of pull requests across more than one Git platform, you've probably built your own little tracking system out of whatever was free and already installed. A few browser tabs. Email filters. Maybe a Slack integration that someone turned on two years ago and nobody can remember the auth for. It works, until it doesn't — until the PR that needed the please merge today comment gets buried under twelve identical CI notifications, or until the GitLab side of your migration stays invisible for three hours because you only had the GitHub tab open.

This is a comparison of the ways developers actually track PRs today — including PR Radar, the open-source Chrome extension we built because none of the existing options did what we wanted. We'll be honest about where each one wins and where it falls short, and we'll end with the one question that decides which tool you actually need. It's the same format we used for our package manager benchmark and our transactional email API comparison — practical, developer-to-developer, and honest about the gaps.

The five options on the table

Before the comparison, here's the shortlist. We've stayed focused on tools that monitor PR status rather than tools that try to change your PR workflow (so Graphite, Aviator, and Reviewpad are out — they solve a different problem).

Email notifications — the default for GitHub, GitLab, and Bitbucket
GitHub's built-in notification inbox — the bell icon, the /notifications page
Slack integrations — GitHub for Slack, GitLab for Slack, Bitbucket's bot
GitHub-specific extensions — Refined GitHub, Notifier for GitHub
PR Radar — multi-platform dashboard in the browser toolbar

Option 1: Email — the default everyone ignores

Every Git host turns on email notifications by default. Every developer turns most of them off within a month.

The problem with email isn't that it's a bad channel. It's that PR events are high-frequency and low-information per message. A typical active PR generates email for:

The initial open
Every review comment
Every reply in a thread
Every push that re-triggers CI
Every CI status change
Merge or close

Multiply by 8–12 active PRs in a normal week and you've built a firehose. The signal-to-noise ratio collapses because every email looks roughly the same in the preview pane: a PR title, a repo name, and one line of context. You cannot tell at a glance which of your fifteen unread messages is CI failed on the PR that's blocking release and which is approving nit on a docs typo.

Where email wins: Audit trail. If you need a durable record of what happened and when, email is it. Good for compliance, useless for real-time awareness.

Where it fails: Real-time awareness, cross-platform visibility, CI status at a glance.

Option 2: GitHub's notification inbox

GitHub's inbox (the bell icon and /notifications) is better than email for one reason: it's scoped and threaded. A single PR becomes one inbox entry that updates in place instead of twenty separate emails.

It has genuine improvements over the last couple of years — filters, custom views, Participating vs All, per-repo mute. If you live entirely inside GitHub, the inbox is solid.

But it has three hard ceilings.

It's GitHub-only. If your team uses GitLab for infra and GitHub for apps, the inbox solves half your problem. The other half you track… somehow.

It doesn't show CI status inline. The inbox will tell you CI ran on this PR. It will not tell you whether it passed or failed without a click into the PR page. For a tool whose primary job is telling you what needs your attention, burying the pass/fail state behind a click is a miss.

It needs a tab open. The inbox icon lives inside github.com. If you closed the tab during a focus block, you find out about a failed deploy the next time you cmd-T your way back. Browser desktop notifications exist but are disabled by default and, even when on, only fire when a GitHub tab is already open.

Where it wins: Native, reliable, no extra auth, granular filters.

Where it fails: GitHub-only, no CI status in the list view, tab-bound.

Option 3: Slack integrations

Slack is where most engineering teams already are, so routing PR events into Slack seems obvious. And for a few specific use cases — a dedicated #deploys channel, a release-critical PR that the whole team is watching — it's the right tool.

For everyday PR tracking, Slack is a noise amplifier. A rebase-heavy afternoon on a single PR can push twenty notifications into a channel. The team stops reading them. Important signals (production deploy failed) end up in the same channel as unimportant ones (renovate bumped a patch version), with the same visual weight, both probably muted by Thursday.

There's also a coverage asymmetry. GitHub for Slack is mature. GitLab for Slack is functional. Bitbucket's Slack integration exists but feels like an afterthought. If you've got repos on all three, Slack gives you an uneven view of each one.

Where it wins: Team visibility on critical events, shared context during an incident.

Where it fails: Personal PR tracking, signal-to-noise, multi-platform parity.

Option 4: Refined GitHub and Notifier for GitHub

If you've looked for browser extensions for this before, you've hit two classic options.

Refined GitHub is excellent — dozens of polish-level improvements to github.com pages. But it enhances GitHub; it doesn't pull PR status out of GitHub into your toolbar. You still need to open the tab.

Notifier for GitHub does put a badge in your toolbar, but the badge counts unread notifications — not CI state, not review state. A red badge tells you there's something and nothing else. You click through to find out what.

Both are GitHub-only, both assume GitHub is your whole world, and neither addresses the core visibility problem if your work spans platforms.

Where they win: Free, lightweight, GitHub UX polish (Refined GitHub in particular is a staple).

Where they fail: Single-platform, no CI awareness in Notifier, no toolbar summary in Refined.

Option 5: PR Radar

PR Radar is the extension we built after rotating through all four options above and still ending up with a browser window full of tabs. It's a Chrome extension (Firefox and Edge in progress), MIT-licensed, open source, and free — no paid tier, no accounts, no backend at all. Links to the store listing and repo are at the end of the post.

The short version of what it does:

One toolbar popup with every open PR across GitHub, GitLab, and Bitbucket
Badge on the toolbar icon with a live pass / fail / running count for CI
Unresolved comment count per PR, pulled via GraphQL so the number is actually correct
Deployment status inline with clickable environment URLs
Desktop notifications and sound alerts when CI finishes (no tab required — it polls in a service worker)
One-click merge from the dashboard, across all three platforms
Stale PR dimming with a configurable threshold so your attention goes to the active ones
Keyboard shortcuts — j/k to move between PRs, o to open, / to search, ? for the full list

The design goal was minimum cognitive load: glance at the toolbar, see whether anything needs you, go back to what you were doing. If the badge is green, there is nothing to do. If it's red, you know exactly where to look. The same mindset drove our list of developer CLIs that AI agents use well — a good dev tool should compress ten decisions into one glance.

Privacy-wise, PR Radar doesn't send your tokens anywhere. Your personal access tokens sit in the browser's local storage, and the extension makes API calls directly from your browser to each Git platform. There is no PR Radar backend. We don't run analytics. There's no DeployHQ account required — the extension works whether or not you're a DeployHQ customer.

Side-by-side

Dimension	Email	GitHub Inbox	Slack	Refined / Notifier	PR Radar
GitHub	✅	✅	✅	✅	✅
GitLab	✅ (via email)	❌	⚠️ Uneven	❌	✅
Bitbucket	✅ (via email)	❌	⚠️ Uneven	❌	✅
CI status at a glance	❌	❌	⚠️ In channel	❌	✅ Badge + inline
Unresolved comment count	❌	❌	❌	❌	✅
Deploy status in PR list	❌	❌	❌	❌	✅
Works without a tab open	✅	❌	✅	❌	✅ Service worker
Sound / desktop alerts	❌	⚠️ If tab open	✅	❌	✅
Merge from the tool	❌	❌	❌	❌	✅ All 3 platforms
Cost	Free	Free	Free tier + Slack cost	Free	Free + open source
Privacy	Platform stores email	Platform	Slack + platform	Platform	100% local, no backend

The pattern is consistent: each mainstream option handles one or two of these well and treats the rest as out of scope. For developers who only use GitHub and already live in Slack, that's fine. For anyone working across platforms, the gaps add up fast.

The deployment connection

If you're reading this on the DeployHQ blog, there's a fair chance you care specifically about the last mile: the moment between CI passed and change is live. That moment is where PR tracking stops being a productivity nice-to-have and starts being a deployment-quality thing.

Two concrete examples:

Catching a broken deploy before the channel sees it. When CI includes a deploy step (either an automatic deployment from Git or a preview environment triggered by PR), the failure signal travels through the same notification pipes as every other CI event. In email or Slack, a failed deploy looks like every other failed check. In PR Radar, the toolbar flips red the moment the job changes state, with the deploy URL one click away. That's a four-second feedback loop instead of a forty-minute one.

Merging without a tab full of PRs. DeployHQ's one-click rollback and zero-downtime deployments are designed to make shipping cheap. The bottleneck in that flow is usually human: somebody has to decide the PR is ready and hit merge. If that decision point lives in a popup rather than on a PR page buried in a tab group, the whole cycle tightens.

Neither of these is the reason to install a browser extension on its own. But if you already care enough about deployment velocity to be reading this, the PR tracking side of the workflow probably deserves the same attention you've given your CI/CD pipeline and your deploy automation.

Who should pick which

Here's the actual decision tree.

You only use GitHub and you're fine with the inbox. Stay with it, maybe bolt on Refined GitHub for UI polish. No extension needed.

You only use GitHub but the inbox feels lossy. Try Notifier for GitHub for the toolbar badge. If you want CI status specifically and not just unread counts, PR Radar fits even in single-platform setups.

You use GitHub + GitLab or GitHub + Bitbucket. This is the case email, the inbox, and GitHub-specific extensions all fail at. A dedicated multi-platform tool is the only real answer. PR Radar is the one we built; there isn't much direct competition in the free / privacy-first slice of that category.

You're a team lead who wants team-wide visibility into deploys. Slack is still right for that — route release-critical events into a dedicated channel. Just don't try to use the same Slack integration for personal PR tracking; it's the wrong tool for the wrong granularity.

You care about privacy or you work on client repos with sensitive PR titles. PR Radar keeps everything local — tokens in browser storage, API calls direct to platforms, no backend, no analytics. Hosted PR tools generally require you to authorize an OAuth app that sees your PR content. That's a real trade-off worth knowing about, in the same category as picking which MCP servers you grant access to your codebase or how you wire Claude Code into Git.

Try it

PR Radar is free, open source (MIT), and takes about a minute to set up.

Install from the Chrome Web Store (Firefox and Edge builds are in progress on the GitHub releases page)
Star the repo on GitHub if it saves you a tab — it's how we know to keep investing in it
File an issue if a platform quirk breaks your setup; we read all of them

If you're already on DeployHQ, PR Radar closes the visibility gap between PR looks good and change is live without asking you to change anything about your deployment workflow. If you're not, it's still the fastest way we've found to stop tab-hopping between Git hosts.

Questions, platform-specific gotchas, or feature requests? Email us at support@deployhq.com or ping us on Twitter/X. If you'd rather build your own PR dashboard on top of the GraphQL APIs, the source is MIT-licensed and PRs are welcome.

Mailtrap vs SendGrid vs Mailgun: Best Email API for Node.js in 2026

DeployHQ — Wed, 15 Apr 2026 05:07:04 +0000

Mailtrap, SendGrid, and Mailgun are the three most common email APIs that Node.js developers use for transactional or promotional email sending. Each takes a different approach to SDK design, deliverability architecture, and pricing, so the right choice depends on what your team actually needs.

This comparison covers installation, deliverability infrastructure, API workflow capabilities, MCP support, and pricing. All three were tested by integrating their SDKs into a Node.js project and sending emails.

Quick Comparison Overview

All three tools offer straightforward npm installation, but there are differences worth noting in setup complexity, package size, and ecosystem maturity.

Email API	Setup Time	NPM Downloads / Week	SDK Size	TypeScript Support
Mailtrap	5 mins	28K+	90.4 kB	Yes
Mailgun	10-15 mins	360K+	1.3 MB	Yes
SendGrid	10-15 mins	1.65M+	17.4 kB	Yes

Installation and Setup Comparison

When integrating an email service into a deployment pipeline, you want an SDK that configures quickly and does not introduce brittle dependencies.

Mailtrap

Setup time: 5 minutes. Complexity: Easy.

npm install mailtrap

const { MailtrapClient } = require("mailtrap");

const client = new MailtrapClient({
  token: process.env.MAILTRAP_API_TOKEN,
});

const sender = { email: "hello@example.com", name: "Test" };

client.send({
  from: sender,
  to: [{ email: "recipient@example.com" }],
  subject: "Hello from Mailtrap",
  text: "This is a test email.",
});

The Mailtrap package follows a clean API design with intuitive REST principles. It does not require complex DNS setup for initial sandbox testing, so developers can configure their environment variables and fire off a test email right away.

Mailgun

Setup time: 10-15 minutes. Complexity: Medium to complex.

npm install mailgun.js form-data

const Mailgun = require("mailgun.js");
const formData = require("form-data");

const mailgun = new Mailgun(formData);
const mg = mailgun.client({
  username: "api",
  key: process.env.MAILGUN_API_KEY,
});

mg.messages.create("your-domain.com", {
  from: "hello@your-domain.com",
  to: ["recipient@example.com"],
  subject: "Hello from Mailgun",
  text: "This is a test email.",
});

Mailgun requires DNS configuration for domain verification before you can send production emails. The SDK also depends on form-data as a peer dependency, which adds a step. Understanding the email validation features adds initial overhead too.

SendGrid

Setup time: 10-15 minutes. Complexity: Medium.

npm install @sendgrid/mail

const sgMail = require("@sendgrid/mail");
sgMail.setApiKey(process.env.SENDGRID_API_KEY);

sgMail.send({
  to: "recipient@example.com",
  from: "hello@example.com",
  subject: "Hello from SendGrid",
  text: "This is a test email.",
});

The @sendgrid/mail package requires additional configuration for sender authentication and strict API key management. There are multiple ways to structure email payloads, which can be confusing during initial setup if you are working from the docs (they carry a lot of legacy content for different API versions).

Getting started verdict: Mailtrap has the lowest friction for a first send. SendGrid and Mailgun both take 10-15 minutes depending on DNS propagation and how familiar you are with their respective dashboards.

Deliverability and Infrastructure

How each service handles deliverability architecture matters more than raw setup speed once you are sending production emails.

Mailtrap

Mailtrap enforces strict separation between transactional and bulk message streams. This is an architectural decision, not just a UI toggle. Transactional emails (password resets, order confirmations, 2FA codes) run on a dedicated IP pool that is never affected by the reputation of your marketing sends. If a promotional campaign triggers spam complaints, your critical application notifications keep arriving. Mailtrap also offers a 99.99% uptime guarantee with compensation, and detailed analytics that track opens, clicks, and bounces for up to 30 days.

Mailgun

Mailgun focuses heavily on pre-send list quality. It validates email addresses by checking DNS MX records, disposable address databases, and mailbox existence against a 450+ billion email dataset. If you have older contact lists with unknown deliverability, this validation layer can meaningfully reduce your bounce rates before you even send. Mailgun also maintains automated suppression lists that remove hard bounces and spam complainers from future sends, which protects your sending domain over time.

SendGrid

SendGrid operates at a massive scale. Its infrastructure handles enterprise-level volume for both marketing and transactional email, backed by Twilio's network. It also offers native Handlebars template logic stored in the UI and programmatic automation for drip campaigns. For large organizations that need a single platform to handle everything from password resets to weekly newsletters, SendGrid's breadth is hard to match.

Deliverability verdict: Mailgun's pre-send validation against 450+ billion records and automated suppression lists give it the most complete deliverability toolkit. Mailtrap's stream separation is a solid architectural advantage for apps mixing transactional and promotional email. SendGrid's scale and Twilio-backed infrastructure make it the safest bet for high-volume senders.

API Workflow Capabilities

Creating Email Templates

SendGrid lets marketing teams store email templates directly in its UI using Handlebars syntax. Content updates don't require code deployments. Mailtrap and Mailgun offer full API control over templates, but developers need to manage the payload construction themselves.

Event Webhooks

Webhooks let your Node.js server passively listen for delivery events.

Mailtrap delivers full payload data for delivered, opened, and bounced events, with 40 internal retries every five minutes to make sure events are not dropped. Mailgun includes message IDs alongside click and bounce events, which is useful for debugging delivery issues. SendGrid tracks standard events but restricts free-tier users to a single endpoint.

Framework Integration

All three providers offer SDKs that work with Express.js, Next.js, NestJS, Fastify, and Koa. They all support standard async/await patterns and compile-time error checking through TypeScript. Framework compatibility is not a differentiator here.

API workflow verdict: SendGrid's Handlebars-based template system lets users update email content without code deployments, and the broader ecosystem means more community examples and integrations. Mailgun's message-ID tracking is the strongest option for debugging delivery issues. Mailtrap's webhook retry mechanism is worth noting for teams that need guaranteed event delivery.

MCP and Extensibility

All three tools support the Model Context Protocol (MCP) for extending AI capabilities into IDEs and terminal workflows.

Mailtrap provides an official MCP server focused on deliverability, template management, and multi-recipient sending. Mailgun offers an open-source MCP server for sending emails and retrieving analytics. SendGrid relies on community-created MCP servers for campaign management, which may require manual configuration.

Common MCP use cases for email include generating and testing HTML email templates via AI, querying bounce rates and delivery logs, and automating recipient list segmentation.

Extensibility verdict: Mailtrap and Mailgun both offer maintained MCP servers. SendGrid's community approach gives you more flexibility but less out-of-the-box reliability.

Pricing Comparison

Cost is often the deciding factor when scaling a Node.js application's email infrastructure.

Mailtrap

Free tier covers up to 1,000 emails. The Basic plan starts at $15/month for 10,000+ emails. The Business plan runs $85/month for 100,000+ emails. Higher tiers include 24/7 priority support and extended log retention.

Mailgun

Free tier allows 100 emails per day. The Foundation plan is $15/month for 10,000 emails. The Scale plan costs $90/month for 100,000 emails. Pricing gets less competitive at higher volumes, but the validation tools can save money by reducing bounces.

SendGrid

Free tier offers 100 emails per day on a 60-day trial. Essentials starts at $19.95/month for 50,000 emails. Pro costs $89.95/month for 100,000 emails. The pricing structure is complex with many add-ons, but makes sense for high-volume senders who need marketing and transactional email in one platform.

Pricing verdict: At lower volumes all three are competitive. Mailtrap and Mailgun both start at $15/month. SendGrid costs slightly more but includes a larger email allowance on its Essentials plan. The real cost differences emerge at scale and depend on which features you actually use.

Unique Strengths

Mailtrap: Strict separation of transactional and promotional streams. An official TypeScript SDK with zero unnecessary dependencies. A 99.99% uptime SLA with automatic webhook failure detection.

Mailgun: Industry-leading pre-send email validation against a 450+ billion record database. Batch sending to 1,000 recipients per API call using localized recipient variables.

SendGrid: The largest Node.js email ecosystem with 1.65 million weekly npm downloads, backed by Twilio's infrastructure. A unified API that handles both transactional coding and visual marketing campaigns.

Managing Email Credentials in Your Deployment Pipeline

Regardless of which email API you choose, never hardcode API keys in your application code. Inject them through environment variables:

const apiKey = process.env.EMAIL_API_KEY;
if (!apiKey) {
  throw new Error("EMAIL_API_KEY is missing from environment.");
}

This is a common pitfall, especially when switching between staging and production API keys for different email providers. A leaked SendGrid or Mailgun key in a public repo can result in your sending domain getting blacklisted within hours.

If you are deploying a Node.js app that sends email, your deployment tool should handle these secrets safely. In DeployHQ, you can store environment variables as part of your project's build pipeline configuration and inject them at deploy time. This keeps credentials out of your repository while ensuring each environment (staging, production) uses the correct API keys and SMTP settings.

You can also use DeployHQ's configuration file feature to template out .env files during deployment, swapping placeholders for real values stored in the deployment target settings. For teams running separate transactional and marketing email streams (which Mailtrap enforces by default), this means you can store different API tokens per deployment target and avoid accidentally sending test emails through your production pipeline.

Recommendations by Use Case

For developer and product teams shipping transactional email quickly: Mailtrap. The 5-minute setup and strict stream separation let you get to production without surprises. The SDK is small, typed, and does not pull in unnecessary dependencies.

For teams managing older or unverified contact lists: Mailgun. The validation API will reduce your bounce rates before emails ever leave your server. The batch sending feature (up to 1,000 recipients per API call with recipient variables) is also useful for teams sending personalized notifications at moderate scale.

For enterprise marketing teams that need campaigns and transactional email in one platform: SendGrid. The unified ecosystem and Twilio backing handle both use cases, and the 1.65 million weekly npm downloads mean you will find answers to most integration questions on Stack Overflow.

Making Your Choice

There is no wrong choice among these three. Mailtrap, SendGrid, and Mailgun are all actively maintained, well-documented, and capable. All three support async/await, TypeScript, and the major Node.js frameworks. Start with the one that matches your timeline and email types, then evaluate further as your sending volume grows.

The broader trend across all three providers is convergence around MCP support, TypeScript-first SDKs, and better webhook reliability. Where they still diverge is in deliverability architecture and pricing models. For deployment workflows specifically, the most important factor is how cleanly the SDK integrates with your existing environment variable management and CI/CD pipeline.

Frequently Asked Questions

Which email API is best for a Node.js beginner?

Mailtrap has the simplest setup at around 5 minutes, with a single npm package and no peer dependencies. SendGrid is also straightforward but has more configuration options that can be confusing initially. If you just need to get a transactional email working quickly, Mailtrap or SendGrid are your best bets.

Can I switch email providers later without rewriting my application?

Yes, if you abstract your email sending behind a service layer. All three providers use similar patterns (API key authentication, JSON payloads, async sending), so swapping one for another typically means changing the SDK import and adjusting the payload format. Keeping your API keys in environment variables rather than hardcoded makes the switch even simpler.

Do I need a dedicated IP address for transactional email?

Not necessarily. All three providers offer shared IP pools that work well for most applications. Dedicated IPs become relevant when you send high volumes (50,000+ emails per month) and want full control over your sender reputation. Mailtrap and SendGrid offer dedicated IPs on higher-tier plans; Mailgun includes them on the Scale plan and above.

How do I test emails without sending to real recipients?

Mailtrap was originally built as an email testing tool — its sandbox captures emails in a virtual inbox so you can inspect HTML rendering, spam scores, and headers without sending to real addresses. SendGrid and Mailgun both support sandbox modes as well, though the setup requires additional configuration.

What happens if my email API goes down during a deployment?

Your application should handle email API failures gracefully with retry logic and a message queue. None of these providers guarantee 100% uptime (Mailtrap offers 99.99%, the others are similar). Using DeployHQ's zero-downtime deployments ensures your application stays available during deploys, but your email error handling should account for temporary API outages regardless of provider.

Is it safe to use free tiers in production?

Free tiers are fine for low-volume applications, but they come with limitations. Mailtrap's free plan caps at 1,000 emails per month. SendGrid and Mailgun limit you to 100 emails per day. Beyond testing and early-stage projects, you will likely need a paid plan for reliable production sending with higher rate limits and better support.

Ready to streamline your Node.js deployments? Get started with DeployHQ and automate your deployment pipeline today.

Have questions? Reach out at support@deployhq.com or find us on X (@deployhq).

CLIs or MCP for Coding Agents? A Practical Comparison

DeployHQ — Mon, 13 Apr 2026 08:34:15 +0000

This is Part 5 of our series on AI coding assistants for developers. See also: Getting Started with Claude Code, Getting Started with OpenAI Codex CLI, Getting Started with Google Gemini CLI, and Comparing AI CLI Coding Assistants.

Your AI coding agent can read files, run commands, and edit code. But how does it actually connect to the tools and services it needs? In 2026, there are two dominant approaches: command-line interfaces (CLIs) and the Model Context Protocol (MCP). Both give coding agents access to external capabilities — but they work in fundamentally different ways, with real consequences for context quality, reliability, and what your agent can actually do.

This isn't an abstract protocol debate. The interface you choose directly affects how well your agent understands your codebase, how accurately it executes tasks, and how much manual oversight you need to provide. Let's break down what's similar, what's different, and when each approach makes sense.

What We Mean by CLIs and MCPs

Before comparing them, let's be precise about what each term means in the context of coding agents.

CLIs: The Agent Shells Out

When a coding agent uses a CLI tool, it constructs a shell command, executes it in a subprocess, and parses the text output. This is the oldest and most universal integration pattern. Your agent might run git log --oneline -10 to see recent commits, npm test to run your test suite, or curl to hit an API endpoint.

The agent treats the CLI as a black box: it sends a string, gets a string back, and interprets the result using its language understanding.

MCP: A Structured Tool Protocol

The Model Context Protocol is an open standard that defines a JSON-RPC interface between AI models and external tools. Instead of executing arbitrary shell commands, the agent calls named tools with typed parameters and receives structured JSON responses.

An MCP server might expose a search_posts tool that accepts { "query": "deployment", "status": "published" } and returns a typed array of post objects — complete with IDs, titles, dates, and metadata. The agent never needs to parse text output or guess at field meanings.

What They Have in Common

Despite the architectural differences, CLIs and MCP share several characteristics:

Both extend agent capabilities. Whether your agent runs gh pr list or calls an MCP tool named list_pull_requests, the end result is the same: the agent gains access to information and actions beyond its training data. Both approaches turn a conversational AI into something that can interact with real systems.

Both require trust boundaries. A CLI command can delete files; an MCP tool can publish a blog post. In both cases, you need permission models. Claude Code uses approval prompts for shell commands; MCP servers define their own tool permissions. The security concern is identical — you're giving an AI agent the ability to affect real systems.

Both work across all major coding agents. Claude Code, Codex CLI, and Gemini CLI all support both shell execution and MCP servers. (If you're still choosing between these three, our comparison of AI CLI coding assistants covers the differences in detail.) The specific configuration differs, but the concept is universal. If you're building an integration, either approach will work with the tools your team already uses.

Both can be composed. Agents regularly chain multiple CLI commands together (git add . && git commit -m "fix" && git push), and they can chain multiple MCP tool calls in sequence. Complex workflows are possible with either approach.

Where They Differ

Here's where the comparison gets interesting — and where the choice actually matters for your development workflow.

1. Output Structure: Text vs. Typed Data

This is the single biggest difference, and it cascades into nearly every other comparison point.

CLI output is unstructured text. When your agent runs ls -la, it gets a blob of text that it must parse using pattern matching and language understanding. This works remarkably well for simple commands, but it introduces ambiguity. Does that column represent file size or block count? Is that date in DD/MM or MM/DD format? The agent is constantly inferring structure from text.

MCP responses are structured JSON. When your agent calls an MCP tool, it gets back typed fields with known semantics. A post object has a published_at field that's always a Unix timestamp, a title that's always a string, and a categories array that's always a list of IDs. There's no ambiguity to resolve.

This matters most when agents need to make decisions based on the data. An agent parsing git log output might misinterpret a commit message that contains a date-like string. An agent receiving structured commit objects from a Git MCP server won't have that problem.

2. Discoverability: Man Pages vs. Tool Schemas

CLI tools require the agent to know what exists. The agent needs prior knowledge (from training data) about which commands are available, what flags they accept, and what their output looks like. If you have a custom deployment script at ./scripts/deploy.sh, the agent won't know about it unless you tell it — or it happens to find it while exploring your project.

MCP servers declare their capabilities. When an agent connects to an MCP server, it receives a complete list of available tools with descriptions, parameter schemas, and return types. The agent knows exactly what it can do without any prior knowledge. This is especially powerful for domain-specific tools — your custom DeployHQ MCP server doesn't need to be in the model's training data for the agent to use it effectively.

3. Context Efficiency: Tokens Matter

Every piece of information the agent processes consumes tokens from its context window. This has real cost and performance implications.

CLI output is verbose and unstructured. Running docker ps might return 20 lines of formatted table output when the agent only needed the container ID and status. The agent ingests all of it. Multiply this across dozens of commands in a complex task, and you're burning significant context on formatting, headers, and irrelevant columns.

MCP responses are precise. An MCP tool can return exactly the fields the agent needs. If you only want post titles and IDs, the MCP server returns just that — no extra columns, no formatting overhead, no ASCII table borders. For agents working on long, multi-step tasks, this efficiency compounds significantly.

Here's a concrete example. Fetching the last 10 blog posts via CLI might look like:

curl -s https://api.example.com/posts?limit=10 | jq '.[] | {id, title, status}'

That raw JSON response might be 2,000 tokens. The equivalent MCP call returns the same data in a pre-structured format that the agent can consume in roughly 800 tokens — because there's no HTTP headers, no jq processing, and no raw response wrapping.

4. Error Handling: Exit Codes vs. Typed Errors

CLI errors are inconsistent. Some tools use exit codes, some print to stderr, some return error messages on stdout, and some do all three in different combinations. An agent parsing CLI output needs to handle all these patterns — and sometimes the error is actually a warning that doesn't indicate failure.

MCP errors follow a standard format. The protocol defines error responses with codes, messages, and optional details. The agent always knows whether a call succeeded or failed, and can make reliable decisions about retry logic, fallback strategies, or error reporting.

5. Security Model: Sandbox vs. Scoped Permissions

CLI access is broad. When you give an agent shell access, it can potentially run any command your user account can execute. Most coding agents mitigate this with approval prompts, but the underlying capability is unrestricted. A malicious or confused agent could run rm -rf / if the permission check fails.

MCP access is scoped by design. Each MCP server exposes only its specific tools. A blog management MCP server can't access your filesystem; a database MCP server can't run shell commands. The attack surface is naturally smaller. If an MCP server's token has read-only permissions, no amount of clever prompting can make it write data.

This becomes especially important when agents operate with reduced oversight — in automated pipelines, background tasks, or full auto modes.

6. State and Authentication

CLIs inherit the user's environment. Your shell's PATH, environment variables, SSH keys, and authentication tokens are all available to CLI commands. This is convenient — git push just works because your SSH agent is running — but it also means the agent has access to all your credentials.

MCP servers manage their own auth. Each server handles its own authentication, typically through API tokens or service accounts configured when the server starts. This creates clear boundaries: your Google Search Console MCP server has its own service account credentials that are separate from your shell environment.

Comparison Summary

Dimension	CLI	MCP
Output format	Unstructured text	Typed JSON
Discoverability	Requires prior knowledge	Self-describing schemas
Context efficiency	Verbose (high token cost)	Precise (low token cost)
Error handling	Inconsistent across tools	Standardised protocol
Security scope	Broad shell access	Scoped per server
Auth model	Inherits user environment	Isolated per server
Setup complexity	Zero (tools already installed)	Moderate (server config needed)
Universality	Any CLI tool works	Only MCP-enabled services
Ecosystem maturity	Decades of tools	Growing rapidly (2024+)
Offline capability	Full	Depends on server

Which Provides Better Context for Coding Agents?

If you're optimising for agent performance — fewer hallucinations, more accurate tool use, better multi-step reasoning — MCP has a clear structural advantage. Typed data, self-describing schemas, and efficient token usage all contribute to higher-quality agent behaviour.

But that doesn't mean you should replace all CLIs with MCP servers. The practical answer is more nuanced:

Use MCP for domain-specific integrations. If you regularly interact with a specific service — your blog platform, deployment tool, monitoring system, or database — an MCP server gives the agent richer context and more reliable interactions. This is why tools like the DeployHQ MCP server exist: they provide structured access to deployment management that no CLI could match.

Use CLIs for general-purpose operations. File system operations, Git commands, package management, and build tools are universal. They work everywhere, require no setup, and agents handle them well. There's no benefit to wrapping npm install in an MCP server — the CLI works perfectly for this.

Use both together. The most effective setup in 2026 combines both approaches. Your agent uses CLIs for general development tasks and MCP servers for specialised integrations. Claude Code, for example, natively supports both — you can run shell commands and call MCP tools in the same conversation, letting the agent choose the best approach for each step.

What This Means for Your Deployment Workflow

For teams using automated Git deployments, the CLI-vs-MCP choice has practical implications:

Git operations stay CLI-based. Your agent commits, pushes, and manages branches through standard Git commands. This is well-understood, universal, and effective.

Deployment management benefits from MCP. Checking deployment status, triggering rollbacks, or inspecting server configurations are tasks where structured data matters. An MCP server that returns deployment status as { "status": "success", "deployed_at": "2026-04-12T10:30:00Z", "commit": "abc1234" } gives the agent far better context than parsing HTML or text output from a dashboard.

Content operations are ideal for MCP. If your workflow includes managing blog content alongside code — writing deployment guides, updating documentation, managing SEO — an MCP server provides the structured access that makes agents genuinely useful for content workflows.

The pattern we see with teams using DeployHQ is straightforward: Git CLI for code, MCP for everything else that has an API. This gives agents the broadest capabilities with the best context quality.

The Future: Convergence

The boundary between CLIs and MCP is already blurring. Some newer CLI tools output structured JSON by default. MCP servers can wrap existing CLIs to add structure. And coding agents are getting better at parsing unstructured output.

But the trend is clear: as agents take on more complex, multi-step tasks with less human oversight, structured interfaces become more important — not less. The more an agent operates autonomously, the more it benefits from unambiguous, typed data.

If you're building tools for AI agents today, MCP is worth the investment. If you're using agents for development work, configure both CLIs and the MCP servers that match your workflow. The agents that perform best are the ones with the richest, most structured context available.

Frequently Asked Questions

Can I use MCP and CLIs together in the same agent session?

Yes. All major coding agents — Claude Code, Codex CLI, and Gemini CLI — support both shell commands and MCP tool calls in the same session. The agent picks the most appropriate interface for each task automatically. You don't need to choose one or the other.

Do MCP servers replace the need for CLI tools?

No. MCP servers complement CLIs rather than replacing them. CLIs excel at general-purpose operations like file management, Git, and build tools. MCP servers are best for domain-specific services where structured data and scoped permissions matter. The most effective setups use both.

Is MCP harder to set up than just using CLIs?

MCP requires initial configuration — you need to install and configure each server, provide API tokens, and register them with your coding agent. CLIs, by contrast, typically just work with your existing shell environment. However, the setup is usually a one-time task, and the improved agent performance often justifies the upfront effort.

Does using MCP reduce token costs?

Generally yes. MCP responses are structured and concise, which means less token usage per interaction compared to parsing verbose CLI output. For agents running long, multi-step tasks or operating at scale, this efficiency can meaningfully reduce costs — especially with pay-per-token pricing models.

Which approach is more secure?

MCP has a structural security advantage because each server exposes only specific capabilities with scoped permissions. CLI access grants broader system access by default. However, both approaches require proper configuration — MCP servers need secure token management, and CLI access needs appropriate permission prompts. Neither is inherently safe without proper setup.

AI coding agents are most effective when they have the right context, delivered through the right interface. For general development tasks, your terminal's CLI tools remain indispensable. For specialised integrations — content management, deployment automation, monitoring, and APIs — MCP provides the structured context that helps agents work accurately and efficiently.

The best setup isn't one or the other. It's both, configured to match your workflow.

Ready to add structured deployment management to your AI coding workflow? DeployHQ integrates with all major AI coding assistants through both CLI and MCP, giving your agents the context they need to manage deployments confidently. Get started for free.

For questions or feedback, reach out at support@deployhq.com or on Twitter/X.

Deploy from Gitea to Your Server Automatically

DeployHQ — Sat, 11 Apr 2026 07:22:39 +0000

Gitea is quietly becoming the go-to self-hosted Git service. It's lightweight (runs on a Raspberry Pi), easy to install, and gives you full control over your source code without depending on GitHub or GitLab's infrastructure.

But Gitea has one notable gap: no built-in CI/CD. Gitea Actions exists but is still maturing and requires a separate runner instance. For teams that just want to push code and have it deployed to their server, that's a lot of infrastructure for a simple requirement.

Here's how to add fully automated deployments to your Gitea workflow in under 10 minutes, using webhooks and DeployHQ.

Why Gitea Needs an External Deployment Tool

Gitea is intentionally minimal — it's a Git hosting service, not a DevOps platform. That's a feature, not a bug. But it means deployment is left as an exercise for the user.

The common approaches:

Gitea Actions — still in development, requires a dedicated runner, modelled after GitHub Actions but with fewer marketplace actions available
Drone CI / Woodpecker CI — full CI/CD systems that integrate with Gitea, but they're heavy for simple push to deploy workflows
Manual SSH — ssh server 'cd /var/www && git pull' works but breaks the moment you need build commands or multiple servers
Webhook-based deployment — a lightweight service watches for push events and deploys automatically

The webhook approach hits the sweet spot: no CI infrastructure to maintain, no YAML pipelines to write, and it works with any Gitea installation.

The Architecture

flowchart LR
    A[Developer] -->|git push| B[Gitea Instance]
    B -->|webhook POST| C[DeployHQ]
    C -->|git clone via SSH| B
    C -->|build commands| D[Build Server]
    D -->|changed files via SSH/SFTP| E[Production Server]

When you push to Gitea, a webhook fires. DeployHQ receives the notification, clones the latest code from your Gitea repo, runs any build commands, and deploys the changed files to your server. The entire cycle takes seconds.

Step-by-Step Setup

1. Create a DeployHQ Project

When asked for your repository, choose Enter repository URL manually — Gitea isn't in the OAuth provider list since it's self-hosted.

Enter your Gitea repository URL. You have two options:

SSH (recommended):

git@gitea.yourserver.com:username/repo.git

HTTPS with access token:

https://gitea.yourserver.com/username/repo.git

For SSH, DeployHQ will generate an SSH key pair. Copy the public key.

2. Add the SSH Key to Gitea

In your Gitea repository:

Go to Settings → Deploy Keys
Click Add Deploy Key
Paste the DeployHQ public key
Title it DeployHQ
Leave Enable Write Access unchecked (read-only is sufficient)

Alternatively, add the key to your Gitea user account under Settings → SSH/GPG Keys for access to all your repositories.

3. Configure Your Server in DeployHQ

Add your deployment target:

Protocol: SSH/SFTP
Hostname: your-production-server.com
Username: your deploy user
Authentication: SSH key (add DeployHQ's key to the server's authorized_keys)
Deployment Path: /var/www/myapp/ (or your web root)

4. Set Up Build Commands (If Needed)

If your project needs a build step:

cd %path% && npm ci && npm run build

Set the Deployment Subdirectory if you're deploying build output (e.g., dist/ for static sites, build/ for React apps).

5. Configure the Webhook in Gitea

This is where Gitea and DeployHQ connect. In DeployHQ, go to your project and find the Webhook URL (under project settings or on the servers page).

In Gitea:

Go to your repository → Settings → Webhooks
Click Add Webhook → choose Gitea
Target URL: paste the DeployHQ webhook URL
HTTP Method: POST
Content Type: application/json
Trigger On: Push Events
Active: checked
Click Add Webhook

Test it by clicking the Test Delivery button. You should see a 200 response.

6. Push and Deploy

Make a change, commit, and push:

echo "test" >> README.md
git add -A && git commit -m "Test deployment" && git push

Gitea fires the webhook → DeployHQ clones, builds, and deploys. Check the deployment log in DeployHQ to see exactly which files were transferred.

Branch-Based Deployments

Map different branches to different servers for a staging/production workflow:

Branch	Server	Environment
`main`	production-server.com	Production
`develop`	staging-server.com	Staging
`feature/*`	—	Not deployed (review locally)

In DeployHQ, add multiple servers and assign each to a specific branch. Pushing to develop deploys to staging. Merging to main deploys to production.

Handling Self-Signed Certificates

If your Gitea instance uses a self-signed HTTPS certificate, DeployHQ's HTTPS clone will fail certificate verification. Two solutions:

Use SSH instead of HTTPS — SSH cloning doesn't involve TLS certificates
Use a real certificate — Let's Encrypt is free and works with any domain

SSH is the simpler fix and is recommended regardless of certificate situation — it's faster and avoids password/token management.

Gitea Behind a Firewall

If your Gitea instance isn't publicly accessible, DeployHQ can't reach it for webhook delivery or Git cloning. Options:

Open port 22 (SSH) to DeployHQ's IPs — check DeployHQ's documentation for the IP list
Use a reverse SSH tunnel — more complex but avoids opening firewall ports
Mirror to a public Git host — Gitea can mirror to GitHub/GitLab, and DeployHQ clones from there

For most setups, opening SSH access from DeployHQ's IPs is the simplest approach.

Comparison: Gitea Deployment Options

Tool	Setup time	Maintenance	Build support	Multi-server	Cost
DeployHQ	~10 min	None	Yes (npm, Composer, etc.)	Yes	Free for 1 project
Gitea Actions	30-60 min	Runner maintenance	Yes (via Actions)	Custom scripting	Free (self-hosted)
Drone CI	30-60 min	Server + runners	Yes (Docker-based)	Custom config	Free (OSS edition)
Woodpecker CI	30-60 min	Server + agents	Yes (Docker-based)	Custom config	Free
Manual `git pull`	5 min	Error-prone	No	No	Free
Custom webhook script	1-2 hours	Script maintenance	Custom	Custom	Free

DeployHQ wins on setup time and maintenance. Drone/Woodpecker win if you need full CI (testing, multi-stage pipelines, matrix builds). Gitea Actions will likely become the default choice once it matures.

Multi-Repository Deployments

If your project spans multiple Gitea repositories (frontend + backend, or a main app + shared library), create separate DeployHQ projects for each. Each project has its own webhook, build configuration, and server targets.

For monorepos on Gitea, use DeployHQ's deployment subdirectory feature to deploy specific directories from the repository.

Gitea gives you independence from hosted Git providers. Adding DeployHQ gives you automated deployments without the complexity of running a full CI/CD system. Push to Gitea, and your code is live — simple as that.

If you're using GitHub or GitLab alongside Gitea, DeployHQ works with all of them from a single dashboard.

Start deploying from Gitea — set up takes about 10 minutes.

Questions about connecting your Gitea instance? Contact support@deployhq.com or reach us on Twitter/X.

How to Deploy EmDash with DeployHQ

DeployHQ — Thu, 09 Apr 2026 16:28:31 +0000

EmDash is a full-stack TypeScript CMS built on Astro — often described as the spiritual successor to WordPress. It combines a modern admin interface with Astro's rendering performance, Portable Text for structured content, and passkey-first authentication. If you're building a content-driven site with EmDash and need reliable, repeatable deployments from Git, DeployHQ makes the process straightforward.

In this guide, you'll set up an EmDash project for Node.js deployment, connect it to DeployHQ, configure your build pipeline, and deploy to a VPS or cloud server with zero manual file transfers.

What Is EmDash?

EmDash is an open-source CMS that runs as an Astro integration. Unlike traditional CMSs that bolt a content API onto a separate frontend, EmDash ships everything in one project — the admin panel, content editor, authentication, media management, and your frontend templates.

A few things that set EmDash apart:

Astro-native : Your site is an Astro project. EmDash adds the CMS layer as an integration, so you keep full control over routing, components, and rendering.
Portable Text editor : Content is stored as structured JSON (via TipTap), not raw HTML. This makes content reusable across different presentation formats.
Passkey-first auth : No passwords by default. Users authenticate with WebAuthn passkeys, with OAuth and magic links as fallbacks.
Schema-in-database : Content collections are defined in the database, not in code files. This means editors can create new collections without touching the codebase.
Plugin system : Extensible via a definePlugin() API with sandboxed execution on Cloudflare or in-process on Node.js.

EmDash supports multiple deployment targets — Cloudflare Workers, Docker containers, or plain Node.js servers. This guide focuses on Node.js deployment via DeployHQ, which covers VPS hosting, cloud instances, and dedicated servers.

Prerequisites

Before starting, make sure you have:

Node.js 22.12.0 or later installed on both your local machine and your deployment server
A Git repository (GitHub, GitLab, or Bitbucket) containing your EmDash project
A DeployHQ account — you can sign up for a free trial if you don't have one
SSH access to your server with Node.js 22+ installed
A process manager like PM2 or systemd configured on your server

If you haven't created an EmDash project yet, scaffold one with:

npm create emdash@latest my-site
cd my-site
npm install

This generates an Astro project with EmDash pre-configured. The scaffolder lets you choose from blog, marketing, or portfolio templates.

Preparing EmDash for Production

EmDash requires server-side rendering — it's a full-stack CMS, not a static site generator. Your Astro config must use the Node.js adapter in standalone mode.

Configure the Astro Adapter

Open your astro.config.mjs and verify the Node.js adapter is set to standalone:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import emdash from 'emdash';

export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone',
  }),
  integrations: [emdash()],
});

The standalone mode is critical — it produces a self-contained server entry point at ./dist/server/entry.mjs that you can run directly with Node.js. The alternative middleware mode is for platforms like Express where you manage the HTTP server yourself, but standalone is simpler for DeployHQ deployments.

Generate Authentication Secrets

EmDash needs two secrets for production: one for signing session cookies and another for preview URLs. Generate them locally:

npx emdash auth secret

This outputs a cryptographically secure random string. Run it twice — once for EMDASH_AUTH_SECRET and once for EMDASH_PREVIEW_SECRET. Save both values; you'll add them as environment variables in DeployHQ.

Choose Your Database

EmDash supports several database backends. For a Node.js deployment via DeployHQ, the practical options are:

Database	Best For	Configuration
SQLite	Single-server deployments	Set `DATABASE_PATH` to a persistent directory
PostgreSQL	Multi-server or production-critical sites	Set `DATABASE_URL` connection string
libSQL (Turso)	Remote SQLite with replication	Set `LIBSQL_DATABASE_URL` and `LIBSQL_AUTH_TOKEN`

SQLite is the simplest choice for a single VPS — no external database server needed. Just make sure the database file lives on a persistent volume, not in the deployment directory (since DeployHQ replaces files on each deploy).

For SQLite, create a data directory outside your deployment path:

# On your server, create a persistent data directory
mkdir -p /var/data/emdash
chown deploy:deploy /var/data/emdash

Then set the environment variable to point there:

DATABASE_PATH=/var/data/emdash/emdash.db

Add a Start Script

Verify your package.json includes a start script:

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "start": "node ./dist/server/entry.mjs",
    "bootstrap": "emdash init && emdash seed"
  }
}

The build command compiles your Astro project into the dist/ directory. The start command runs the compiled server. DeployHQ will execute build during deployment and your process manager will run start on the server.

Setting Up DeployHQ

With your EmDash project in Git and your server ready, connect everything through DeployHQ.

Create a New Project

Log in to DeployHQ and click New Project
Name it (e.g., EmDash Blog) and select the server region closest to your deployment target
Connect your Git repository — DeployHQ supports GitHub, GitLab, Bitbucket, and self-hosted Git servers

Configure the Server

Add your deployment server under Servers in the project settings:

Click New Server
Choose SSH/SFTP as the protocol
Enter your server hostname, SSH port, and the deploy user credentials
Set the Deployment Path to where your application lives, for example /var/www/emdash
Test the connection to verify DeployHQ can reach your server

Configure the Build Pipeline

This is where DeployHQ handles your Node.js build. Navigate to Build Pipeline in your project settings:

Enable the build pipeline
Select Node.js 22 as the build environment
Add the build commands:

npm ci
npm run build

Using npm ci instead of npm install ensures a clean, reproducible install from your lockfile — important for consistent deployments.

DeployHQ's build pipeline runs these commands in an isolated container, compiles your Astro project, and then deploys only the output files to your server. This means your server doesn't need to run npm install or npm run build — it just receives the compiled application.

Set Environment Variables

Under Environment Variables in your project settings, add:

Variable	Value
`EMDASH_AUTH_SECRET`	Your generated auth secret
`EMDASH_PREVIEW_SECRET`	Your generated preview secret
`DATABASE_PATH`	`/var/data/emdash/emdash.db` (for SQLite)
`HOST`	`0.0.0.0`
`PORT`	`4321` (or your preferred port)

If you're using PostgreSQL instead, replace DATABASE_PATH with DATABASE_URL pointing to your connection string.

DeployHQ encrypts environment variables at rest, so your secrets are protected. These variables are available during the build step and can also be written to a .env file on the server if your application reads from one.

Configure Deployment Exclusions

Not every file needs to reach your server. Under Excluded Files , add:

src/
tests/
node_modules/
.git/
tsconfig.json
astro.config.mjs
README.md

Wait — you actually need node_modules on the server because dist/server/entry.mjs requires runtime dependencies. There are two approaches:

Approach A — Deploy node_modules (simpler): Don't exclude node_modules. DeployHQ transfers the full project including dependencies. This is slower but requires no server-side commands.

Approach B — Install on server (cleaner): Exclude node_modules and add a post-deploy SSH command to install production dependencies:

cd /var/www/emdash && npm ci --omit=dev

Approach B is preferred for larger projects because it only installs production dependencies, keeping the server lean.

Deploying EmDash

First Deployment

Your first deployment needs extra setup because the database doesn't exist yet. After the initial deploy completes:

SSH into your server
Navigate to your deployment directory
Run the bootstrap command to initialise the database:

cd /var/www/emdash
npm run bootstrap

This creates the database schema and optionally seeds sample content. You only need to run this once.

Start the application:

# Using PM2 (recommended)
pm2 start dist/server/entry.mjs --name emdash

# Or using systemd (see next section)

Visit http://your-server:4321/_emdash/admin to complete the setup wizard — set your site title, tagline, and register your admin passkey.

Set Up a Process Manager

For production, use PM2 or systemd to keep EmDash running and restart it on crashes or reboots.

PM2 ecosystem file (ecosystem.config.cjs):

// ecosystem.config.cjs
module.exports = {
  apps: [{
    name: 'emdash',
    script: './dist/server/entry.mjs',
    env: {
      HOST: '0.0.0.0',
      PORT: 4321,
      DATABASE_PATH: '/var/data/emdash/emdash.db',
      NODE_ENV: 'production',
    },
    instances: 1,
    autorestart: true,
    max_memory_restart: '512M',
  }],
};

Note: if you're using SQLite, keep instances: 1. SQLite doesn't handle concurrent writes from multiple processes well. For multi-instance deployments, switch to PostgreSQL.

systemd service (/etc/systemd/system/emdash.service):

[Unit]
Description=EmDash CMS
After=network.target

[Service]
Type=simple
User=deploy
WorkingDirectory=/var/www/emdash
ExecStart=/usr/bin/node dist/server/entry.mjs
Restart=on-failure
Environment=NODE_ENV=production
Environment=HOST=0.0.0.0
Environment=PORT=4321
Environment=DATABASE_PATH=/var/data/emdash/emdash.db
EnvironmentFile=/var/www/emdash/.env

[Install]
WantedBy=multi-user.target

Automate Restarts with Post-Deploy Commands

After each deployment, EmDash needs to restart so it picks up the new code. Add a post-deploy SSH command in DeployHQ under SSH Commands → After Deployment :

cd /var/www/emdash && pm2 restart emdash

Or for systemd:

sudo systemctl restart emdash

This ensures every successful deployment automatically restarts the application without manual intervention.

Subsequent Deployments

After the initial setup, the deployment workflow is:

Push code changes to your Git repository
DeployHQ detects the push (via webhook) and starts a deployment
The build pipeline runs npm ci && npm run build
Compiled files are transferred to your server
The post-deploy command restarts the application

You can also configure DeployHQ to deploy automatically on every push to your main branch, or keep deployments manual and trigger them from the DeployHQ dashboard.

Deployment Architecture

Here's how the pieces fit together:

flowchart LR
    A[Git Push] --> B[DeployHQ]
    B --> C[Build Pipeline<br/>npm ci + astro build]
    C --> D[Transfer Files<br/>via SSH]
    D --> E[VPS / Cloud Server]
    E --> F[PM2 / systemd<br/>Restart]
    F --> G[EmDash Running<br/>port 4321]
    G --> H[Reverse Proxy<br/>nginx / Caddy]
    H --> I[Public Traffic<br/>HTTPS on port 443]

DeployHQ handles steps A through F. You configure the reverse proxy once during initial server setup.

Setting Up a Reverse Proxy

In production, you'll want a reverse proxy in front of EmDash to handle HTTPS, compression, and static asset caching. Here's a minimal nginx configuration:

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:4321;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

If you prefer Caddy, the configuration is even simpler:

your-domain.com {
    reverse_proxy localhost:4321
}

Caddy handles TLS certificates automatically via Let's Encrypt — no manual certificate setup needed.

Troubleshooting

Build Fails with Cannot find module Errors

This usually means dependencies aren't installed correctly. Make sure your package-lock.json is committed to Git. DeployHQ's build pipeline runs npm ci, which requires a lockfile. If you're using pnpm locally, either switch DeployHQ to use pnpm install && pnpm build or add a package-lock.json alongside.

Application Starts but Admin Panel Returns 404

EmDash's admin routes live under /_emdash/admin. Make sure your Astro config has output: 'server' — if it's set to 'static' or 'hybrid', the server-side routes won't work.

Database Errors After Deployment

If you're using SQLite and see database is locked or no such table errors:

Verify DATABASE_PATH points to a directory outside the deployment path (so it persists between deployments)
Make sure the deploy user has write permissions to the database directory
Run npm run bootstrap if the database hasn't been initialised yet

Passkey Authentication Fails

Passkeys require HTTPS. If you're testing over plain HTTP, passkey registration and login will fail. Set up your reverse proxy with TLS first, or use the dev bypass endpoint for initial testing:

https://your-domain.com/_emdash/api/setup/dev-bypass?redirect=/_emdash/admin

Remove this bypass in production by ensuring NODE_ENV=production is set.

Deployment Succeeds but Site Shows Old Content

The post-deploy restart command might not be running. Check the DeployHQ deployment log for SSH command output. Also verify that PM2 or systemd is actually restarting the correct process — run pm2 list or systemctl status emdash on the server to confirm.

Frequently Asked Questions

Can I use DeployHQ's atomic deployments with EmDash?

Yes. DeployHQ's zero downtime deployments work well with EmDash. Each deployment goes into a new directory, and a symlink switches to the new version atomically. Just make sure your DATABASE_PATH and any uploaded media point to a shared directory outside the release path so they persist across deployments.

Does EmDash work with DeployHQ's build pipeline caching?

The build pipeline caches node_modules between deployments, so subsequent builds are faster since npm only installs changed dependencies. Astro's build output isn't cached (it rebuilds each time), but the dependency caching alone can cut build times significantly.

Can I deploy EmDash to shared hosting via FTP?

EmDash requires a long-running Node.js process, which most shared hosting plans don't support. You need a VPS, cloud instance, or container hosting where you can run node dist/server/entry.mjs persistently. DeployHQ supports FTP and SFTP deployment protocols, but the server itself must support Node.js 22+.

How do I handle database migrations during deployment?

EmDash automatically runs migrations when the application starts (for SQLite, libSQL, and PostgreSQL). There's no separate migration step needed in your deployment pipeline. The restart via PM2 or systemd triggers the migration check on boot.

Can multiple team members deploy independently?

Yes. DeployHQ supports team collaboration with role-based permissions. You can restrict who can trigger deployments while giving everyone read access to deployment logs. Combined with DeployHQ's deployment approvals, you can require sign-off before production deployments go live.

Next Steps

You now have a production EmDash deployment powered by Git-based automation through DeployHQ. Every push to your repository triggers a clean build and deployment — no manual file transfers, no SSH-ing into servers to run commands.

From here, you might want to:

Set up deployment notifications to get Slack or email alerts on each deploy
Configure a staging server in DeployHQ to test changes before they hit production
Explore EmDash's plugin system to extend your CMS with custom functionality
Add a build pipeline step for running tests before deployment

Ready to automate your EmDash deployments? Sign up for DeployHQ and connect your repository in minutes.

If you have questions about deploying EmDash or any other framework with DeployHQ, reach out to us at support@deployhq.com or on Twitter/X @deployhq.

OpenClaw Skills: How to Find, Install, and Build Your Own

DeployHQ — Tue, 07 Apr 2026 06:13:28 +0000

If you followed our guide to deploying OpenClaw on a VPS, you've got a self-hosted AI assistant running on infrastructure you control. Out of the box it can chat, browse the web, run terminal commands, and remember context across sessions. Skills are what turn it from a capable chatbot into an automation engine that handles the repetitive parts of your workflow without being asked twice.

This post covers what Skills are, how to find and install them, a tour of the most useful directories, and how to build one from scratch to automate a real task. We'll also walk through troubleshooting common issues and best practices for writing skills that work reliably across environments.

What Are Skills?

A Skill is a directory containing a SKILL.md file — a Markdown document with YAML frontmatter — that teaches OpenClaw a repeatable procedure. When OpenClaw starts, it reads all eligible skills and injects compressed descriptions of them into its system prompt. The agent then knows which skills are available and invokes them automatically when a user request matches.

The simplest skill is just a natural-language runbook:

skills/
└── my-skill/
    └── SKILL.md

More advanced skills can include supporting scripts and configuration, but the SKILL.md is always the entry point. Unlike traditional plugins, which require the host application to define an API surface, Skills work by giving the LLM instructions — the model figures out how to use them in context.

Three locations are checked when loading skills, in precedence order:

<workspace>/skills — workspace-specific, highest priority
~/.openclaw/skills — user-level, shared across all agents on the machine
Built-in bundled skills — shipped with the install, lowest priority

This means you can override a bundled skill just by dropping a folder with the same name into your workspace directory.

flowchart LR
    A["Workspace Skills\n(./skills)"] -->|highest priority| D["OpenClaw\nSystem Prompt"]
    B["User-Level Skills\n(~/.openclaw/skills)"] -->|medium priority| D
    C["Bundled Skills\n(built-in)"] -->|lowest priority| D
    D --> E["Agent Ready\n— skills injected"]

Finding Skills: The ClawHub Registry

ClawHub is the official public skills registry, hosting over 13,700 community-built skills. Use the CLI to search and install:

# Search by keyword
clawhub search "github pull request"

# Install a skill
clawhub install pr-summary

# Update all installed skills
clawhub update --all

By default clawhub install places the skill in ./skills under your current directory. To install globally (visible to all your OpenClaw workspaces):

clawhub install pr-summary --global

The community has also published a curated list — awesome-openclaw-skills — which filters the registry down to 5,400+ vetted skills organised into categories. It's the faster way to browse if you don't already know what you're looking for.

Security note : Treat third-party skills as untrusted code. Read the SKILL.md before enabling a skill, especially if it requires API keys or system binaries. A skill that phones home with your environment variables is possible to write — the registry has moderation, but it's not a guarantee.

A Tour of the Skill Categories

Coding & Development (1,200+ skills) — the largest category by far. Highlights include skills for searching academic papers via OpenAlex, generating hash-chained audit logs for agent actions, and full GitHub workflow automation (open PRs, review diffs, triage issues). If your team uses GitHub-based deployment workflows, skills in this category can trigger deploys directly from a conversation — push a branch, open a PR, and let your CI pipeline handle the rest.

DevOps & Cloud (400+ skills) — Docker container management, process health monitoring, cloud provider CLIs. The agentic-devops skill handles common operations like restarting a crashed container or tailing logs from a service, triggered by a plain-language message. Teams running zero downtime deployments can pair these skills with health-check monitoring to automatically roll back a release if the new container fails readiness probes.

Browser & Automation (335 skills) — web scraping, UI testing, form automation. Useful for monitoring pages that don't expose APIs or automating login-gated workflows. A common pattern is combining a browser skill with a notification skill to alert you when a competitor changes their pricing page or when your own staging environment returns errors after a deploy.

Productivity & Tasks (200+ skills) — Notion CRUD, calendar management, email triage. The better-notion skill gives full create/read/update/delete access to Notion pages and databases from any messaging channel. Other standout skills in this category include time-tracking integrations that log hours against Jira tickets and daily digest generators that summarise activity across multiple project management tools.

Communication (149 skills) — Slack, Discord, Teams, and email integrations. Post to channels, summarise threads, draft replies. The Slack skills are particularly mature — you can configure them to post deployment summaries, standup reminders, or incident alerts directly into the relevant channel without leaving the OpenClaw conversation.

Git & GitHub (170 skills) — beyond the basics, there are skills for commit message generation, changelog drafting, and coordinating multi-repo releases. The release-coordinator skill is worth highlighting: it tags a release, generates a changelog from merged PRs, and posts the release notes to Slack in a single invocation.

Building Your Own Skill

The quickest way to understand Skills is to build one. Here's a practical example: a daily standup note generator that reads your recent git commits and drafts your standup update, so you never have to manually trawl through git log before your morning call.

Step 1 — Create the folder

mkdir -p ~/.openclaw/skills/standup-notes

Step 2 — Write the SKILL.md

nano ~/.openclaw/skills/standup-notes/SKILL.md


---
name: standup-notes
description: Generates a standup update from git commits in the last 24 hours across local repositories
user-invocable: true
metadata: {"openclaw":{"requires":{"bins":["git"]}}}
---

# Standup Notes Generator

When the user asks for standup notes, a standup summary, or "what did I work on yesterday", follow these steps:

## Steps

1. Ask the user which directory their repositories live in, or use `~/repos` as the default if they don't specify.

2. Find all git repositories in that directory:

bash
find ~/repos -maxdepth 2 -name ".git" -type d | sed 's|/.git||'


1. For each repository found, get commits from the last 24 hours authored by the current git user:

2. Collect all results. Ignore repos with no recent commits.

3. Group the commits by repository name and draft a standup update in this format:

4. Keep the language concise and past-tense. Replace jargon-heavy commit messages with plain descriptions where possible.

5. Output the draft in a code block so it's easy to copy.

## Example trigger phrases

- <q>Give me my standup notes</q>
- <q>What did I work on yesterday?</q>
- <q>Draft my standup for today</q>
- <q>Standup summary</q>```



### Step 3 — Test it

Restart the OpenClaw gateway to pick up the new skill:



```shell
openclaw gateway restart

Then send your bot a message:

Give me my standup notes

OpenClaw will run the git commands, collect the output, and return a formatted standup summary. Because the instructions are plain English, you can iterate on the output by replying — make it shorter or use first person — without editing the skill.

Step 4 — Extend it with an automatic post

Once the notes look right, extend the skill to post them directly to your team's Slack channel. Add a section to the SKILL.md:

## Posting to Slack (optional)

If the user asks to "post" or "send" the standup, use the Slack skill (if installed) to post the formatted message to the `#standup` channel. If the Slack skill is not available, output the message and tell the user to copy it manually.

Now the full workflow — generate, review, post — happens in one conversation turn.

Skill SKILL.md Reference

Here are the frontmatter fields you'll use most often:

Field	Type	Description
`name`	string	Unique identifier (used by clawhub)
`description`	string	One-line summary injected into the system prompt
`user-invocable`	boolean	Exposes the skill as a `/skill-name` slash command (default: `true`)
`disable-model-invocation`	boolean	Excludes the skill from model prompts — use for slash-command-only tools
`metadata`	JSON (single line)	Gating, emoji, OS requirements, installer specs

The metadata.openclaw.requires object gates the skill so it only loads when its dependencies are met:

---
name: my-tool
description: Does something with jq and an API key
metadata: {"openclaw":{"requires":{"bins":["jq","curl"],"env":["MY_API_KEY"]}}}
---

If jq isn't on PATH or MY_API_KEY isn't set, OpenClaw skips the skill entirely — it won't show up in the agent's prompt or the UI.

Tips for Writing Effective Skills

Writing a skill that works on your machine is straightforward. Writing one that works reliably across environments and for other users takes a bit more discipline.

Be explicit about prerequisites. Always declare required binaries and environment variables in the metadata.openclaw.requires block. A skill that silently fails because jq isn't installed wastes debugging time. If your skill needs a specific version of a tool, mention it in the instructions — the requires block only checks for presence, not version.

Write instructions for the model, not for humans. The LLM reads your SKILL.md, so phrase steps as direct commands rather than explanations. Run docker ps and parse the output is better than You might want to check which containers are running. Ambiguity in instructions leads to inconsistent behaviour across different models and context windows.

Keep descriptions short and specific. The description field is injected into the system prompt on every conversation. A verbose description eats tokens that could be used for reasoning. Aim for 10-15 words that clearly state what the skill does and when to use it.

Handle failure gracefully. Include instructions for what the agent should do when a command returns an error or produces unexpected output. If the API returns a 401, tell the user their token may have expired prevents the agent from guessing or hallucinating a recovery path.

Test with a clean environment. Before publishing, test your skill on a machine that doesn't have your personal dotfiles, aliases, or globally installed packages. What works in your shell might not work on a fresh Ubuntu server where the only tools available are what's declared in the skill's requirements.

Scope each skill to one task. A skill that tries to do everything — search, filter, format, post, and archive — is harder to maintain and more likely to confuse the model. Break complex workflows into smaller skills that compose together. The standup-notes example above delegates posting to the Slack skill rather than reimplementing Slack integration.

Troubleshooting Common Issues

Skill not appearing in the agent's prompt. The most common cause is a missing or malformed metadata.openclaw.requires block. If the skill requires a binary that isn't installed or an environment variable that isn't set, OpenClaw silently skips it. Run openclaw skills list to see which skills loaded and which were skipped, along with the reason.

Skill loads but doesn't trigger. Check the description field — if it's too vague, the model may not recognise when to invoke it. A description like Useful helper tool gives the LLM almost nothing to work with. Rewrite it to match the kind of phrases users actually say: Generates daily standup notes from recent git commits.

Permission denied errors. Skills that run shell commands inherit the permissions of the OpenClaw process. If you're running OpenClaw as a non-root user (which you should be), commands like systemctl restart nginx will fail. Either configure passwordless sudo for specific commands, or have the skill check permissions first and return a clear message instead of a raw error trace.

Dependency not found on remote servers. A skill that works locally may fail on your VPS because a binary (e.g., jq, gh, docker) isn't installed there. Add all system-level dependencies to your server provisioning script or Dockerfile. Declaring them in the skill's requires.bins block prevents the skill from loading at all, which is better than it loading and then crashing mid-execution.

Conflicting skills. If two skills have overlapping trigger patterns, the model may pick the wrong one. The easiest fix is to make the description fields more distinct. If both skills live in the same precedence tier (e.g., both in ~/.openclaw/skills), the one loaded first alphabetically wins — rename the folder to control order if needed.

Changes not taking effect after editing. OpenClaw reads skills at gateway startup. After editing a SKILL.md, you need to run openclaw gateway restart for the changes to take effect. Hot-reloading is on the roadmap but not yet implemented.

Publishing to ClawHub

When your skill works reliably and you want to share it:

# From the skills directory
clawhub publish ./standup-notes --slug standup-notes --version 1.0.0

Publishing requires a GitHub account at least a week old (abuse prevention). The registry runs automated checks for obviously malicious patterns, but passes it to you to write a clear README and document what environment variables the skill uses and why.

For updates, bump the version and republish:

clawhub publish ./standup-notes --slug standup-notes --version 1.1.0

Keeping Skills in Sync Across Servers with DeployHQ

If you're running OpenClaw on a VPS — or across multiple servers — keeping skills in sync manually is error-prone. The same Git-based approach from the VPS deployment guide applies here: store your custom skills in a repository and let an automated deployment platform push changes to every server automatically.

my-openclaw-config/
├── config.json
└── skills/
    ├── standup-notes/
    │ └── SKILL.md
    └── deploy-digest/
        └── SKILL.md

Set up Git deployment automation so that every push to your main branch triggers a deployment. Add a post-deployment command using build pipelines to copy the skills into place and restart the gateway:

rsync -av skills/ ~/.openclaw/skills/
openclaw gateway restart

Every time you add or update a skill and push to your repository, DeployHQ deploys it to all connected servers — no SSH sessions required. If a skill breaks something, use one-click rollback to revert to the previous working version from the dashboard.

For teams with larger budgets or multiple environments (staging, production), DeployHQ's pricing plans include multiple server targets per project — deploy to staging first, verify the skill works, then promote to production.

The Skills ecosystem is what makes OpenClaw genuinely composable. Start with a few skills from ClawHub, modify them to match your workflow, and build custom ones for the tasks that are specific to your team. The bar to entry is low — if you can write a clear step-by-step process in plain English, you can write a skill.

Sign up for DeployHQ to automate skill deployments across your VPS fleet, or drop us a line at support@deployhq.com if you have questions. Find us on Twitter at @deployhq.

SOC 2 Compliance for Deployment Workflows: What Auditors Look For

DeployHQ — Thu, 02 Apr 2026 17:38:52 +0000

Every tool in your deployment pipeline is now under scrutiny. If your team is pursuing SOC 2 Type II certification — or any compliance framework that governs how software changes reach production — your deployment workflow is no longer just DevOps. It's an audit surface.

This guide breaks down what SOC 2 auditors actually look for in deployment tooling, which controls matter most, and how to configure your pipeline so it passes muster without slowing your team down.

Why Your Deployment Pipeline Is an Audit Target

SOC 2's Trust Service Criteria (TSC) don't mention CI/CD or deployment tools by name. But several controls map directly to how code moves from a developer's machine to production:

CC6.1–CC6.2 (Logical Access): Who can trigger deployments? How are they authenticated?
CC6.3 (Role-Based Access): Can a junior developer deploy to production? Should they be able to?
CC7.1–CC7.2 (System Monitoring): Do you have immutable logs of every deployment — who, what, when, where?
CC8.1 (Change Management): Are production changes reviewed and approved before they go live?
CC9.2 (Vendor Risk): Does your deployment tool vendor meet SOC 2 requirements themselves?

The uncomfortable truth: 68% of SOC 2 qualified opinions (failures) stem from access control weaknesses in CC6.1–CC6.8. Your deployment tool is often the weakest link because it has direct write access to production servers.

The Six Controls Auditors Actually Check

1. Authentication: SSO and MFA

Auditors want to see that access to deployment tooling is consolidated through your identity provider (IdP). This means:

Single Sign-On (SSO) via SAML or OIDC — so access is governed by your IdP (Okta, Azure AD, Google Workspace), not a separate username/password
Multi-Factor Authentication (MFA) enforced at the organisation level, not optional per user
Centralised deprovisioning — when someone leaves the team, their deployment access is revoked automatically through the IdP, not manually by an admin who might forget

Why this matters : If your deployment tool uses standalone credentials, every audit cycle requires manual evidence that offboarded employees had their access revoked. SSO makes this automatic and auditable.

DeployHQ approach : DeployHQ supports team-based access control with configurable permissions per project and server group. For teams requiring SSO, DeployHQ integrates with enterprise identity providers to centralise authentication.

2. Role-Based Access Control (RBAC)

Not everyone who can view a project should be able to deploy to production. Auditors look for:

Separation of duties — developers can deploy to staging; only designated leads or automated pipelines deploy to production
Granular permissions — per-environment, per-server, per-action (view, deploy, configure)
Documented access policies — who has what access and why

flowchart LR
    A[Developer] -->|Can deploy| B[Staging]
    A -.->|Cannot deploy| C[Production]
    D[Team Lead] -->|Can deploy| B
    D -->|Can deploy| C
    E[CI Pipeline] -->|Auto-deploy| B
    E -->|Requires approval| C

DeployHQ approach : DeployHQ's permission system lets you assign roles per project — restricting who can deploy to which server groups. You can set up configurations where staging deploys happen automatically on push while production deploys require manual trigger from authorised users.

3. Immutable Audit Trails

Every deployment must produce a tamper-evident log entry containing:

Who triggered the deployment (authenticated identity, not just admin)
What was deployed (commit SHA, branch, changed files)
When the deployment occurred (timestamp)
Where it was deployed to (server, environment)
Whether it succeeded or failed
What changed — a diff or file manifest of what was actually transferred

These logs must be immutable — no one should be able to delete or modify deployment records after the fact.

DeployHQ approach : DeployHQ maintains a complete deployment history for every project, including the triggering user, commit reference, target servers, transferred files, and build output. This history is accessible via the dashboard and API for audit evidence collection.

4. Change Management and Approval Gates

SOC 2's CC8.1 requires that changes to production are authorised before they take effect. In practice, this means:

Branch protection rules — production deployments only from protected branches (e.g., main) that require pull request reviews
Manual approval gates — someone must explicitly approve production deploys, even if staging is automated
Emergency change procedures — a documented process for hotfixes that bypasses normal review, with after-the-fact review requirements

flowchart TD
    A[Code Push] --> B{Branch?}
    B -->|feature/*| C[Run Tests]
    C --> D[Deploy to Staging]
    B -->|main| E{PR Approved?}
    E -->|Yes| F[Deploy to Production]
    E -->|No| G[Block Deployment]
    F --> H[Log Deployment]
    D --> H

DeployHQ approach : DeployHQ supports conditional deployments — you can configure automatic deployments for staging branches while requiring manual triggers for production. Combined with your Git provider's branch protection, this creates a documented approval chain from code review to production deployment.

5. Environment Separation

Auditors verify that development, staging, and production environments are isolated:

Separate credentials — production server credentials are not shared with staging
Network isolation — staging cannot accidentally write to production databases
Independent configurations — environment variables, API keys, and secrets are managed per environment

DeployHQ approach : DeployHQ's server groups allow you to define separate deployment targets with independent credentials, paths, and configurations for each environment. Each server group has its own deployment history and access controls.

6. Vendor Compliance (Your Tools Are Part of Your Audit)

Under CC9.2, auditors assess the compliance posture of your third-party vendors. For deployment tools, this means:

Does the vendor have their own SOC 2 Type II report?
What data does the vendor access? (Server credentials, source code, environment variables)
How does the vendor store and protect sensitive data?
What happens if the vendor has a security incident?

What to ask your deployment tool vendor :

Do you have a current SOC 2 Type II report?
How are server credentials stored? (At rest encryption? Key management?)
Who at your organisation can access customer deployment configurations?
What's your incident response process?
Do you support data residency requirements?

Beyond SOC 2: Other Compliance Frameworks

SOC 2 isn't the only framework that cares about your deployment pipeline. Here's how the requirements map across frameworks:

Control	SOC 2	ISO 27001	HIPAA	PCI DSS
SSO/MFA	CC6.1–CC6.2	A.9.4.2	§164.312(d)	Req 8.3
RBAC	CC6.3	A.9.2.3	§164.312(a)(1)	Req 7.1
Audit trails	CC7.1–CC7.2	A.12.4.1	§164.312(b)	Req 10.1
Change management	CC8.1	A.14.2.2	§164.312(e)(1)	Req 6.4
Vendor management	CC9.2	A.15.1.1	§164.308(b)(1)	Req 12.8

The good news: if your deployment pipeline meets SOC 2 requirements, you're largely covered for these other frameworks too. The controls are complementary, not conflicting.

A Practical Compliance Checklist for Your Deployment Pipeline

Use this checklist to assess your current deployment workflow against SOC 2 requirements:

Authentication & Access

[] SSO enabled for all deployment tool access
[] MFA enforced at the organisation level (not optional)
[] Automated deprovisioning when team members leave
[] No shared credentials or service accounts used for interactive access

Permissions & Roles

[] Production deployment restricted to authorised roles
[] Staging and production use separate permission sets
[] Access reviews conducted quarterly (documented)
[] Principle of least privilege applied to all roles

Audit & Logging

[] Every deployment logged with user identity, commit, timestamp, and target
[] Deployment logs are immutable (cannot be deleted or modified)
[] Logs retained for the audit period (typically 12 months)
[] Failed deployments logged with error details

Change Management

[] Production deployments require prior approval (PR review or manual gate)
[] Emergency change process documented and followed
[] Rollback procedures documented and tested
[] All deployments traceable to a specific code change (commit SHA)

Environment Isolation

[] Separate credentials for each environment
[] Production configuration not accessible from staging
[] Environment-specific secrets management
[] Network segmentation between environments

Vendor Management

[] Deployment tool vendor has current SOC 2 Type II report
[] Vendor security review conducted annually
[] Data processing agreement (DPA) in place
[] Incident notification procedures agreed upon

Getting Started

If your team is beginning the SOC 2 journey, here's a practical order of operations:

Audit your current state — map out who has access to what, how deployments are triggered, and where the gaps are
Fix authentication first — SSO and MFA have the highest ROI because they address the most common audit failures
Enable audit logging — make sure every deployment is logged with enough detail for an auditor to reconstruct the event
Implement approval gates — start with production, then extend to other sensitive environments
Document everything — auditors care as much about documented policies as they do about technical controls

The goal isn't to make deployments slower. It's to make them provably secure — so that when an auditor asks who deployed this change and why?, you have a clear, automatic answer.

If you're evaluating how DeployHQ fits into your compliance workflow, you can explore our features or start a free trial to test the deployment controls against your audit requirements.

For questions about enterprise features including SSO, contact us at support@deployhq.com or reach out on X (@deployhq).

SQLite vs PostgreSQL vs MySQL: Choosing the Right Database

DeployHQ — Thu, 02 Apr 2026 06:31:57 +0000

Every application stores data somewhere, and for most web applications, that means a relational database. But which one? SQLite, PostgreSQL, and MySQL serve very different use cases despite sharing SQL as their query language.

This guide compares all three with honest benchmarks, real configuration differences, and practical advice for choosing the right database for your project and deployment workflow.

Quick Comparison

Feature	SQLite	PostgreSQL	MySQL
Type	Embedded (serverless)	Client-server	Client-server
Storage	Single file	Server with data directory	Server with data directory
Setup	Zero configuration	Install + configure	Install + configure
Concurrent writes	Limited (file-level locking)	Excellent (MVCC)	Good (row-level locking with InnoDB)
Max database size	~281 TB (theoretical)	Unlimited	Unlimited
JSON support	Basic (json functions)	Advanced (JSONB with indexing)	JSON type with functions
Full-text search	FTS5 extension	Built-in (ts_vector)	Built-in (InnoDB)
Replication	None	Streaming + logical	Primary-replica, Group Replication
Best for	Small apps, development, embedded	Complex apps, data integrity	Web apps, read-heavy workloads

SQLite: The Embedded Database

SQLite isn't a server — it's a library that reads and writes directly to a single file on disk. There's no installation, no configuration, no separate process. Your application links against the SQLite library and talks directly to the database file.

Strengths

Zero configuration : No server to install, configure, or maintain
Single file : The entire database is one .sqlite or .db file — easy to copy, backup, and move
Self-contained : No external dependencies
Reliable : Used in every smartphone (iOS and Android), every web browser, and most operating systems
Fast for reads : No network overhead since it's in-process

Limitations

Concurrent writes : Only one writer at a time (readers can run concurrently). WAL mode improves this but doesn't match PostgreSQL
No user management : No built-in authentication or access control
Limited ALTER TABLE : Can't drop or rename columns in older versions (improved in 3.35.0+)
No network access : The database file must be on the same machine as the application

When to Use SQLite

Development and prototyping : Get started without setting up a database server
Small-to-medium applications : Blogs, internal tools, single-server apps
Mobile and desktop apps : The database ships with the application
Embedded systems : IoT devices, configuration stores
Testing : In-memory SQLite databases run tests fast with no cleanup

Configuration Example

import sqlite3

conn = sqlite3.connect('app.db')
cursor = conn.cursor()

cursor.execute('''
    CREATE TABLE IF NOT EXISTS users (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        email TEXT UNIQUE NOT NULL,
        name TEXT NOT NULL,
        created_at TEXT DEFAULT CURRENT_TIMESTAMP
    )
''')

PostgreSQL: The Enterprise Database

PostgreSQL is the most feature-rich open-source database. It emphasizes data integrity, SQL standards compliance, and extensibility. It handles complex queries, large datasets, and high-concurrency workloads.

Strengths

Data integrity : Strict type checking, ACID compliance, foreign key enforcement
Advanced features : JSONB, full-text search, window functions, CTEs, materialized views
Extensibility : Custom types, functions, operators, and extensions (PostGIS, pgvector, TimescaleDB)
Concurrency : MVCC (Multi-Version Concurrency Control) handles many concurrent writers efficiently
SQL standards : Most standards-compliant open-source database

Limitations

Setup complexity : Requires installation, configuration, and ongoing maintenance
Resource usage : Higher memory and CPU usage than SQLite or MySQL for simple workloads
Shared hosting : Less commonly available on basic hosting plans
Learning curve : Advanced features require deeper PostgreSQL knowledge

When to Use PostgreSQL

Complex applications : Apps with complex queries, relationships, and data integrity requirements
Analytics and reporting : Window functions, CTEs, and materialized views
Geospatial data : PostGIS extension is the gold standard
JSON-heavy workloads : JSONB with GIN indexes is powerful
High-concurrency writes : MVCC handles many concurrent writers well

Configuration Example

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    email TEXT UNIQUE NOT NULL,
    name TEXT NOT NULL,
    metadata JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- GIN index on JSONB for fast queries
CREATE INDEX idx_users_metadata ON users USING GIN (metadata);

-- Full-text search
ALTER TABLE users ADD COLUMN search_vector tsvector;
CREATE INDEX idx_users_search ON users USING GIN (search_vector);

MySQL: The Web Database

MySQL (and its fork MariaDB) has been the default database for web applications since the early 2000s. It's the M in LAMP (Linux, Apache, MySQL, PHP) and remains the most widely deployed database in web hosting.

Strengths

Ubiquity : Available on virtually every hosting platform, including shared hosting
Read performance : Optimized for read-heavy web workloads
Replication : Mature primary-replica replication for scaling reads
Ecosystem : Massive community, extensive tooling, widespread ORM support
WordPress : Powers 40%+ of the web through WordPress

Limitations

Less strict by default : Older versions silently truncate data or accept invalid dates — modern versions (8.0+) improved this significantly
Fewer advanced features : No native JSONB indexing (until recently), limited window function support in older versions
Storage engine complexity : InnoDB vs MyISAM distinction can confuse beginners

When to Use MySQL

Web applications : Traditional LAMP/LEMP stack applications
WordPress sites : WordPress requires MySQL (or MariaDB)
Read-heavy workloads : MySQL excels at simple SELECT queries at scale
Shared hosting : When it's the only database available
Legacy systems : Migrating away from MySQL is often more work than staying

Configuration Example

CREATE TABLE users (
    id INT AUTO_INCREMENT PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    name VARCHAR(255) NOT NULL,
    metadata JSON,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

SQL Syntax Differences

Despite all three using SQL, there are syntax differences that matter when writing queries or switching databases:

Feature	SQLite	PostgreSQL	MySQL
Auto-increment	`AUTOINCREMENT`	`SERIAL` or `GENERATED ALWAYS`	`AUTO_INCREMENT`
Boolean type	Integer (0/1)	Native `BOOLEAN`	`TINYINT(1)`
String concat	`\	\	`
Current time	`CURRENT_TIMESTAMP`	`NOW()`	`NOW()`
UPSERT	`INSERT OR REPLACE`	`ON CONFLICT DO UPDATE`	`ON DUPLICATE KEY UPDATE`
LIMIT with offset	`LIMIT n OFFSET m`	`LIMIT n OFFSET m`	`LIMIT m, n` or `LIMIT n OFFSET m`

ORMs like Prisma, SQLAlchemy, Django ORM, and ActiveRecord abstract these differences, letting you switch databases without rewriting queries (in theory — in practice, database-specific features often creep in).

How Database Choice Affects Deployment

Your database choice has direct implications for how you deploy and manage your application:

SQLite Deployments

SQLite's database file lives alongside your application code. This creates a unique deployment challenge:

your-app/
├── app.js
├── database.sqlite ← This is your database
├── package.json
└── ...

When deploying with DeployHQ, you need to be careful:

Don't overwrite the database on every deploy. Exclude *.sqlite and *.db from your deployment or use DeployHQ's excluded files feature
Backups are simple : Just copy the file
No connection string needed : The file path is the connection

PostgreSQL and MySQL Deployments

These databases run as separate servers. Your application connects via a connection string:

# PostgreSQL
DATABASE_URL=postgres://user:password@db-server:5432/myapp

# MySQL
DATABASE_URL=mysql://user:password@db-server:3306/myapp

Store these connection strings as environment variables — never hardcode them. DeployHQ's build pipelines can inject these securely during deployment.

Migrations

All three databases need schema migrations as your application evolves. Run migrations as part of your deployment:

# In your DeployHQ build command
npm ci
npm run build
npm run db:migrate

Whether you push from GitHub or GitLab, DeployHQ runs your build commands (including migrations) before transferring files to the server.

For agencies managing client databases, PostgreSQL and MySQL offer user-level access control — you can give each client's app its own database user with restricted permissions.

FAQ

Can I start with SQLite and migrate to PostgreSQL later? Yes, if you use an ORM. The ORM abstracts SQL differences, making the switch mostly painless. Test thoroughly — there are always edge cases with date handling, string comparison, and JSON support.

Which database is fastest? It depends on the workload. SQLite is fastest for single-user read-heavy applications (no network overhead). PostgreSQL handles concurrent writes best. MySQL is optimized for simple read queries at scale. Benchmark your actual workload rather than relying on generic benchmarks.

Do I need PostgreSQL for a simple blog? No. SQLite or MySQL are fine for simple applications. Choose PostgreSQL when you need advanced features like JSONB, full-text search, or complex analytical queries.

Is MariaDB the same as MySQL? MariaDB forked from MySQL in 2009 and is largely compatible. Most MySQL applications work with MariaDB without changes. MariaDB has diverged more in recent versions, adding unique features, but the core SQL and wire protocol remain compatible.

Which database does DeployHQ recommend?DeployHQ works with any database — it deploys your application code, and your application connects to whatever database you've set up. For new projects, PostgreSQL is the most versatile choice.

There's no universally best database — only the right one for your project. SQLite for simplicity, PostgreSQL for power, MySQL for ubiquity. Pick the one that matches your needs and deploy it confidently.

Try DeployHQ free — deploy your application with any database and manage connection strings securely. See pricing for team plans.

Questions? Reach out at support@deployhq.com or @deployhq.

Nginx vs Apache vs Caddy: Choosing the Right Web Server

DeployHQ — Wed, 01 Apr 2026 13:45:21 +0000

Every web application needs a web server to handle HTTP requests. Whether you're serving a static site, reverse-proxying to a Node.js backend, or hosting a WordPress installation, your choice of web server affects performance, security, and how much time you spend on configuration.

This guide compares the three most popular options — Nginx, Apache, and Caddy — with real configuration examples and practical advice for choosing the right one.

Quick Comparison

Feature	Nginx	Apache	Caddy
Architecture	Event-driven, async	Process/thread per connection	Event-driven, Go goroutines
Performance	Excellent for static files and high concurrency	Good, but higher memory under load	Very good, slightly behind Nginx
Configuration	`nginx.conf` (custom syntax)	`httpd.conf` + `.htaccess` (XML-like)	`Caddyfile` (minimal, human-readable)
HTTPS	Manual (Let's Encrypt + certbot)	Manual (Let's Encrypt + certbot)	Automatic (built-in ACME)
Per-directory config	No (centralized only)	Yes (`.htaccess`)	No (centralized only)
Module system	Compiled modules	Dynamic modules (loaded at runtime)	Plugins (Go modules)
Market share	~34% (most popular)	~29% (declining)	~1% (growing fast)
Best for	High-traffic sites, reverse proxy	Shared hosting, PHP apps	Small-to-medium sites, automatic HTTPS

Nginx

Nginx (pronounced engine-x) was created in 2004 to solve the C10K problem — handling 10,000 concurrent connections. Its event-driven architecture uses a small number of worker processes, each handling thousands of connections asynchronously.

Strengths

Performance : Serves static files extremely fast with minimal memory
Reverse proxy : The de facto standard for proxying to application servers (Node.js, Python, Ruby, Go)
Load balancing : Built-in upstream balancing with multiple algorithms
Low memory footprint : Handles thousands of connections with minimal RAM

Configuration Example

Serving a static site:

server {
    listen 80;
    server_name example.com;
    root /var/www/example.com;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    # Cache static assets
    location ~* \.(css|js|png|jpg|gif|ico)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

Reverse proxy to a Node.js app:

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

When to Use Nginx

High-traffic websites needing maximum performance
Reverse proxying to application servers
VPS deployments where you control the server
Load balancing across multiple backends
Serving static assets alongside dynamic applications

Apache

Apache HTTP Server has been running the web since 1995. It introduced the concept of dynamically loadable modules and per-directory configuration via .htaccess files — features that made shared hosting possible.

Strengths

.htaccess support : Per-directory configuration without server restart
Module ecosystem : Hundreds of modules (mod_php, mod_rewrite, mod_security)
Shared hosting : Still the default on most shared hosting providers
Documentation : Decades of community knowledge and tutorials

Configuration Example

Serving a static site:

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /var/www/example.com

    <Directory /var/www/example.com>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    # Cache static assets
    <FilesMatch "\.(css|js|png|jpg|gif|ico)$">
        ExpiresActive On
        ExpiresDefault "access plus 30 days"
        Header set Cache-Control "public, immutable"
    </FilesMatch>
</VirtualHost>

Reverse proxy to a Node.js app:

<VirtualHost *:80>
    ServerName api.example.com

    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:3000/
    ProxyPassReverse / http://127.0.0.1:3000/

    RequestHeader set X-Forwarded-Proto "http"
</VirtualHost>

When to Use Apache

Shared hosting environments where Nginx isn't available
PHP applications that benefit from mod_php
Projects that need .htaccess for per-directory configuration
Legacy applications with existing Apache configurations

Caddy

Caddy (v2, released 2020) is the newest of the three. Its headline feature is automatic HTTPS — it obtains and renews TLS certificates from Let's Encrypt without any configuration. The Caddyfile syntax is designed to be as simple as possible.

Strengths

Automatic HTTPS : Certificates obtained and renewed automatically via ACME
Simple configuration : A basic site takes 2-3 lines
Modern defaults : HTTP/2, HTTP/3, TLS 1.3 out of the box
Single binary : No dependencies, easy to install and update

Configuration Example

Serving a static site (with automatic HTTPS):

example.com {
    root * /var/www/example.com
    file_server
}

That's it. Caddy automatically obtains a TLS certificate, redirects HTTP to HTTPS, and serves the files.

Reverse proxy to a Node.js app:

api.example.com {
    reverse_proxy 127.0.0.1:3000
}

When to Use Caddy

Small-to-medium sites where simplicity matters
Projects where automatic HTTPS saves significant ops time
Development environments needing local HTTPS
APIs and microservices with straightforward routing

Performance Comparison

For static file serving and high concurrency, Nginx leads. Apache's process-per-connection model uses more memory under load. Caddy performs well but sits between the two.

Metric	Nginx	Apache	Caddy
Static file throughput	Highest	Moderate	High
Memory per 10K connections	~2.5 MB	~10+ MB (prefork)	~5 MB
Concurrent connection handling	Excellent	Good (with worker MPM)	Very good
TLS handshake overhead	Low (with tuning)	Low (with tuning)	Low (default)

In practice, the web server is rarely the bottleneck. Your application code, database queries, and network latency have far more impact on user-perceived performance.

How Web Server Choice Affects Deployment

When you deploy with DeployHQ, your code is transferred to the server — the web server configuration ships alongside it. Understanding the relationship between your application code and web server is important:

Configuration files deploy with your code. Your nginx.conf, .htaccess, or Caddyfile lives in your Git repository and deploys automatically when you push from GitHub or GitLab
Server restart may be needed. After deploying Nginx or Apache config changes, you often need a reload command. DeployHQ's build pipelines can run post-deploy commands to handle this
The web server is already running. DeployHQ deploys your application code. The web server itself is installed and managed separately on your server

For teams managing multiple client sites, having a consistent web server across projects simplifies operations. Agencies often standardize on Nginx for its performance and flexibility.

FAQ

Can I run Nginx and Apache together? Yes. A common pattern is Nginx as a reverse proxy in front of Apache. Nginx handles static files and SSL termination; Apache handles PHP via mod_php. This gives you the best of both worlds.

Is Caddy production-ready? Yes. Caddy v2 is stable and used in production by many companies. Its automatic certificate management actually reduces ops risk compared to manual cert renewal.

Which is best for WordPress? Apache is the traditional choice because WordPress relies on .htaccess for URL rewriting. However, Nginx works well with WordPress using a try_files directive, and many high-traffic WordPress sites run on Nginx.

Do I need a web server if I'm using Node.js/Express? Node.js can serve HTTP directly, but a reverse proxy (typically Nginx or Caddy) in front of it provides SSL termination, static file serving, load balancing, and protection against slow clients. For production, always use a reverse proxy.

Which web server is easiest to learn? Caddy, by a wide margin. A functional Caddyfile can be 3 lines. Nginx has a moderate learning curve. Apache's configuration is the most verbose but extremely well-documented.

Your web server is the front door to your application. Whether you choose Nginx for performance, Apache for compatibility, or Caddy for simplicity, the important thing is that your deployment pipeline handles the configuration reliably.

Try DeployHQ free — deploy your web server configuration alongside your application code on every push. See pricing for team plans.

Questions? Reach out at support@deployhq.com or @deployhq.

Understanding CORS: The Developer's Guide

DeployHQ — Mon, 30 Mar 2026 06:22:41 +0000

If you've ever opened your browser console and seen a red error message about CORS policy, you're not alone. CORS errors are one of the most common and most frustrating issues in web development — and they almost always surface after deployment, not during local development.

This guide explains what CORS is, why browsers enforce it, and how to fix it in every major framework.

What Is CORS?

CORS stands for Cross-Origin Resource Sharing. It's a security mechanism built into web browsers that controls which websites can make requests to your server.

When your frontend at https://app.example.com tries to fetch data from https://api.example.com, the browser checks whether the API server explicitly allows requests from app.example.com. If the server doesn't say yes, the browser blocks the response.

This isn't your server rejecting the request — the server processes it normally. The browser blocks the response from reaching your JavaScript code.

The Same-Origin Policy

CORS is built on top of the Same-Origin Policy, which defines what counts as the same origin:

https://app.example.com:443/page
  ↑ ↑ ↑
protocol domain port

Two URLs have the same origin only if all three parts match:

URL A	URL B	Same origin?	Why
`https://app.example.com`	`https://app.example.com/api`	Yes	Same protocol, domain, port
`https://app.example.com`	`http://app.example.com`	No	Different protocol
`https://app.example.com`	`https://api.example.com`	No	Different subdomain
`https://app.example.com`	`https://app.example.com:8080`	No	Different port

When origins don't match, the browser requires CORS headers from the server before it will allow the response through.

Simple Requests vs Preflight Requests

Not all cross-origin requests are handled the same way.

Simple Requests

The browser sends the request directly if it meets all of these conditions:

Method is GET, HEAD, or POST
Only standard headers (Accept, Content-Type, Content-Language)
Content-Type is application/x-www-form-urlencoded, multipart/form-data, or text/plain

For simple requests, the browser sends the request and checks the CORS headers in the response.

Preflight Requests

For anything else — PUT, DELETE, PATCH, custom headers, Content-Type: application/json — the browser sends a preflight OPTIONS request first:

Browser → OPTIONS /api/users (preflight)
Server → 200 OK + CORS headers
Browser → PUT /api/users (actual request)
Server → 200 OK + data


sequenceDiagram
    Browser->>Server: OPTIONS /api/users (preflight)
    Server-->>Browser: 200 OK + CORS headers
    Browser->>Server: PUT /api/users (actual request)
    Server-->>Browser: 200 OK + response data

The preflight asks: Am I allowed to make this type of request? If the server responds with the right headers, the browser proceeds with the actual request.

CORS Headers Explained

Access-Control-Allow-Origin

The most important header. It tells the browser which origins can access the response:

Access-Control-Allow-Origin: https://app.example.com

Or allow any origin (use with caution):

Access-Control-Allow-Origin: *

Important : You can only specify one origin or *. You cannot list multiple origins. To support multiple origins, your server must check the request's Origin header and echo it back if it's in your allowed list.

Access-Control-Allow-Methods

Which HTTP methods are permitted:

Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH

Access-Control-Allow-Headers

Which request headers are permitted:

Access-Control-Allow-Headers: Content-Type, Authorization, X-Requested-With

Access-Control-Allow-Credentials

Whether the browser should send cookies and authentication:

Access-Control-Allow-Credentials: true

Critical : When this is true, Access-Control-Allow-Origin cannot be *. You must specify the exact origin.

Access-Control-Max-Age

How long (in seconds) the browser caches the preflight response:

Access-Control-Max-Age: 86400

This avoids sending a preflight OPTIONS request before every actual request. Set it to 24 hours (86400) for production.

Access-Control-Expose-Headers

Which response headers JavaScript can read (beyond the basic set):

Access-Control-Expose-Headers: X-Total-Count, X-Request-Id

How to Enable CORS

Node.js / Express

The cors middleware is the standard approach:

npm install cors


const express = require('express');
const cors = require('cors');
const app = express();

// Allow specific origin
app.use(cors({
  origin: 'https://app.example.com',
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  credentials: true,
  maxAge: 86400
}));

// Or allow multiple origins
app.use(cors({
  origin: ['https://app.example.com', 'https://staging.example.com'],
  credentials: true
}));

Python / Django

Install django-cors-headers:

pip install django-cors-headers


# settings.py
INSTALLED_APPS = [
    'corsheaders',
    # ...
]

MIDDLEWARE = [
    'corsheaders.middleware.CorsMiddleware', # Must be before CommonMiddleware
    'django.middleware.common.CommonMiddleware',
    # ...
]

CORS_ALLOWED_ORIGINS = [
    'https://app.example.com',
    'https://staging.example.com',
]

CORS_ALLOW_CREDENTIALS = True

Python / Flask

pip install flask-cors


from flask import Flask
from flask_cors import CORS

app = Flask( __name__ )
CORS(app, origins=['https://app.example.com'], supports_credentials=True)

Ruby on Rails

Add rack-cors to your Gemfile:

gem 'rack-cors'


# config/initializers/cors.rb
Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins 'https://app.example.com'
    resource '*',
      headers: :any,
      methods: [:get, :post, :put, :patch, :delete, :options],
      credentials: true,
      max_age: 86400
  end
end

PHP (Manual Headers)

<?php
$allowed_origin = 'https://app.example.com';

if (isset($_SERVER['HTTP_ORIGIN']) && $_SERVER['HTTP_ORIGIN'] === $allowed_origin) {
    header("Access-Control-Allow-Origin: $allowed_origin");
    header("Access-Control-Allow-Methods: GET, POST, PUT, DELETE");
    header("Access-Control-Allow-Headers: Content-Type, Authorization");
    header("Access-Control-Allow-Credentials: true");
    header("Access-Control-Max-Age: 86400");
}

// Handle preflight
if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    http_response_code(204);
    exit;
}

Nginx (Server-Level)

server {
    listen 80;
    server_name api.example.com;

    location / {
        # Handle preflight
        if ($request_method = 'OPTIONS') {
            add_header 'Access-Control-Allow-Origin' 'https://app.example.com';
            add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE';
            add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization';
            add_header 'Access-Control-Max-Age' 86400;
            add_header 'Content-Length' 0;
            return 204;
        }

        add_header 'Access-Control-Allow-Origin' 'https://app.example.com';
        add_header 'Access-Control-Allow-Credentials' 'true';

        proxy_pass http://127.0.0.1:3000;
    }
}

Common CORS Errors and Fixes

No 'Access-Control-Allow-Origin' header is present

The server isn't sending CORS headers. Add the appropriate middleware or headers for your framework.

The value of the 'Access-Control-Allow-Origin' header must not be the wildcard '*' when the request's credentials mode is 'include'

You're using credentials: true (or withCredentials: true in fetch/axios) but the server is responding with Access-Control-Allow-Origin: *. You must specify the exact origin:

// Wrong
res.header('Access-Control-Allow-Origin', '*');

// Correct
res.header('Access-Control-Allow-Origin', 'https://app.example.com');

Preflight Failures (OPTIONS Returns 405 or 404)

Your server doesn't handle OPTIONS requests. Some frameworks need explicit configuration:

// Express: cors middleware handles this automatically
// Without cors middleware, add:
app.options('*', (req, res) => {
  res.header('Access-Control-Allow-Origin', 'https://app.example.com');
  res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
  res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
  res.sendStatus(204);
});

CORS Works Locally but Fails in Production

This is the most common deployment issue. Locally, your frontend and API often run on localhost (same origin or with a dev proxy). In production, they're on different subdomains.

Check that your production server's CORS configuration includes your production frontend URL, not just localhost:3000.

CORS in Development vs Production

Development

During development, CORS issues are often avoided with a dev proxy. Most frontend tools support this:

Vite:

// vite.config.js
export default {
  server: {
    proxy: {
      '/api': 'http://localhost:3000'
    }
  }
}

The proxy makes API requests appear same-origin during development, bypassing CORS entirely.

Production

In production, you have several options:

Same origin : Serve frontend and API from the same domain (no CORS needed)
CORS headers : Configure your API to accept requests from your frontend's origin
Reverse proxy : Use Nginx to serve both frontend and API from the same domain

Option 3 is often the simplest. If your frontend and API are both deployed via DeployHQ, an Nginx reverse proxy can route /api/* to your backend and everything else to your frontend — making them the same origin.

How This Relates to Deployment

CORS issues are deployment issues. They rarely appear during development (because of dev proxies or same-origin localhost) and almost always appear when code hits staging or production.

When you deploy with DeployHQ from GitHub or GitLab:

Your CORS configuration deploys with your code — it's part of your application's middleware or server config
Environment-specific origins can be managed via DeployHQ's build pipelines — set CORS_ORIGIN as a build variable that differs between staging and production
Nginx config deploys alongside your app — your reverse proxy rules are version-controlled and auto-deployed

For agencies deploying frontend and backend separately for clients, getting CORS right from the start saves hours of debugging post-deploy.

Security Considerations

Never use * in production for APIs that handle authentication. It allows any website to make requests to your API
Validate origins : Don't blindly echo the Origin header. Maintain a whitelist of allowed origins
Don't confuse CORS with authentication. CORS controls which websites can talk to your API. It doesn't replace API authentication (tokens, sessions)
Credentials require specific origins. If you use cookies or auth headers, you must specify exact origins — * is not allowed

FAQ

Does CORS apply to server-to-server requests? No. CORS is a browser-only mechanism. Server-to-server HTTP requests (curl, fetch from Node.js, Python requests) are not subject to CORS restrictions.

Can I disable CORS in the browser? Yes, for testing — but never in production. Chrome can be launched with --disable-web-security, but this is dangerous and only for debugging.

Does CORS protect my API from abuse? No. CORS is enforced by browsers, not servers. Anyone can use curl or Postman to make requests directly. Use authentication and rate limiting to protect your API.

Why does my API work in Postman but not in the browser? Postman doesn't enforce CORS — it's not a browser. The same request that fails in the browser due to CORS will succeed in Postman because there's no same-origin policy to enforce.

Should I handle CORS in my application or in Nginx? Either works. Application-level CORS (Express cors middleware, Django cors-headers) is more flexible and portable. Nginx-level CORS is useful when you can't modify the application. Don't configure CORS in both places — the headers can conflict.

CORS is confusing at first, but it's simple once you understand the flow: the browser asks the server for permission, the server responds with headers, and the browser enforces the result. Get your headers right, test on staging before production, and you'll never see that red console error again.

Try DeployHQ free — deploy your frontend and backend together with consistent CORS configuration. See pricing for team plans.

Questions? Reach out at support@deployhq.com or @deployhq.

How To Deploy from Windows Using WSL2, Docker, and DeployHQ

DeployHQ — Wed, 25 Mar 2026 11:51:46 +0000

Most deployment tutorials assume you are already on Linux or macOS. But if your daily machine runs Windows, you have likely hit the gap between it works on my laptop and it works on the server. WSL2 closes that gap — it gives you a real Linux kernel inside Windows, so your local Docker containers behave exactly like they will in production.

This guide covers the full workflow: setting up WSL2 and Docker on Windows, structuring a project for deployment, and using DeployHQ to ship changes from your Git repository to a remote Linux server — automatically.

flowchart LR
    Dev["Windows + WSL2"] -->|git push| Git["GitHub / GitLab"]
    Git -->|webhook| DHQ["DeployHQ"]
    DHQ -->|SSH + files| Prod["Linux VPS"]
    DHQ -->|SSH commands| Prod

Why WSL2 for deployment workflows

If you develop on Windows and deploy to Linux servers, you have probably run into at least one of these problems:

Path differences : Windows uses backslashes and drive letters (C:\Users\), Linux uses forward slashes (/home/). Build scripts and Docker volumes break when they cross this boundary.
Shell incompatibilities : Bash scripts that run perfectly on the server fail in PowerShell or CMD.
File permission mismatches : Linux file permissions (chmod, chown) do not exist on NTFS, causing issues with Docker volume mounts and deployment scripts.
Line ending conflicts : Windows uses \r\n, Linux uses \n. A single wrong line ending can break a shell script or a Dockerfile.

WSL2 solves all of these by running a real Linux distribution (not an emulation layer) inside a lightweight VM managed by Windows. Docker Desktop integrates with WSL2 directly, so containers run on a real Linux kernel — identical to your production server.

Step 1 — Install WSL2 and Ubuntu

Open PowerShell as Administrator and run:

wsl --install -d Ubuntu-24.04

This installs WSL2 (the default since Windows 10 version 2004) and Ubuntu 24.04 LTS. Restart your machine when prompted.

After reboot, Ubuntu will launch and ask you to create a Linux username and password. These are separate from your Windows credentials.

Verify the installation:

wsl --list --verbose

You should see Ubuntu-24.04 running on WSL version 2.

Already have WSL1? Upgrade with wsl --set-version Ubuntu-24.04 2. WSL1 does not support Docker.

Step 2 — Install Docker Desktop with the WSL2 backend

Download and install Docker Desktop for Windows. During setup, ensure Use WSL 2 based engine is checked (it is the default).

After installation, open Docker Desktop and go to Settings > Resources > WSL Integration. Enable integration with your Ubuntu-24.04 distribution.

Verify from your WSL2 terminal:

docker --version
docker compose version

Both commands should work without sudo. Docker Desktop handles the daemon — you do not need to install Docker Engine inside WSL2 separately.

Performance tip

Store your project files inside the WSL2 filesystem (~/projects/), not on the Windows mount (/mnt/c/). File operations on /mnt/c/ are significantly slower due to the cross-filesystem translation layer.

mkdir -p ~/projects
cd ~/projects

Step 3 — Set up Git and SSH keys

Your WSL2 environment has its own Git configuration and SSH keys, separate from Windows. Configure them inside WSL2:

git config --global user.name "Your Name"
git config --global user.email "your@email.com"

Generate an SSH key for connecting to both your Git provider and your deployment server:

ssh-keygen -t ed25519 -C "your@email.com"
cat ~/.ssh/id_ed25519.pub

Add this public key to:

Your GitHub or GitLab account
Your remote server's ~/.ssh/authorized_keys file

Step 4 — Create a sample Docker Compose project

Let's create a minimal project to demonstrate the full workflow. This example uses Nginx serving a static site, but the pattern works for any Docker-based application.

cd ~/projects
mkdir my-app && cd my-app
git init

Create docker-compose.yml:

services:
  web:
    image: nginx:alpine
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - ./public:/usr/share/nginx/html:ro
    restart: unless-stopped

Create a simple page:

mkdir public
echo '<h1>Deployed with DeployHQ from WSL2</h1>' > public/index.html

Create .gitignore:

.env

Test locally:

docker compose up -d
curl http://localhost:8080

You should see your HTML. Stop it with docker compose down.

Commit and push:

git add .
git commit -m "Initial project setup"
git remote add origin git@github.com:your-username/my-app.git
git push -u origin main

Step 5 — Set up DeployHQ

DeployHQ connects your Git repository to your server and deploys changes automatically — or on your approval. Here is how to wire it up:

Create a new project in DeployHQ and connect your Git repository. DeployHQ supports GitHub, GitLab, Bitbucket, and any self-hosted Git server.
Add your server as a deployment target. Choose SSH/SFTP and enter your server's IP, SSH user, and deployment path (e.g., /home/deploy/my-app).
Configure SSH commands to manage Docker containers on each deployment:

Timing	Command	Purpose
Before upload	`cd /home/deploy/my-app && docker compose down`	Stop running containers
After upload	`cd /home/deploy/my-app && docker compose up -d --remove-orphans`	Start updated containers

DeployHQ runs SSH commands from the user's $HOME by default, so the cd prefix is required. See the deployment command examples for more patterns.

Enable automatic deployments (optional): Under project settings, enable auto-deploy so every push to main triggers a deployment without manual approval.

Step 6 — Deploy and verify

From your WSL2 terminal, make a change and push:

echo '<h1>Updated from WSL2!</h1><p>Deployed automatically.</p>' > public/index.html
git add .
git commit -m "Update landing page"
git push

DeployHQ will:

Detect the new commit via webhook
Upload changed files to your server
Run the SSH commands to restart Docker containers

Check the deployment log in your DeployHQ dashboard to confirm success.

Step 7 — Edit with VS Code from Windows

One of the best parts of WSL2: you can edit files inside the Linux filesystem using VS Code on Windows. Install the WSL extension, then from your WSL2 terminal:

cd ~/projects/my-app
code .

VS Code opens on Windows but operates inside WSL2 — file access, terminal, Git, and Docker commands all run natively in Linux. Your workflow becomes:

Edit in VS Code on Windows
Test with docker compose up in the integrated WSL2 terminal
Commit and push from the same terminal
DeployHQ deploys to your Linux server automatically

No context switching. No path translation issues. No works on my machine surprises.

Going further: real-world project patterns

Environment-specific configuration

Use separate Compose files for local development and production:

# Local development (with hot reload, debug ports)
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

# Production uses the base file only
# DeployHQ deploys docker-compose.yml to the server

Using DeployHQ build pipelines

If your project needs a build step (compiling assets, running tests), DeployHQ build pipelines can run commands before deploying. For example:

npm install && npm run build

This runs on DeployHQ's build servers, so your production server only receives the compiled output.

Docker image builds with DeployHQ

For projects that build custom Docker images, DeployHQ's Docker build feature can build and push images to Docker Hub, GitHub Container Registry, or other registries — then deploy a docker compose pull && docker compose up -d on your server.

Rolling back

If a deployment breaks something, open DeployHQ's deployment history and click Redeploy this version on the last working deployment. The SSH commands will restart the containers with the previous configuration.

Troubleshooting

Docker commands not available in WSL2 Open Docker Desktop > Settings > Resources > WSL Integration and ensure your Ubuntu distro is enabled. Then restart your WSL2 terminal.

Slow file access in Docker volumes You are likely mounting from /mnt/c/. Move your project to ~/projects/ inside WSL2. The performance difference is substantial.

SSH key not working with DeployHQ or your serverMake sure you generated the key inside WSL2 (not Windows). Check permissions: chmod 600 ~/.ssh/id_ed25519. Test with ssh -T git@github.com or ssh deploy@your-server-ip.

Line ending issues in Git Configure Git inside WSL2 to keep Linux line endings:

git config --global core.autocrlf input

This ensures files stay with \n endings even if you occasionally edit them from Windows.

DeployHQ deployment times out Docker image pulls can be slow on the first deployment. Increase the SSH command timeout in DeployHQ's server settings, or pre-pull images on the server with docker compose pull before the first deploy.

Frequently asked questions

Can I use WSL2 without Docker Desktop?

Yes. You can install Docker Engine directly inside your WSL2 Ubuntu distribution using the official Linux install steps. This avoids Docker Desktop entirely and is free for all team sizes. The trade-off is that you lose the GUI, automatic updates, and the seamless cross-distro integration that Docker Desktop provides. The deployment workflow with DeployHQ works exactly the same either way — it only cares about what you push to Git.

Does DeployHQ run on Windows or inside WSL2?

Neither. DeployHQ is a hosted service — it runs in the cloud. You interact with it through your browser or via Git webhooks. Your local environment (Windows, WSL2, macOS, Linux) only matters for writing code and pushing commits. DeployHQ connects to your Git provider and your remote server independently.

Is WSL2 fast enough for Docker development?

For containers and builds, WSL2 performs at near-native Linux speed. The one bottleneck is cross-filesystem access — reading files from /mnt/c/ (the Windows drive) inside a container is significantly slower than reading from the native Linux filesystem (~/). Keep your projects inside WSL2's home directory and performance will not be an issue.

Can I deploy to multiple servers from the same project?

Yes. DeployHQ supports multiple servers per project. You can deploy the same Git repository to a staging server and a production server with different SSH commands for each. For example, staging could auto-deploy on every push, while production requires manual approval.

What if my team uses a mix of Windows, macOS, and Linux?

That is one of the main advantages of this workflow. Docker Compose files are cross-platform, Git is cross-platform, and DeployHQ does not care what OS pushed the commit. Team members on macOS or Linux skip the WSL2 step and use Docker natively — the rest of the workflow (Git push → DeployHQ → server) is identical.

Do I need WSL2 if I only deploy static sites or PHP apps (no Docker)?

No. WSL2 and Docker are optional. DeployHQ can deploy any Git repository to any server over SSH/SFTP — no containers needed. WSL2 becomes valuable when your production stack uses Docker, because it lets you run the same containers locally on Windows that you will run on the server. For static sites or traditional PHP deployments, DeployHQ works directly without any local Docker setup.

Ready to bridge your Windows development environment with production Linux servers? Sign up for DeployHQ and connect your first project in minutes.

For questions or help, reach out to support@deployhq.com or find us on X (@deployhq).