DEV Community: DeployHQ

How to Host a Node.js Service on DeployHQ Managed VPS

DeployHQ — Mon, 03 Aug 2026 09:35:49 +0000

This guide walks through hosting a Node.js service (Express, Fastify, NestJS, Koa — whichever framework you're running) on a DeployHQ Managed VPS. End to end: provision the VPS, install Node, configure Nginx as a reverse proxy, run the service under systemd, set up the DeployHQ build pipeline, and ship the first deploy.

If you're considering DeployHQ Managed VPS against PaaS alternatives — Render, Railway, Fly.io — our Heroku alternatives roundup covers the trade-offs. This post is the implementation path for the DeployHQ Managed VPS choice. If you'd rather run your service in a container than directly on the box, Dockerize a Node.js app walks the Docker path instead.

What you'll build

A DeployHQ Managed VPS running Ubuntu with Node.js installed
Your Node service running under systemd with auto-restart
Nginx reverse-proxying HTTP/HTTPS to the Node process
DeployHQ build pipeline running npm ci and any compile step
Custom domain over HTTPS
Atomic zero-downtime deploys with one-click rollback

Expected time: 30-45 minutes for a fresh project.

Prerequisites

A Node.js service in a Git repository (Express, Fastify, NestJS, Koa, or any HTTP framework)
A DeployHQ account with beta features enabled ( Settings > Beta Features )
A database if your app needs one (install Postgres on the VPS or use an external managed DB)
Local Node.js to verify the build before pushing

If you don't have a DeployHQ account yet, you can start a free trial — the trial includes one Managed VPS at the smallest size at no charge.

Step 1: Provision the Managed VPS

In your DeployHQ project, click New Server :

Enter a name (your reference only)
Select Managed VPS under the Hosting section
Pick a region and server size. For a small Express API: 1 vCPU / 1 GB RAM is workable; bump to 2 GB if you're running a database alongside.
SSH keys: blank for auto-generated, or paste your own
Set the deployment path to /var/www/node-app (or your preferred root)
Click Create Server

Provisioning takes about a minute. The server appears in Settings > Hosted Resources with IP, region, size, and sync status.

Step 2: Install Node.js and supporting packages

SSH in. Install Node via NodeSource (gives you a current LTS release with apt-managed updates):

sudo apt update
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs nginx

Adjust the major version (22.x, 20.x) to match what your project requires. Verify:

node --version
npm --version

Set up the deployment directory:

sudo mkdir -p /var/www/node-app
sudo chown -R $USER:www-data /var/www/node-app

Step 3: Configure Nginx as a reverse proxy

Create /etc/nginx/sites-available/node-app:

upstream node_app {
    server 127.0.0.1:3000;
    keepalive 32;
}

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

    location / {
        proxy_pass http://node_app;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $http_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_redirect off;
        proxy_read_timeout 60s;
    }

    client_max_body_size 10M;
}

The Upgrade and Connection headers enable WebSocket support if your Node service uses them (Socket.IO, ws, NestJS websockets).

Enable the site:

sudo ln -s /etc/nginx/sites-available/node-app /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Step 4: Environment variables

Create /var/www/node-app/shared/.env with your environment variables (database URL, API keys, secrets, port):

NODE_ENV=production
PORT=3000
DATABASE_URL=postgres://user:pass@localhost:5432/dbname
JWT_SECRET=...

This file lives in shared/ so it persists across deploys. The systemd service reads from it.

Step 5: Create a systemd service

Create /etc/systemd/system/node-app.service:

[Unit]
Description=Node.js application
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/node-app/current
EnvironmentFile=/var/www/node-app/shared/.env
ExecStart=/usr/bin/node dist/server.js
Restart=on-failure
RestartSec=5
StandardOutput=append:/var/log/node-app.log
StandardError=append:/var/log/node-app.log
SyslogIdentifier=node-app

[Install]
WantedBy=multi-user.target

(Adjust the ExecStart path to wherever your built entry point lives — dist/server.js for TypeScript projects, src/index.js for plain JS, etc.)

Enable but don't start yet — wait for the first deploy:

sudo systemctl daemon-reload
sudo systemctl enable node-app

Step 6: Configure the build pipeline in DeployHQ

In project build settings, add the build pipeline commands. These run on DeployHQ's build infrastructure before transferring to the VPS:

npm ci --omit=dev
npm run build

(Skip npm run build if your project is plain JavaScript with no compile step. For TypeScript projects, npm run build typically runs tsc or your bundler.)

For deeper Node build configuration — dependency caching, pnpm and Bun, pinning the Node version — see using Node.js and npm with the DeployHQ build pipeline.

In the environment variables UI, set any vars the build step needs at build time (not runtime — runtime vars live in shared/.env).

In deployment hooks , add a post-deploy hook to restart the service:

sudo systemctl restart node-app

For the sudo to work without a password prompt, configure passwordless sudo for systemctl restart node-app via /etc/sudoers.d/:

# /etc/sudoers.d/deployhq-node-app
deployhq ALL=(ALL) NOPASSWD: /bin/systemctl restart node-app

(Replace deployhq with whichever user DeployHQ deploys as.)

In server settings, ensure shared files includes .env and shared folders includes any persistent directories your app uses (uploaded files, generated artifacts, etc.). Enable atomic transfers — see one-click rollback for what the atomic mechanism enables.

Step 7: First deploy

Push to the repository or trigger a manual deploy. DeployHQ:

Clones the repo at HEAD
Runs the build pipeline (npm ci + your build step)
Transfers the built artifact to the VPS via SSH
Symlinks current/ to the new release
Runs the post-deploy hook (systemctl restart node-app)
Old releases kept for rollback

Verify the service is up:

sudo systemctl status node-app
sudo journalctl -u node-app -n 50 # check recent logs

Then curl http://localhost:3000/ (or your service's health endpoint) to confirm the Node process responds before exposing externally.

Common first-deploy failures:

Module not found — npm ci --omit=dev skips devDependencies. If your runtime code imports something from devDeps, install it as a regular dep.
Build artifacts missing — confirm npm run build actually produces the entry point at the path systemd's ExecStart references.
Permission denied on systemd restart — the sudoers line for passwordless restart isn't set up. Either set it up, or run the restart as root via a different mechanism.

Step 8: Custom domain + HTTPS

Point your domain at the server's IP via A record. Then either:

Cloudflare : add domain, set DNS to Proxied, HTTPS terminated at the edge. Free and zero config on the VPS.

Let's Encrypt directly on the VPS :

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d example.com -d www.example.com

Certbot configures Nginx for HTTPS and auto-renews.

Common gotchas

Service crashes on startup and systemd restarts it forever. systemd's Restart=on-failure keeps restarting failing services indefinitely. If your app crashes due to a config error, you'll see this in journalctl -u node-app. Fix the underlying error, then systemctl restart node-app once the fix is in place.

Environment variables don't load. systemd doesn't expand shell variables. If your .env file uses ${VAR} syntax, systemd won't expand them — use literal values. Or use a tool like dotenv-cli inside ExecStart to load and run.

WebSockets disconnect after 60 seconds. Nginx's default proxy_read_timeout is 60s. For long-lived WebSocket connections, increase it: proxy_read_timeout 86400s;.

TypeScript compile fails on the build worker due to memory. TypeScript can be memory-hungry on large codebases. Either run tsc --incremental to use a build cache, or compile to swc or esbuild which use much less memory.

Process running as root because of missing User directive. systemd defaults to running as root if User= isn't set. Add User=www-data to the unit file and make sure the deployment user owns the current/ and shared/ directories.

No graceful shutdown handling. A Node service should listen for SIGTERM and finish in-flight requests before exiting. Without that, systemctl restart kills mid-request connections. Add a SIGTERM handler in your server startup that closes the HTTP server, waits for in-flight requests, then exits.

What you've shipped

You now have:

A Node.js service running on a DeployHQ Managed VPS
Nginx + systemd + the runtime on a real Ubuntu box you can SSH into
Atomic zero-downtime deploys with one-click rollback via the DeployHQ dashboard
HTTPS via Cloudflare or Let's Encrypt

For the broader picture, the hosting hub catalogs all five DeployHQ hosting types. The Managed VPS pillar guide covers the provisioning surface and includes comparisons against DigitalOcean App Platform, Linode, and Render. For the category-wide reference, best software deployment tools in 2026 puts DeployHQ alongside the rest, and your universal deployment and hosting platform is the cross-cluster bridge.

What's next

If you also have a static frontend — a React/Vue SPA, a Next.js static export, a documentation site — pair this Managed VPS Node backend with DeployHQ Static Hosting in the same DeployHQ project. The frontend rides on Cloudflare's edge, the API runs on the VPS, one project ships both with one billing relationship.

For Express-specific patterns (Express deployment guide) or Fastify, NestJS, or Koa specifics, the canonical guides cover the framework-specific build steps. For broader background on where Node deployment sits among hosting alternatives, the DeployHQ ecosystem catalog is the deeper reference.

Start a free trial if you don't have an account yet. For the full Managed VPS product reference, see the Managed VPS support library.

Questions or feedback on Node.js + Managed VPS? Email support@deployhq.com or follow @deployhq on X for product updates.

How to Host a Laravel App on DeployHQ Managed VPS

DeployHQ — Thu, 30 Jul 2026 09:33:27 +0000

This guide is narrowly scoped: provision a DeployHQ Managed VPS from inside DeployHQ and host a Laravel application on it end to end. Server provisioning, runtime setup (PHP-FPM + Nginx), queue workers and scheduler, the DeployHQ deployment pipeline, custom domain, first deploy.

If you're looking for the broader Laravel deployment reference — comparisons against Forge / Deployer / Laravel Cloud, decision frameworks, the 15-point pre-deploy checklist — see our comprehensive Laravel deployment guide. This post is the Managed-VPS-specific path through that landscape. If your app deploys to a shared or third-party SFTP/SSH host rather than a Managed VPS, the general Laravel deployment tutorial walks that path instead.

What you'll build

By the end:

A DeployHQ Managed VPS provisioned and running Ubuntu
PHP-FPM, Nginx, and Composer installed and configured for Laravel
Laravel queue worker running under Supervisor (Redis or database-backed queue)
Laravel scheduler wired in via cron
DeployHQ build pipeline running Composer install + asset compilation
Custom domain serving over HTTPS via Cloudflare or Let's Encrypt
Atomic zero-downtime deploys with one-click rollback

Expected time: 30-45 minutes for a fresh project.

Prerequisites

A Laravel project in a Git repository (GitHub, GitLab, Bitbucket)
A DeployHQ account with beta features enabled ( Settings > Beta Features )
A database for Laravel to use — either install MySQL/PostgreSQL on the same VPS (covered below) or point at a managed database service
Local Composer + PHP for running migrations and verifying the build before pushing

If you don't have a DeployHQ account yet, you can start a free trial — the trial includes one Managed VPS at the smallest size at no charge.

Step 1: Provision the Managed VPS

In your DeployHQ project, click New Server :

Enter a name for the server (your reference only)
Select Managed VPS from the protocol picker under the Hosting section
Choose a region (data center location) and a server size. For a small-to-medium Laravel app: 1 vCPU / 2 GB RAM is a reasonable starting point. Adjust based on traffic and queue throughput.
SSH keys: leave blank to let DeployHQ generate one automatically, or paste your own private key if you'd rather use yours
Set the deployment path to /var/www/laravel-app (or your preferred root). DeployHQ writes deploys to this path.
Click Create Server

Provisioning takes about a minute. Once the status flips to active, the server appears in Settings > Hosted Resources with its IP address, region, size, and sync status.

Step 2: Install the runtime stack

SSH into the server using the key DeployHQ generated. The server runs Ubuntu, so the standard apt commands work:

sudo apt update
sudo apt install -y nginx php8.3-fpm php8.3-cli php8.3-mbstring \
  php8.3-xml php8.3-curl php8.3-zip php8.3-mysql php8.3-bcmath \
  php8.3-intl composer redis-server supervisor mysql-server

(Adjust the PHP version to match what your Laravel project requires. Laravel 11 and Laravel 12 typically need PHP 8.2 or 8.3.)

Enable services to start on boot:

sudo systemctl enable nginx php8.3-fpm redis-server mysql supervisor
sudo systemctl start nginx php8.3-fpm redis-server mysql supervisor

Create the Laravel app directory if it doesn't exist:

sudo mkdir -p /var/www/laravel-app
sudo chown -R $USER:www-data /var/www/laravel-app

Step 3: Configure Nginx for Laravel

Create /etc/nginx/sites-available/laravel-app:

server {
    listen 80;
    server_name example.com www.example.com;
    root /var/www/laravel-app/current/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

The current symlink in the root path is important — DeployHQ's zero-downtime deployments use atomic symlink switching, and Nginx serves whatever current/public/ points to at any given moment.

Enable the site:

sudo ln -s /etc/nginx/sites-available/laravel-app /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Step 4: Set up Laravel database + environment

Create the database:

sudo mysql -e "CREATE DATABASE laravel_app CHARACTER SET utf8mb4;"
sudo mysql -e "CREATE USER 'laravel_app'@'localhost' IDENTIFIED BY 'STRONG-PASSWORD';"
sudo mysql -e "GRANT ALL ON laravel_app.* TO 'laravel_app'@'localhost';"

Create /var/www/laravel-app/shared/.env with your environment variables (DB credentials, app key, mail config, queue driver, etc.). DeployHQ's symlinks pattern preserves this file across deploys — the shared/ directory persists, while each release gets a new directory under releases/ that's symlinked from current.

Step 5: Configure the build pipeline in DeployHQ

In project build settings, add the build commands. DeployHQ's build pipeline runs these on DeployHQ's build infrastructure before uploading to the VPS:

composer install --no-dev --optimize-autoloader --no-interaction
npm ci
npm run build

(Skip the npm steps if your Laravel project has no frontend build pipeline.)

In the deployment hooks section, add a post-deploy hook to run on the VPS itself:

cd /var/www/laravel-app/current
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan queue:restart

queue:restart signals all running queue workers to gracefully exit and restart with the new code — important so workers don't run stale code after a deploy.

In the server settings under Configuration , ensure shared files includes .env and shared folders includes storage (Laravel writes to storage/logs, storage/framework/cache, and storage/framework/sessions — these need to persist across deploys). Enable atomic transfers and zero-downtime mode.

Step 6: First deploy

Push to your repository (or trigger a manual deploy). DeployHQ:

Clones the repo at HEAD
Runs the build pipeline on DeployHQ's build infrastructure
Transfers the built artifact to the VPS via SSH
Symlinks current/ to the new release
Runs the post-deploy hooks (migrations, cache, queue restart)
Old releases are kept for rollback

When the deploy completes, visit your server's IP (or domain) and verify Laravel responds.

Common first-deploy failures:

Permission errors on storage/ — chown -R www-data:www-data /var/www/laravel-app/shared/storage and verify the symlinks
APP_KEY missing in .env — Laravel needs a base64 app key; generate locally with php artisan key:generate --show and put the result in your VPS .env
Migrations fail — run php artisan migrate --force manually first via SSH and confirm the database is reachable

Step 7: Queue workers under Supervisor

Add /etc/supervisor/conf.d/laravel-queue.conf:

[program:laravel-queue]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/laravel-app/current/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/log/laravel-queue.log
stopwaitsecs=3600

Reload Supervisor:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-queue:*

numprocs=2 runs two workers; increase if your job throughput needs more. Each worker handles jobs until max-time (1 hour) and gracefully restarts.

Schedule Laravel's task scheduler via cron:

sudo crontab -e -u www-data
# Add this line:
# * * * * * cd /var/www/laravel-app/current && php artisan schedule:run >> /dev/null 2>&1

Step 8: Custom domain + HTTPS

Point your domain at the server's IP via A record. Then either:

Use Cloudflare (free): add the domain to Cloudflare, set DNS to Proxied, and Cloudflare handles HTTPS termination at its edge.

Use Let's Encrypt directly on the VPS :

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d example.com -d www.example.com

Certbot updates the Nginx config to listen on 443, configures SSL, and sets up auto-renewal via systemd timer.

Common gotchas

Queue workers don't pick up new code after deploy. Long-running workers keep the old code in memory. The php artisan queue:restart in the post-deploy hook signals workers to exit gracefully and restart with the new code on the next iteration.

storage/ symlinks break across deploys. The php artisan storage:link command needs to point public/storage at storage/app/public. With atomic deploys, this needs to be set up in shared/ (not in the release). Standard pattern: create the symlink in shared/storage, and let the deploy pipeline create the per-release public/storage symlink pointing to it.

Sessions die on every deploy. If SESSION_DRIVER=file and the session files live in storage/framework/sessions, make sure that directory is in the shared folders list — otherwise it's recreated empty on each deploy.

Cron doesn't fire because of permissions. Laravel's scheduler runs as the cron user. Make sure the cron is registered for the right user (usually www-data) and that the user owns the relevant directories.

Composer runs out of memory during build. Composer can be memory-hungry on complex dependency trees. Either bump the build worker's memory or use COMPOSER_MEMORY_LIMIT=-1 in the build pipeline's environment.

What you've shipped

You now have:

A Laravel app running on a DeployHQ Managed VPS
PHP-FPM + Nginx + MySQL + Redis on a real Ubuntu box you can SSH into
Queue workers under Supervisor and the scheduler under cron
Atomic zero-downtime deploys with one-click rollback via the DeployHQ dashboard
HTTPS via Cloudflare or Let's Encrypt

For the broader picture of where Managed VPS fits, the hosting hub catalogs all five DeployHQ hosting types. The Managed VPS pillar guide covers the provisioning surface in more depth and includes the comparison against DigitalOcean App Platform, Linode, and Render.

If you're choosing between DeployHQ as your deployment tool and Laravel Forge as a provisioning + deployment tool, DeployHQ vs Laravel Forge covers the trade-offs and how to use them together. For a broader category reference, best software deployment tools in 2026 places DeployHQ alongside the rest of the landscape, and your universal deployment and hosting platform is the cross-cluster bridge.

What's next

If you also have a static frontend (an Astro marketing site, a SvelteKit pre-rendered docs site), pair this Managed VPS with DeployHQ Static Hosting in the same DeployHQ project — frontend on Cloudflare's edge, Laravel API on the VPS, one project, one billing relationship.

For Laravel-specific deployment depth — Composer optimization, queue strategies, deployment hooks, environment management — the canonical Laravel guide is the next reference. And for the smooth migration story if you're moving from Forge or Vapor, the migrating to DeployHQ guide covers the broader pattern.

Start a free trial if you don't have an account yet. For the full Managed VPS product reference, see the Managed VPS support library.

Questions or feedback on Laravel + Managed VPS? Email support@deployhq.com or follow @deployhq on X for product updates.

Self-host BugSink on a VPS — the open-source Sentry alternative

DeployHQ — Mon, 27 Jul 2026 10:14:08 +0000

You don't need a Kubernetes cluster to track production errors

Sentry is a great product. Sentry's self-hosted distribution is also a great product — and a 20-service Docker Compose stack with substantial CPU, RAM, and disk needs. If your team's main interaction with self-hosted observability is a Slack thread that begins the Sentry box is OOMing again, you're not alone.

BugSink takes the opposite approach. One application container, one Postgres database, Sentry-SDK-compatible. You point your existing Sentry SDKs at it by changing the DSN. Per BugSink's own marketing page, it's more lightweight and less complicated than Sentry — and the install proves it.

This tutorial wires BugSink onto a $5 VPS with Docker, Postgres, HTTPS via Nginx, and Git-based auto-deploys from DeployHQ. By the end, every change to the stack — env vars, container versions, Nginx config — ships from a git push, with one-click rollback in DeployHQ if a tweak breaks something.

What you'll build

BugSink (current 2.x major version) as a single application container
Postgres 17 in another container for persistent storage of issues, events, and project config
Docker Compose to glue them together with persistent volumes and restart policies
Nginx + Let's Encrypt for HTTPS termination in front of BugSink
DeployHQ for Git-based auto-deploys so the whole stack lives in version control
A working DSN you can drop into any Sentry SDK to redirect events to your VPS

Why BugSink instead of Sentry self-hosted? Three reasons that come up in real conversations. Cost predictability — BugSink is free to self-host with unlimited users and events; you pay for the VPS, full stop. Resource footprint — one app + one DB versus Sentry's ~20-service Helm/Compose distribution. Data residency — for teams who need stack traces (and the source context Sentry sends with them) to stay on infrastructure they own, BugSink is much easier to keep audit-ready.

Why a VPS instead of a hosted plan? If volume is low (handful of apps, hobby projects) the VPS is genuinely cheaper. If volume is high, you're paying once for a box you control instead of per-event metering forever. Either way, a $5/month VPS at Hetzner, DigitalOcean, Vultr, or Linode is enough to start.

Prerequisites

A VPS running Ubuntu 22.04 or 24.04 with SSH access
A domain name pointing at the VPS (e.g. bugsink.example.com)
A GitHub account with an empty private repo for the deploy config
A DeployHQ account (free trial — sign-up link at the end)
Docker and Docker Compose installed locally for testing

Step 1: Prepare the VPS

SSH in as root and install Docker:

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

Create a non-root deploy user that DeployHQ will SSH in as:

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

Copy your SSH key to the new user from your local machine so DeployHQ can authenticate without a password:

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

Confirm ssh deploy@your-vps-ip works passwordless. If it works for you, DeployHQ can do the same.

Step 2: The Docker Compose stack

BugSink ships an official production sample at github.com/bugsink/bugsink/blob/main/docker-compose-sample.yaml. Use it as the starting point, then tighten the production knobs.

In your fresh GitHub repo, create compose.yaml:

services:
  db:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: bugsinkuser
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: bugsink
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: pg_isready -h db
      retries: 5
      start_period: 10s
      interval: 5s
      timeout: 5s

  web:
    image: bugsink/bugsink:2
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
    ports:
      - "127.0.0.1:8000:8000"
    environment:
      SECRET_KEY: ${SECRET_KEY}
      DATABASE_URL: postgresql://bugsinkuser:${POSTGRES_PASSWORD}@db:5432/bugsink
      PORT: 8000
      BEHIND_HTTPS_PROXY: "true"
      USE_X_FORWARDED_HOST: "true"
    healthcheck:
      test: ["CMD-SHELL", "python -c 'import requests; requests.get(\"http://localhost:8000/\").raise_for_status()'"]
      interval: 5s
      timeout: 20s
      retries: 10
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: "1.0"

volumes:
  db-data:

Three changes from BugSink's sample worth flagging:

SECRET_KEY and POSTGRES_PASSWORD are read from environment , not baked into the file. We'll inject them from DeployHQ as a config file in the next step. Never commit secrets to the repo.
Port 8000 is bound to 127.0.0.1 , not 0.0.0.0. BugSink should not be exposed directly to the public internet — Nginx will handle that. Bind to localhost; firewall the external port at the host level too.
BEHIND_HTTPS_PROXY and USE_X_FORWARDED_HOST are both true because Nginx will terminate TLS and forward X-Forwarded-Proto / X-Forwarded-Host. BugSink needs to know to trust those headers when generating absolute URLs (otherwise the DSN it shows you will use http://, and the SDK won't be able to connect).

Generate a real SECRET_KEY locally:

python -c "import secrets; print(secrets.token_urlsafe(50))"

And a Postgres password the same way. Save both — you'll paste them into DeployHQ in the next step.

Also add a .gitignore:

.env
*.local

Commit everything (the compose file, the gitignore, nothing else) and push to GitHub.

Step 3: Wire it up with DeployHQ

This is where the stack stops being a one-off SSH session and starts being a real deployment.

In DeployHQ:

Create a new project and point it at your GitHub repo. DeployHQ supports deploying directly from a GitHub repo to your server without manual webhook setup.
Add a server. Use the VPS IP, port 22, username deploy, and the SSH key you authorised in Step 1. Set the deployment path to /home/deploy/bugsink.
Add a config file at /home/deploy/bugsink/.env containing:SECRET_KEY=<the value you generated> POSTGRES_PASSWORD=<the password you generated>DeployHQ writes this file to disk before every deploy, so Compose picks it up — and the secrets never live in your repo or your container image.
Configure the SSH command. Under the server's SSH commands, add:bash cd /home/deploy/bugsink && docker compose up -dThat's it. DeployHQ checks out the repo, writes the env file, SSHes in, and runs Compose. New container versions, env tweaks, resource limit changes — all of them ship via the same one-line deploy.
Enable auto-deploy on push to main. Every merge now triggers a build.

Trigger the first deploy manually. Watch the log: clone, write env, run Compose. About 30 seconds later, BugSink and Postgres are both up. Check with docker compose ps on the VPS — both services should be healthy.

If anything breaks at this stage, DeployHQ's one-click rollback restores the previous deploy in seconds, so you can iterate on config without leaving the box in a half-broken state.

Step 4: HTTPS with Nginx and Let's Encrypt

BugSink is now running on 127.0.0.1:8000. To put it on the internet at bugsink.example.com with HTTPS:

On the VPS (still as root):

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

Create /etc/nginx/sites-available/bugsink:

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

    client_max_body_size 25M;

    location / {
        proxy_pass http://127.0.0.1:8000;
        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_set_header X-Forwarded-Host $host;
        proxy_read_timeout 60s;
    }
}

Two notes. client_max_body_size 25M — SDK event payloads can be sizeable (source context, attachments) and the default 1MB will reject them. X-Forwarded-Proto and X-Forwarded-Host are why we set BEHIND_HTTPS_PROXY and USE_X_FORWARDED_HOST in Compose; the two halves have to agree.

Enable the site and get a cert:

ln -s /etc/nginx/sites-available/bugsink /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
certbot --nginx -d bugsink.example.com

certbot handles cert provisioning, the redirect from HTTP to HTTPS, and auto-renewal via systemd timers. After this, https://bugsink.example.com/ returns the BugSink login screen.

Step 5: First login and creating a project

The first time you visit your BugSink instance you'll need a superuser. The cleanest way to create one is a one-off manage.py invocation against the running container:

docker compose exec web python -m bugsink.manage createsuperuser

You'll be prompted for email, username, and password. The official docker-compose-sample.yaml also supports a CREATE_SUPERUSER: email:password env var for the very first boot, but injecting a password through env is messy; the createsuperuser command keeps the secret off your disk history.

Log in. Create a new project (one per application is the standard pattern — same as Sentry). BugSink shows you the DSN on the project page; it looks like a normal Sentry DSN, just pointing at your VPS hostname instead of o<your-org>.ingest.sentry.io.

Step 6: Point an application at BugSink

The whole point of Sentry-SDK compatibility: nothing in your application code changes.

In the SDK init for a Python app, that's:

import sentry_sdk

sentry_sdk.init(
    dsn="https://<your-bugsink-key>@bugsink.example.com/<project-id>",
    environment="production",
    release="my-app@1.2.3",
)

Same for JavaScript, Ruby, PHP, Go, .NET, Rust — every Sentry SDK that takes a DSN takes BugSink's. Per BugSink's own quickstart docs, install an SDK, copy the DSN, trigger an error on purpose, and it appears in BugSink within seconds.

Two things to know:

release is the same field Sentry uses , and BugSink's release tracking works the same way — issues get tagged with the release they first appeared in. The release string should be a version + commit SHA your build pipeline produces, not a timestamp.
environment has to match between your SDK config and any release notifications you send (more on that below). prod vs production mismatches will silently break attribution.

Production hardening

A working deploy is the floor, not the ceiling. Five things to add before BugSink starts taking real traffic:

1. Pin the image by digest, not the floating :2 tag. BugSink's :2 tag is the current major-version label, and the maintainer pushes patch updates to it. For reproducible builds, pin to a specific digest (bugsink/bugsink@sha256:...) and bump it explicitly via a commit. Same for postgres:17-alpine — pin the minor.

2. Back up the Postgres volume. Stack traces are not infinite — BugSink has retention policies — but losing your historical issue grouping mid-incident is painful. A daily pg_dump to S3 (or another off-host destination) via a cron container is the minimum bar. The DB volume in the compose above is what survives container restarts; without backups it does not survive a VPS disk failure.

3. Watch the ingest rate limit. Per BugSink's ingestion rate limit docs, there are project-level limits to keep one noisy app from drowning out the rest. Configure these before an app starts throwing 500 errors at 100/sec.

4. Resource limits on the web container. The compose above already includes a 1G memory / 1 CPU cap on the web service. Tune up if you're ingesting heavy traffic — BugSink's event digestion isn't free, and unbounded growth on a $5 VPS will OOM the whole box (including Postgres).

5. Rate-limit the ingest endpoint at Nginx. BugSink will rate-limit at the application layer per the link above, but a Nginx limit_req zone on /api/ (or wherever the SDK posts events) acts as a cheap pre-filter against accidental loops in misconfigured clients.

For the deploys themselves, DeployHQ runs zero downtime deployments by default. When you graduate to multiple replicas behind a load balancer or move BugSink to a bigger box, the rollout pattern stays the same.

Tying BugSink issues to DeployHQ deploys

Because BugSink speaks the Sentry release API, the existing DeployHQ Sentry deploy tracking integration can in principle point at a BugSink installation — same project:releases scope, same release-creation endpoint shape. If your team relied on Sentry's release-tagged regressions before, you can keep that workflow with BugSink as the backend. (Test before relying on it in production — Sentry SDK compatibility is BugSink's headline claim, but the management API surface has edges; verify against your specific version.)

If you'd rather not test that route, the same outcome falls out of including a release value in every SDK init that matches the commit SHA your build pipeline already exposes. BugSink groups issues by release automatically.

Where to go from here

The setup above is a working production install for a single low-to-medium-traffic team. A few paths from here, depending on what you actually need next:

More self-hosted observability on the same VPS pattern. The same Docker Compose + Nginx + DeployHQ pattern fits a long list of self-hostable tools:

Hermes Agent on a VPS — self-improving agent runtime with persistent skills
Self-host the Paperclip orchestrator on a VPS — agent orchestrator with a Docker-first install
Self-host Immich on a VPS — open-source Google Photos alternative
Self-host Vaultwarden on a VPS — open-source Bitwarden server
Deploy your first AI agent to a VPS with Docker — minimal FastAPI agent in the same shape

Or stick with hosted error tracking and add deploy tracking. If self-hosting is one bridge too far and you'd rather stay on Sentry, Bugsnag, Rollbar, or Honeybadger, the DeployHQ integration pattern is identical to what you just built — one config block in DeployHQ, every release shows up in the dashboard:

Sentry deploy tracking with DeployHQ (see the integration linked above)
Bugsnag deploy tracking with DeployHQ
Rollbar deploy tracking with DeployHQ
Honeybadger deploy tracking with DeployHQ

The point isn't which backend you pick — it's that error tracking, the deploy that introduced each error, and a one-click rollback should all live in the same workflow. BugSink + DeployHQ gets you there for the price of a VPS.

Ready to put error tracking on infrastructure you control? Start a free DeployHQ trial and have BugSink shipping from git push in under thirty minutes.

Need a hand? Email us at support@deployhq.com or find us on X at @deployhq.

Why appleboy/ssh-action and SCP Scripts Break for Real Deployments

DeployHQ — Fri, 24 Jul 2026 14:18:39 +0000

Almost every team that deploys to its own servers arrives at the same place. You add a deploy job to your CI pipeline, drop in a community SSH action or a hand-written scp command, paste your key into a secret, and it works. The first green checkmark feels like you've solved deployment.

Then the pipeline starts costing you. Not all at once — in small, hard-to-reproduce ways that surface at the worst time, usually during an incident when you most need the deploy path to be boring.

This is a look at why the just SSH in from CI pattern erodes, using the failure modes teams actually hit, and where a dedicated deployment layer earns its place over a pipeline step. The same brittleness shows up whether you push over SSH or FTP from CI — here we focus on the SSH side.

The pattern that everyone starts with

The canonical setup is a workflow step built on something like appleboy/ssh-action, or a hand-rolled scp/rsync transfer (each with its own tradeoffs between SFTP, SCP, and rsync), triggered on push to main:

- name: Deploy
  uses: appleboy/ssh-action@v1
  with:
    host: ${{ secrets.HOST }}
    username: ${{ secrets.USER }}
    key: ${{ secrets.SSH_KEY }}
    script: |
      cd /var/www/app
      git pull
      composer install --no-dev
      php artisan migrate --force

Nothing here is wrong on day one. The problem is that this step is quietly doing several jobs at once — authentication, transport, remote execution, release logic, and error handling — with none of them owned by anything that understands deployment. It's a shell script wearing a CI badge.

Failure mode 1: secrets that don't mask cleanly

CI systems mask registered secrets in logs by replacing the exact secret string. That guarantee gets thin the moment your secret is a composite value. A host:port secret, for example, may only be partially redacted — the masker matches the whole string, not the host fragment that also appears elsewhere in output — so part of the value leaks into the log.

Mask more aggressively and you trade one problem for another: if every host string is scrubbed across a multi-server deploy, the logs become ambiguous. You can no longer tell which server produced which line, which is exactly the information you need when one host in the fleet fails and the rest succeed. Coordinating that cleanly — deploying to multiple servers in parallel without version drift — is its own discipline that raw CI logs don't support.

That's the tension. Raw CI logs weren't designed to be a deployment audit trail, and bending them into one fights the masking layer both directions.

Failure mode 2: no concept of a release

git pull && composer install mutates your live directory in place. There is no atomic switch, no discrete artifact, and no clean before to return to. If the build half-completes — a dependency fetch times out, a migration partially applies — you are now serving a site that is neither the old version nor the new one.

Rollback in this world means another forward deploy: check out the previous SHA, reinstall, re-migrate, and hope the down-migration is as clean as you assumed when you wrote it at 3pm on a calm Tuesday. Teams that lean on this pattern almost always describe rollback as by memory — there's no retained artifact to flip back to because the model never produced one. Atomic releases with a retained history and a one-click rollback exist precisely because just deploy the old commit again is not a recovery strategy under pressure.

Failure mode 3: the runner is not a stable machine

Hosted runners are ephemeral and clean, which sounds like a feature until your deploy depends on state. Self-hosted runners are the opposite: they persist, so they accumulate. Leftover SSH agents, a known_hosts file from a decommissioned server, a cached key, half-cleaned working directories — residue from previous runs that makes a deploy behave differently depending on which runner picked it up and what the last job left behind.

The result is the least debuggable class of failure: the pipeline is green on one runner and red on another, with the same commit. You end up debugging the CI environment instead of your application.

Failure mode 4: transport and orchestration are tangled together

A single ssh-action step is authentication, file transfer, remote shell, and release orchestration fused into one opaque block. When it fails, the error surface is a shell exit code and a wall of stdout. Was it the connection? A key permission? A failed composer step on the remote? A timeout mid-transfer? The step can't tell you, because it doesn't model those as distinct phases — it just runs a script and reports whether the script exited non-zero.

Pulling these concerns apart is most of what a real deployment tool does. When deployments run over SSH and SFTP through a system that models them, connection, build, transfer, and remote commands are separate, individually logged steps — so a failure points at a stage instead of a stack trace.

What actually changes when deployment is its own layer

The fix is not write a better bash script. It's moving the responsibilities that don't belong in a CI job out of it. GitHub Actions is a genuinely good CI system — running tests, building artifacts, gating merges (if that's the part you want to get right, here's how to build a CI/CD pipeline with GitHub Actions). Deployment is a different job with different requirements: credentials that live at the deployment layer instead of in pipeline secrets, per-server logs you can actually read, build steps that run off your production host, and a release model with history and rollback built in. That's the line the DeployHQ vs GitHub Actions comparison draws in detail — CI to prove the code is good, a dedicated deployment platform to ship it safely.

Concretely, that means:

Credentials and known hosts live in one place , not copied into every repo's secrets, not re-provisioned on ephemeral runners, and not a matter of generating SSH keys from the command line for every new target.
Build commands run in an isolated environment through a proper build pipeline, so a failed composer install never leaves your live server half-updated.
Every server gets its own readable deploy log , so a multi-host deploy tells you exactly which target failed — no log-masking guesswork.
Releases are atomic and retained , so recovery is flipping back, not re-deriving the previous state — the foundation of atomic, zero-downtime release strategies.

If you've been staring at a red deploy job trying to work out whether it was the network, the key, or the remote build that broke, that ambiguity is the tax. Start with a project and connect your server and the SSH glue stops being something you maintain.

When the CI-only pattern is genuinely fine

To be fair to the humble ssh-action: if you deploy a single static site to a single box, downtime during deploy is acceptable, and you rarely roll back, the pattern is proportionate. Don't add a deployment platform to a personal blog. The calculus changes the moment you have more than one server, a build step that can fail, real users who notice a broken release, or a teammate who needs to understand what shipped without reading raw pipeline output. That's when the deploy step wants to become a deployment system. If you're comparing the options for a single box, the easiest way to deploy on a VPS weighs manual SSH, Capistrano, and managed deploys side by side.

Deploying over SSH from CI isn't a mistake — it's a stage most teams pass through. The mistake is staying there after your setup has outgrown it.

Questions about moving a brittle CI deploy onto a managed path? Email us at support@deployhq.com or reach out on X/Twitter @deployhq.

Deploy a Modern Laravel App to cPanel Shared Hosting (No SSH)

DeployHQ — Fri, 24 Jul 2026 14:13:59 +0000

If you build with a modern Laravel stack — Inertia, React or Vue, Tailwind, a Vite build step — and your client insists on their existing cPanel shared hosting, you've probably hit the wall this post is about. The framework assumes a build toolchain and often SSH. The host gives you neither. Every just run composer install on the server tutorial quietly assumes access you don't have.

You don't actually need that access. The trick is to stop treating the shared host as a place where building happens, and start treating it as a place where finished files land.

Why the usual advice fails on shared hosting

The standard deploy recipe for a Laravel VPS is: SSH in, git pull, composer install, npm run build, php artisan migrate. On cPanel shared hosting, that chain breaks at almost every link:

No SSH. Many shared plans expose only FTP/SFTP and the cPanel UI. There's no shell to run commands in.
Composer won't install (or won't run). Memory limits, missing CLI PHP, no write access outside your home directory, or no way to invoke it at all. This is one of the most common shared-hosting complaints, and it's usually not fixable from your side. Running Composer where the build actually belongs — off the shared host — is the approach in deploying a PHP site with Composer off-host.
No Node build. Vite/webpack need a build environment the host doesn't provide, so your compiled CSS/JS never gets generated where the site actually runs.
Connecting Git is fiddly. cPanel's built-in Git Version Control ties awkwardly to a single deploy key, which is why people hit walls trying to connect multiple private repositories to one cPanel account.

The instinct is to fight each of these on the server. The better move is to not run any of them on the server at all.

Build off-host, deploy the artifact

The model that works on constrained hosting separates the two jobs the shared host can't do from the one it can:

Build somewhere with a real toolchain — install Composer dependencies, run the Vite/npm build, cache config, generate the optimized autoloader.
Ship only the finished result to the host over FTP/SFTP.

The shared host never sees Composer or Node. It receives a directory of ready-to-serve files, which is the one thing every cPanel plan can accept. This is the whole idea behind a managed build pipeline: your build commands run in an isolated environment on the deployment side, and only the compiled output is transferred to the FTP/SFTP or cPanel-style target you configure.

Compared to wiring cPanel's own Git tooling to your repositories, this sidesteps the single-deploy-key limitation entirely — the platform connects to your repository centrally, so multiple private repos and multiple targets stop being a plumbing exercise. If you're weighing the two approaches directly, the DeployHQ vs cPanel deployment comparison lays out where each fits. For the full sequence of build steps and release hygiene on this stack specifically, see Laravel build-pipeline deployment best practices.

A no-SSH Laravel deployment, end to end

Here's the shape of it, assuming a Laravel app with an Inertia/React front end on a cPanel shared plan that only offers FTP/SFTP.

1. Point deployment at your repository. Connect the Git repo once. Every push to your deploy branch becomes a candidate release — no cPanel Git key juggling.

2. Define the build commands. These run off-host, not on cPanel:

composer install --no-dev --optimize-autoloader
npm ci
npm run build
php artisan config:cache
php artisan route:cache

The output — vendor/, the built public/build/ assets, cached config — becomes the artifact.

3. Configure the FTP/SFTP target. Add the host's FTP or SFTP credentials as a server. The shared-hosting deployment setup covers the target configuration, and the step-by-step FTP-from-Git walkthrough shows the mechanics if FTP is all you've got. Prefer SFTP where the host offers it — the same setup over SSH/SFTP is worth the small extra effort for the encrypted transport.

4. Handle Laravel's public-directory quirk. On shared hosting the web root is usually public_html, not your app's public/. Map the deploy so the built public/ contents land in public_html, and keep the framework files above the web root. This is a mapping decision, not a code change.

5. Deploy. Push to your branch. The build runs off-host, the finished files transfer to public_html, and the site updates — with a deploy log for each run, so a failed transfer tells you what happened instead of leaving you guessing.

If that sequence is where you're stuck right now, connecting a repository and a shared-hosting target is the fastest way to see it work against your own setup.

The same pattern isn't Laravel-specific

Everything above is really about any build-step framework meeting a host that can't build. The same off-host-build approach applies to a Drupal site where Composer won't run on shared hosting (see the Laravel deployment guide for framework specifics), a static-site generator, or a Vue SPA. It works just as well when you deploy WordPress from Git without FTP uploads. The constraint — the host serves files but can't assemble them — is the same, and so is the fix.

Is shared hosting still the right home?

Sometimes the honest answer is that the constraint is worth removing rather than working around. If you're regularly fighting the host's limits, the signs it's time to move off shared hosting to automated deployments is a useful gut-check. And if you've been told FTP is obsolete, the reality is more nuanced — FTP's continued, legitimate role in deployment covers where it still earns its place. But when the client's cPanel plan is a fixed requirement, building off-host and deploying the artifact is how you ship a modern app onto it without asking the host for access it will never give you.

Stuck on a specific no-SSH deployment? Email support@deployhq.com or ask us on X/Twitter @deployhq.

How to Run WordPress on AWS: EC2, Lightsail & Git Deploys

DeployHQ — Wed, 22 Jul 2026 07:14:29 +0000

Running WordPress on AWS gives you something shared hosting never will: full control over the machine, the network, and the database that serve your site. But that control comes with decisions most tutorials skip — which AWS compute service to pick, how to lock down your firewall, whether to run MySQL on the box or hand it to a managed service, and how to keep the IP address from changing every time you reboot. This guide walks through the whole path: choosing between EC2, Lightsail, and Elastic Beanstalk, provisioning and securing the instance, installing WordPress, and then automating your theme and plugin deploys from Git so you never SSH in to drag files around again.

We'll focus on the decisions that actually bite you in production, not the happy-path clicks you can find anywhere.

Step 1: Choose your AWS compute — EC2 vs Lightsail vs Elastic Beanstalk

AWS gives you at least three sensible ways to host WordPress, and the right one depends on how much of the underlying machine you want to manage.

Service	Best for	Pricing model	Control
Lightsail	A single WordPress site, predictable cost, minimal ops	Fixed monthly (bundle)	Medium — AWS manages the plumbing
EC2	Full control, custom stacks, multiple sites, tuning	Pay-as-you-go (per second)	Full — it's your server
Elastic Beanstalk	Managed platform with autoscaling built in	Pay for the underlying resources	Low-to-medium — AWS runs the platform

Amazon Lightsail is the simplest entry point. It's EC2 underneath, but wrapped in a fixed-price bundle (compute + storage + a generous data transfer allowance) with a friendlier console. You get a static IP, DNS management, and one-click blueprints. For a typical single WordPress site, this is the pragmatic default.

Amazon EC2 hands you a raw virtual server and gets out of the way. You pick the operating system, install exactly the stack you want, and pay only for what you run. Choose EC2 when you need a custom stack (specific PHP or Nginx tuning), plan to host several sites on one box, or want to attach services like Amazon RDS and ElastiCache directly. If you want to walk the full server build, our guide to deploy to Amazon EC2 covers the connection setup.

Elastic Beanstalk is a managed platform layer that provisions and autoscales the infrastructure for you from an application bundle. It shines when traffic is spiky and you want load balancing and autoscaling without wiring them by hand — but it adds abstraction that a single WordPress site rarely needs, and it's a different mental model from a plain server.

Our recommendation: start on Lightsail if you want fixed cost and low ops, or EC2 if you want full control. Reach for Beanstalk only when autoscaling is a hard requirement.

Step 2: Provision and secure the instance

Whether you land on Lightsail or EC2, the provisioning checklist is the same: pick an image, size it, open the right ports, and pin the IP.

Pick the image (AMI or blueprint)

On Lightsail: choose a blueprint. The Bitnami WordPress blueprint gives you a fully installed LAMP + WordPress stack in a couple of minutes. If you'd rather build the stack yourself, pick an OS-only blueprint like Ubuntu 24.04 LTS.
On EC2: pick an AMI. Ubuntu Server 24.04 LTS or Amazon Linux 2023 are both solid. Start clean and install the stack yourself for maximum control.

Size it honestly

A small WordPress site runs comfortably on a 2 GB RAM instance — an EC2 t3.small or the equivalent Lightsail bundle. The 1 GB tier works but leaves little headroom once you add plugins and a page cache. You can resize an EC2 instance later by stopping it and changing the type, so don't over-buy on day one.

Lock down the firewall (this is where people get burned)

On EC2 this is the security group ; on Lightsail it's the instance firewall. Configure inbound rules deliberately:

Port	Protocol	Source	Purpose
80	TCP (HTTP)	`0.0.0.0/0`	Public web traffic
443	TCP (HTTPS)	`0.0.0.0/0`	Public secure traffic
22	TCP (SSH)	Your IP only (`x.x.x.x/32`)	Admin access

The gotcha that bites everyone: do not open port 22 to 0.0.0.0/0. Leaving SSH open to the entire internet invites constant brute-force attempts. Restrict the source to your own IP (or a VPN range). Ports 80 and 443 are meant to be public; port 22 is not.

Pin the IP with a static/Elastic IP

By default, an EC2 instance's public IP changes every time you stop and start it. That will silently break your DNS and your site. Allocate an Elastic IP and associate it with the instance so the address stays put. On Lightsail, attach a static IP — same idea, one click. Do this before you point your domain's DNS at the box.

Set up SSH access

Create (or upload) an SSH key pair when you launch the instance and download the private key. You'll connect with it, and — importantly — you'll hand the same kind of key to your deployment tool later:

# Connect to your instance (Ubuntu AMI uses the "ubuntu" user)
ssh -i ~/.ssh/wordpress-aws.pem ubuntu@<your-elastic-ip>

If you provisioned Lightsail's Bitnami blueprint, deploy to AWS Lightsail documents where the WordPress files and credentials live on that image.

Step 3: Install the stack and WordPress

You have two honest paths here, depending on the image you chose.

Path A — Pre-baked Bitnami (Lightsail)

If you picked the Bitnami WordPress blueprint, WordPress is already installed and serving. Grab the admin password from the instance (it's in /home/bitnami/bitnami_credentials), log in at /wp-admin, and you're essentially done with the stack. This is the fastest route to a running site.

Path B — Build a LEMP stack yourself (EC2 or OS-only Lightsail)

For full control, install a LEMP stack (Linux, Nginx, MySQL, PHP-FPM) on Ubuntu:

# 1. Update packages
sudo apt update && sudo apt upgrade -y

# 2. Install Nginx, MySQL, PHP-FPM and common WordPress extensions
sudo apt install -y nginx mysql-server \
  php-fpm php-mysql php-curl php-gd php-xml php-mbstring

# 3. Secure the MySQL install (set root password, remove test DB)
sudo mysql_secure_installation

# 4. Create the WordPress database and a dedicated user
sudo mysql -e "CREATE DATABASE wordpress;"
sudo mysql -e "CREATE USER 'wp_user'@'localhost' IDENTIFIED BY '<strong-password>';"
sudo mysql -e "GRANT ALL ON wordpress.* TO 'wp_user'@'localhost'; FLUSH PRIVILEGES;"

# 5. Download and place WordPress
cd /tmp && curl -O https://wordpress.org/latest.tar.gz
tar xzf latest.tar.gz
sudo mv wordpress /var/www/wordpress
sudo chown -R www-data:www-data /var/www/wordpress

From there, point an Nginx server block at /var/www/wordpress, copy wp-config-sample.php to wp-config.php with your database credentials, and finish the famous five-minute install in the browser.

The real decision: local MySQL vs Amazon RDS

Where your database lives is the tradeoff worth thinking about before you go live.

Local MySQL (on the same instance) is free, simple, and fast because there's no network hop. But you own everything: backups, tuning, patching, and recovery. If the instance dies, so does the database unless you've been backing it up.
Amazon RDS (managed MySQL) costs extra — you're paying for a separate managed instance — but you get automated backups, point-in-time recovery, easy version upgrades, and optional Multi-AZ failover. It also decouples the database from the web server, so you can resize or replace the instance without touching your data.

For a small hobby or brochure site, local MySQL is fine. For anything where the data matters — a store, a client site, a business — RDS pays for itself the first time you need a clean restore. Point wp-config.php at the RDS endpoint instead of localhost and WordPress doesn't know the difference.

Once your site is live, the last thing you want is to keep logging in over SSH to push theme edits by hand. Ready to put deploys on autopilot? Start on the free plan or a 10-day trial and connect your repository in a few minutes.

Step 4: The bridge — version your code in Git and automate deploys

Here's the part that separates a hobby setup from a maintainable one. Your WordPress theme and custom plugin code is real software, and it belongs in a Git repository — not edited live on the server through the WordPress admin. Once it's in Git, you can push changes automatically to your AWS instance the moment you merge, with none of the manual SFTP shuffling.

DeployHQ connects to your GitHub, GitLab, or Bitbucket repo and ships your code to the EC2 or Lightsail instance over SSH/SFTP — the same key-based access you set up in Step 2. On each commit to your chosen branch, it can run a build pipeline (compile assets, run composer install, minify CSS) on a separate build server, then transfer only the changed files. It performs atomic deployments — releasing into a fresh directory and swapping a symlink so visitors never see a half-uploaded site — and gives you one-click rollback if a release misbehaves.

flowchart TD
    A[Push to main branch] --> B[DeployHQ detects commit]
    B --> C[Run build pipeline on build server]
    C --> D[Transfer changed files over SSH]
    D --> E[Atomic release: symlink swap]
    E --> F[WordPress site live on AWS instance]

Why automate instead of SSHing in? Because manual file drags cause half-deployed states, are impossible to reproduce across a team, and have no undo. Automated deploys are consistent, atomic, and reversible — and they let you run build steps that manual uploads can't.

We won't re-teach the full pipeline setup here — the step-by-step lives in our guide to automate WordPress deployments from Git, which covers connecting the repo and configuring the transfer. For the broader concepts, our overview of deployment automation explains why this pattern matters for any stack, and if you're coming from a plain server the install WordPress on a VPS beginner's guide fills in the server-side basics. WordPress is PHP under the hood, so the same approach used to deploy a PHP site applies directly.

Keep the database and uploads out of Git. Version your themes, plugins, and configuration — not wp-content/uploads or the database. Those are runtime data, and committing them causes conflicts and bloat. Use a keep development and production in sync workflow to manage content and media separately from code.

Step 5: Production notes — backups, HTTPS, and scaling

Back up to S3

Your instance is not a backup. Schedule regular dumps of the database and wp-content/uploads to Amazon S3, which is cheap, durable, and off-instance:

# Nightly database backup pushed to S3 (add to cron)
mysqldump wordpress | gzip > /tmp/wp-$(date +%F).sql.gz
aws s3 cp /tmp/wp-$(date +%F).sql.gz s3://my-wordpress-backups/db/

Our walkthrough on how to back up your server to AWS S3 covers automating this properly with lifecycle rules so old backups age out.

Enable HTTPS

For a certificate that lives on the instance (Nginx or Apache serving directly), use Let's Encrypt via Certbot — it's free and auto-renews:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

A common gotcha: AWS Certificate Manager (ACM) certificates are free too, but you cannot install them directly on an EC2 instance. ACM certs only attach to AWS-managed endpoints like an Application Load Balancer or CloudFront. If you're serving straight from the box, use Let's Encrypt. Reach for ACM only when you put a load balancer or CDN in front.

Scaling considerations

When a single instance stops keeping up, scale in this order:

Vertical resize — bump the instance to more RAM/CPU. Simplest first move.
Add caching — a page cache plus an object cache (Redis via ElastiCache) removes most database pressure.
Offload media — move wp-content/uploads to S3 and serve it through CloudFront so the web server isn't shipping images.
Separate the database — move to Amazon RDS if you haven't, so the web tier and data tier scale independently.
Go horizontal — run multiple instances behind a load balancer across Availability Zones for redundancy.

One clear boundary worth stating: the AWS-side architecture — Availability Zones, load balancers, multi-region redundancy — is something you design and provision on AWS. DeployHQ's job is to ship your code reliably to the server or servers you've configured; it doesn't build your AWS topology for you. Keep those two responsibilities distinct and both jobs stay simple. If your growth path leads toward a managed platform with built-in autoscaling, we also cover how to deploy to AWS Elastic Beanstalk from Git.

FAQ

Should I use EC2 or Lightsail for WordPress? Use Lightsail if you want fixed monthly pricing and minimal server management for a single site — it's the pragmatic default. Choose EC2 when you need full control over the stack, plan to host multiple sites, or want to attach managed services like RDS and ElastiCache directly.

Do I need Amazon RDS, or can I run MySQL on the same instance? Both work. Local MySQL is free and simple but you own backups and recovery. RDS costs extra but adds automated backups, point-in-time recovery, and optional failover. For any site where the data matters, RDS is worth it; for a hobby site, local MySQL is fine.

Why does my WordPress site's IP address keep changing? Because an EC2 instance gets a new public IP each time it stops and starts. Allocate an Elastic IP (or a Lightsail static IP) and associate it with the instance so the address is permanent, then point your DNS at it.

Can I use a free AWS Certificate Manager certificate on my EC2 instance? Not directly. ACM certificates only attach to AWS-managed endpoints like Application Load Balancers and CloudFront. To serve HTTPS straight from an EC2 or Lightsail instance, use a free Let's Encrypt certificate via Certbot instead.

How do I deploy theme and plugin changes without SSHing in every time? Keep your theme and custom plugin code in a Git repository and connect it to a deployment tool that pushes to your instance over SSH on each commit. You get consistent, atomic releases with rollback — no manual SFTP, and no half-deployed sites.

Wrapping up

Running WordPress on AWS is mostly about making a few decisions well: Lightsail or EC2 for compute, local MySQL or RDS for the database, a locked-down firewall, a pinned IP, and HTTPS that actually renews itself. Get those right and you have a fast, controllable host. Add automated deploys from Git and you also get a maintainable one — every change versioned, every release reversible.

Ready to stop dragging files over SFTP? Connect your repository and deploy from GitHub to server in minutes. Questions? Email us at support@deployhq.com or reach out on X.

WordPress with Docker: A Local-to-Production Workflow (2026)

DeployHQ — Wed, 22 Jul 2026 07:14:17 +0000

Setting up WordPress the old way meant installing PHP, a web server, and MySQL directly on your laptop, then praying the versions roughly matched whatever your host was running. They never did. A plugin that worked on your machine would throw a fatal error in production because the live server ran PHP 8.1 and you were on 8.4. Docker fixes that mismatch by packaging PHP, Apache, and the database into disposable containers you can spin up, tear down, and rebuild in seconds.

This guide covers the part most tutorials skip: running WordPress in Docker locally as your development environment, with a real docker-compose.yml you can copy today. You'll get a working WordPress + database + phpMyAdmin stack, learn how to edit themes and plugins on a mounted volume, run WP-CLI inside a container, and — once your code lives in Git — hand the production step down to an automated deployment instead of Dockerizing your live site. By the end you'll have local-to-production parity without the works on my machine tax.

Why run WordPress in Docker locally

Local WordPress development has three chronic problems, and containers solve all three.

Environment parity. Production runs a specific PHP version, a specific MySQL or MariaDB version, and a specific set of extensions. When your local machine drifts from those versions, bugs appear only after you deploy. Pinning the same image tags locally that your host runs closes that gap. If you understand how Docker containers work, you already know the pitch: the container is the environment, so it behaves identically on your laptop, a teammate's laptop, and CI.

No global pollution. Installing PHP and MySQL system-wide means every project shares one runtime. Upgrade PHP for one client and you risk breaking another. Docker scopes everything to the project directory — delete the folder and the environment is gone, with nothing left behind in /usr/local.

Disposable, reproducible setups. A new developer clones the repo, runs one command, and has a working site in under a minute. No wiki page of setup steps that rot the moment someone bumps a version. The docker-compose.yml is the documentation, and it's executable.

The catch — and this is the part to internalize before you start — is that WordPress in Docker locally and WordPress in Docker in production are different projects with different tradeoffs. This guide is firmly about the first. We'll cover why you probably shouldn't Dockerize production later on.

A working docker-compose.yml for local WordPress

Here's a complete stack: WordPress (PHP + Apache), a MariaDB database, and phpMyAdmin for poking at tables. Create a project folder, drop this in as docker-compose.yml, and add a .env file alongside it.

# docker-compose.yml — local WordPress development stack
services:
  db:
    image: mariadb:11.4
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: ${DB_NAME}
      MARIADB_USER: ${DB_USER}
      MARIADB_PASSWORD: ${DB_PASSWORD}
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    volumes:
      - db_data:/var/lib/mysql
    ports:
      - "3306:3306"

  wordpress:
    image: wordpress:6.7-php8.3-apache
    restart: unless-stopped
    depends_on:
      - db
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_NAME: ${DB_NAME}
      WORDPRESS_DB_USER: ${DB_USER}
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
      # WP_DEBUG on locally, never in production
      WORDPRESS_DEBUG: 1
    volumes:
      - wp_core:/var/www/html
      - ./wp-content/themes/my-theme:/var/www/html/wp-content/themes/my-theme
      - ./wp-content/plugins/my-plugin:/var/www/html/wp-content/plugins/my-plugin
    ports:
      - "8080:80"

  phpmyadmin:
    image: phpmyadmin:5.2
    restart: unless-stopped
    depends_on:
      - db
    environment:
      PMA_HOST: db
      UPLOAD_LIMIT: 64M
    ports:
      - "8081:80"

volumes:
  db_data:
  wp_core:


# .env — kept out of Git via .gitignore
DB_NAME=wordpress
DB_USER=wp_user
DB_PASSWORD=change-me-locally
DB_ROOT_PASSWORD=change-me-too

Start it:

# Pull images and launch in the background
docker compose up -d

# Watch the logs until WordPress finishes its first-run setup
docker compose logs -f wordpress

Open http://localhost:8080 and you'll land on the WordPress installer. phpMyAdmin is at http://localhost:8081.

What each service does

db (MariaDB). This is your database. MariaDB is a drop-in replacement for MySQL and is what many managed hosts actually run, so it's a sensible default. The db_data named volume persists your tables between restarts — without it, docker compose down would wipe your posts and settings every time. Note the environment variables use the MARIADB_ prefix; if you swap in the mysql:8.4 image instead, they become MYSQL_DATABASE, MYSQL_USER, and so on.

wordpress (PHP + Apache). The official wordpress image bundles PHP and Apache with WordPress core already installed. The tag 6.7-php8.3-apache pins all three: WordPress 6.7, PHP 8.3, Apache. Pin these to match production — that's the entire point. WORDPRESS_DB_HOST: db:3306 works because Compose puts every service on a shared network where the service name (db) resolves as a hostname.

phpmyadmin. Optional but handy — a browser UI for the database so you can inspect rows, run queries, and export dumps without a MySQL client. Drop this service entirely if you prefer the CLI.

The volume strategy that actually matters

Notice we mount wp_core (a named volume) over the whole of /var/www/html, but then bind-mount only your theme and plugin directories from the host on top of it. This is deliberate:

WordPress core, and any plugins you install through the admin UI, live inside the named volume — you don't want those cluttering your Git repo.
Your custom theme and plugin — the code you actually write and version — live on your host machine at ./wp-content/themes/my-theme and ./wp-content/plugins/my-plugin, so your editor sees them directly and changes appear instantly in the browser.

This split keeps your repository lean: it contains only the code you author, not the tens of thousands of core files.

Working with themes and plugins on the mounted volume

Because your theme and plugin folders are bind-mounted, editing them is just editing files on your machine. Save style.css, refresh the browser, done — no rebuild, no copy step. That instant feedback loop is the day-to-day payoff of this setup.

Two gotchas bite almost everyone the first week:

File permissions and UID mismatch. Inside the container, Apache runs as the www-data user (UID 33 on Debian-based images). On Linux hosts, files you create as your own user (often UID 1000) can end up owned by a UID the container can't write to, and WordPress's media uploader will throw permission errors. The quickest local fix is to align ownership on the mounted directory:

# Give the container's www-data user write access to uploads
sudo chown -R 33:33 ./wp-content

On macOS and Windows this rarely bites because Docker Desktop's filesystem sharing translates UIDs for you. On native Linux it's the number-one cause of why can't I upload an image locally.

Database persistence. docker compose down stops and removes containers but keeps named volumes, so your database survives. docker compose down -v adds -v and deletes volumes too — that wipes your local database. Learn the difference now, because running the -v variant by reflex when you just wanted a clean restart is a classic way to lose an afternoon of test content.

Running WP-CLI in a container

You don't install WP-CLI on your host — you run it in a throwaway container that shares the WordPress volumes and network. Add this to docker-compose.yml:

  wpcli:
    image: wordpress:cli-php8.3
    depends_on:
      - db
      - wordpress
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_NAME: ${DB_NAME}
      WORDPRESS_DB_USER: ${DB_USER}
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
    volumes:
      - wp_core:/var/www/html
    user: "33:33"

Then run commands with docker compose run --rm:

# Install WordPress non-interactively
docker compose run --rm wpcli wp core install \
  --url="http://localhost:8080" \
  --title="Local Dev Site" \
  --admin_user=admin \
  --admin_password=admin \
  --admin_email=you@example.com

# Activate your theme and a plugin
docker compose run --rm wpcli wp theme activate my-theme
docker compose run --rm wpcli wp plugin activate my-plugin

# Export the database to a file on your host
docker compose run --rm wpcli wp db export /var/www/html/backup.sql

The --rm flag deletes the CLI container after each command so they don't pile up. Scripting wp core install this way means a fresh clone can be fully bootstrapped — WordPress installed, theme active, sample content imported — with a single shell script, which is where the one command and you're running promise actually pays off.

The bridge: from local Docker to production

Here's the mental model that keeps this simple. Docker is your local development environment. Your custom theme and plugin code is what you actually ship. Git is the pipeline between the two.

Commit the wp-content/themes/my-theme and wp-content/plugins/my-plugin directories (plus docker-compose.yml) to a repository. Do not commit wp-config.php, your .env file, WordPress core, or the uploads directory — those are environment-specific or reproducible, and secrets never belong in Git.

From there, you don't manually SFTP files to your server ever again. Once your theme and plugin code is in Git, you can automate WordPress deployments from Git so that every push to your main branch copies the changed files to your live WordPress host over SSH. This is the same deployment automation pattern any modern web team uses: your local environment and your production release both trace back to the same commit.

The important boundary: DeployHQ ships your code to your host — it isn't a WordPress host and it doesn't run your containers in production for you. Your live site can be a VPS, a managed WordPress host, or shared hosting; DeployHQ pushes the theme and plugin files there and runs any build steps you configure. If you're standing up the server side from scratch, our walkthrough on how to install WordPress on a VPS covers the host setup, and since WordPress is PHP under the hood, the general approach to deploy a PHP site applies directly.

Ready to wire your repository to your WordPress host? Create a free DeployHQ account and connect your Git provider — start on the free plan or a 10-day trial and automate your first deployment.

If your theme has a build step — compiling Sass, bundling JavaScript, running Composer — put it in a build pipeline so the compiled assets are generated on DeployHQ's build servers and only the finished files land on production. Releases are applied as atomic deployments (the new version is swapped in as a whole, so visitors never hit a half-updated site), and if a release misbehaves you get one-click rollback to the previous version.

Keeping local Docker and production in parity

The whole exercise is worthless if local and production quietly diverge. A few habits keep them honest:

Pin the PHP version to production. If your host runs PHP 8.2, use wordpress:6.7-php8.2-apache locally — not the latest tag, which floats. A plugin that relies on a function deprecated in PHP 8.3 will pass locally on 8.2 and fail on 8.3 (or vice versa). The image tag is your version contract.

Match the database engine and major version. If production runs MySQL 8, don't develop against MariaDB 11 and assume they're identical — they diverge on JSON functions, default collations, and some SQL modes. Set the local image to whatever your host actually runs.

Never carry WP_DEBUG or dev credentials into production. The WORDPRESS_DEBUG: 1 line above is great locally and dangerous live. Configuration that differs between environments — debug flags, database credentials, API keys, salts — should come from environment variables on each host, never be baked into committed code. Keeping those inputs in sync (and separate) is exactly the discipline behind keeping development and production in sync.

Why not just Dockerize production too? It's tempting to run the same Compose stack live, but self-hosting a containerized WordPress in production means you now own database backups, TLS termination, security patching of the container host, scaling, and uptime — a real operations burden. For the vast majority of WordPress sites, a managed or VPS host plus automated Git deployment of your theme and plugin code delivers the parity benefit without the ops overhead. Keep Docker where it shines — local development — and let a purpose-built host run the live site. If you do run containers in production, our guide on how to deploy Docker containers to a VPS covers that path.

Frequently asked questions

Do I need to commit WordPress core to Git? No. Commit only the code you write — your custom theme and plugin directories, plus docker-compose.yml. WordPress core, wp-config.php, uploads, and your .env file should all be gitignored. Core is reproducible from the image; config and uploads are environment-specific.

Why is my media upload failing with a permission error locally? On Linux hosts this is almost always a UID mismatch between your host user and the container's www-data user (UID 33). Run sudo chown -R 33:33 ./wp-content on the mounted directory. macOS and Windows usually handle this automatically through Docker Desktop.

How do I reset my local database without losing my code? Run docker compose down (keeps volumes) to stop everything, then docker compose up -d to restart with data intact. Only docker compose down -v deletes the database volume. Your theme and plugin files live on your host, so they're never affected either way.

Can I use MySQL instead of MariaDB? Yes. Swap the db image for mysql:8.4 and rename the environment variables from the MARIADB_ prefix to MYSQL_ (MYSQL_DATABASE, MYSQL_USER, MYSQL_PASSWORD, MYSQL_ROOT_PASSWORD). Match whatever your production host runs.

Should I run this same Docker stack in production? For most sites, no. Self-hosting containerized WordPress means owning backups, TLS, patching, and scaling. Keep Docker for local development and deploy your theme and plugin code to a managed or VPS host from Git instead.

Wrapping up

Docker turns local WordPress development from a fragile, machine-specific chore into a reproducible environment that mirrors production. Pin your PHP and database versions to match your host, bind-mount only the theme and plugin code you author, and use WP-CLI in a container to script setup. Then let Git — not manual file transfers — carry that code to your live site.

Ready to automate the last step? Connect your repository and deploy from GitHub to server — configure your host once, and every push ships your theme and plugin changes automatically.

Questions about deploying WordPress from Git? Email us at support@deployhq.com or reach out on X.

Deploy Docker Containers to a VPS with DeployHQ Shell Servers

DeployHQ — Mon, 20 Jul 2026 13:58:49 +0000

If your application is already containerised, deploying it should be the easy part — but most teams end up wiring the same fragile bash by hand into a GitHub Action or a long-lived CI runner. This guide covers the shorter path: a Docker container deployment workflow on a VPS or dedicated server, driven by a DeployHQ Shell Server, with a Git push as the only trigger.

Shell Servers are the right starting point when you control the host. You run docker on your own box, DeployHQ runs the orchestration. If you're deploying to AWS ECS or EKS instead, hand off to the dedicated guide on deploying containerised apps to ECS and EKS — that workflow uses Custom Actions and ECR, and it covers the parts (task definitions, services-stable waits, kubectl rollout) that a Shell Server won't.

When Shell Servers fit and when they don't

Shell Servers run your script over SSH against a host you own — a Hetzner, DigitalOcean, OVH, or on-prem box with the Docker daemon installed. Nothing is uploaded; only the commands you write run remotely. That fits four very common shapes:

A single VPS running 1-10 containers behind Caddy, Traefik, or Nginx
A small Docker Compose stack (app + Postgres + Redis) that needs a coordinated restart
A self-hosted internal tool that you want updated on every push to main
A staging server where you want every PR branch to deploy automatically

It does not fit ECS, EKS, GKE, Fargate, or any managed orchestrator — those have no shell to SSH into. For those, use Custom Actions, which spin up a managed container per deploy and run AWS CLI or kubectl against the cluster API.

Prerequisites

Before the first deploy you need:

A DeployHQ account on a plan that includes Shell Servers
A Linux server (Ubuntu 22.04 LTS or 24.04 LTS recommended) reachable over SSH on port 22 (or a port you'll specify)
Docker Engine 24.0+ installed on that server. The official Docker convenience script is the fastest path; the distro-packaged docker.io lags by several releases and is missing BuildKit defaults
Docker Compose v2 if you're running multi-container stacks. It's bundled as docker compose (no hyphen) with modern Docker Engine — verify with docker compose version
The deploy user added to the docker group (sudo usermod -aG docker deploy && newgrp docker) so it can run docker without sudo
Read/write access to your container registry. For Docker Hub: a Personal Access Token, not your account password. For AWS ECR: an IAM user with ecr:GetAuthorizationToken, ecr:BatchGetImage, and ecr:PutImage
Your Git repository connected to DeployHQ — both deploy from GitHub and deploy from GitLab work the same way

The Docker cheatsheet covers the host-side commands referenced throughout this guide — docker system prune, docker image ls --filter, docker logs --since, and the diagnostic flags you'll want when a deploy goes sideways.

Step 1: Add the Shell Server to DeployHQ

Inside your project, go to Servers & Groups > New Server and pick Shell. The fields that matter:

Hostname : IP or DNS name of the box
Username : the user with docker group membership
Port : 22 unless you've moved it
SSH key : paste your project's public key into the server's ~/.ssh/authorized_keys. Password auth works but you'll regret it the first time you rotate
Working directory : where your repo will be checked out for the deploy. /srv/myapp is a reasonable convention

Smoke-test the connection with Test Connection before continuing. If it fails, 90% of the time it's Permission denied (publickey) because the key isn't in authorized_keys, or the wrong user.

Step 2: Write a Dockerfile that's actually deployable

Most Docker container deployment problems are baked in at the Dockerfile stage. The minimal Dockerfile you find on Docker's getting-started page works for docker run on your laptop, but it has three problems that show up on the second deploy.

Here's a production-leaning Dockerfile for a Python Flask app. The patterns are the same for Node, Ruby, Go, or Java — only the base image and dependency-install commands change.

# syntax=docker/dockerfile:1.7
FROM python:3.12-slim AS base

# Don't run as root in the container
RUN useradd --create-home --uid 1000 app

WORKDIR /app

# Install deps separately from app code so the layer caches across deploys
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

# Now copy application code — invalidates only when code changes
COPY --chown=app:app . .

USER app

EXPOSE 5000

# tini handles SIGTERM properly; without it `docker stop` SIGKILLs after 10s mid-request
ENTRYPOINT ["/usr/bin/tini", "--"]
CMD ["python", "app.py"]

The three fixes most starter Dockerfiles get wrong:

COPY requirements.txt before COPY . . — keeps the dependency layer cached. Without it, pip install re-runs on every code change, turning 10-second builds into 90-second ones
A non-root app user with USER app — if your app process is compromised, the blast radius is the container's filesystem, not root in the container
tini as the entrypoint — Python and Node don't forward SIGTERM to child processes, so docker stop waits 10 seconds then SIGKILLs mid-request. tini is a 220KB init that reaps zombies and forwards signals correctly

The full pattern for Node, including multi-stage builds and the .dockerignore that goes with it, is in the production-ready Node.js Dockerfile walkthrough.

Build and test locally before pushing — if it doesn't run on your laptop, the registry push is wasted work:

docker build -t myapp:dev .
docker run --rm -p 5000:5000 myapp:dev

Step 3: Push to a container registry

Your Shell Server pulls the image; it doesn't build it. That means the build either happens (a) on a DeployHQ build pipeline before the Shell Server step runs, or (b) on the Shell Server itself if it has spare CPU and RAM. Build pipelines are the cleaner pattern because they decouple build from deploy and surface failures earlier — see what a build pipeline actually does for the model.

Tag with the Git commit SHA — never with :latest alone:

# In a DeployHQ build pipeline, ${REVISION} is the commit SHA
IMAGE=myorg/myapp:${REVISION}

docker login --username myorg --password-stdin <<< "${DOCKERHUB_TOKEN}"
docker build -t $IMAGE -t myorg/myapp:latest .
docker push $IMAGE
docker push myorg/myapp:latest

Why both tags? :${REVISION} is what you pull on the Shell Server (immutable, traceable, rollback-friendly). :latest is what your local docker compose pull grabs for development. If you only push :latest, you've thrown away your rollback target — a 30-second incident becomes a 30-minute one.

Set DOCKERHUB_TOKEN, AWS_ACCESS_KEY_ID, and any other secrets as environment variables in Project Settings > Environment Variables , marked as protected so they don't leak into logs. If you need encrypted-at-rest secrets you can commit alongside your repo, the Dotenvx encrypted env workflow handles that without a second secrets store. For AWS ECR registries, the login is a one-liner — see the AWS CLI cheatsheet for the exact aws ecr get-login-password invocation and the surrounding session patterns.

Step 4: The Shell Server deploy script

This is the only script you actually maintain. It runs on the target host as the deploy user, with the repo not uploaded — the Shell Server runs commands, it doesn't transfer files. Anything you need from the repo (a docker-compose.yml, Kubernetes manifests, migration scripts) either lives on the box already, gets fetched by the script, or comes from your registry inside the image.

For a single-container app:

#!/bin/bash
set -euo pipefail

IMAGE="myorg/myapp:${REVISION}"
CONTAINER=myapp

echo "Pulling $IMAGE..."
docker pull "$IMAGE"

echo "Stopping previous container (if any)..."
docker rm -f "$CONTAINER" 2>/dev/null || true

echo "Starting new container..."
docker run -d \
  --name "$CONTAINER" \
  --restart unless-stopped \
  -p 5000:5000 \
  --env-file /etc/myapp/.env \
  "$IMAGE"

echo "Waiting for health check..."
for i in {1..30}; do
  if curl -fsS http://localhost:5000/healthz >/dev/null; then
    echo "Healthy after ${i}s"
    docker image prune -f --filter "until=72h" >/dev/null
    exit 0
  fi
  sleep 1
done

echo "Health check failed — rolling back"
docker rm -f "$CONTAINER"
docker run -d --name "$CONTAINER" --restart unless-stopped \
  -p 5000:5000 --env-file /etc/myapp/.env "myorg/myapp:previous"
exit 1

Two details to call out:

The 30-second health-check loop turns this from did the container start (always true) into is the new revision serving traffic. Without it DeployHQ will report success even when the app is crash-looping. The loop is the same shape as the services-stable wait that ECS gives you for free
docker image prune --filter "until=72h" keeps the disk from filling up with old image layers. Three days is enough to roll back to anything from the last week's deploys; tighten or loosen as your disk allows

For a Compose stack, the deploy is docker compose pull && docker compose up -d --remove-orphans — Compose handles the container churn and respects depends_on and health checks defined in the YAML. Keep the YAML in /srv/myapp/docker-compose.yml on the server, version-controlled separately or synced via a build pipeline.

Start the deploy script with set -euo pipefail. Without it, a failed docker pull (image not found, registry down) returns non-zero, your script keeps going, and the next docker run happily starts the previous image — silent rollback to yesterday's bug. set -e makes the script halt on the first failure; -u catches undefined variables; -o pipefail propagates exit codes through pipes.

Step 5: Automate on every push

The whole point of this setup is that you don't run anything manually after the first deploy. In Project Settings > Automatic Deployments , enable deployment for the branch (main for production, staging for staging) and copy the webhook URL into your GitHub or GitLab repository's Settings > Webhooks. The GitHub webhook setup guide walks through the exact steps; GitLab is identical in shape.

From here, the full loop is: git push → DeployHQ runs the build pipeline (image build + push to registry) → DeployHQ runs the Shell Server script (pull + restart + health check) → success or one-click rollback on the dashboard if the health check failed.

Need to verify your project's deployment safety story before going live? Sign up for DeployHQ and run the first deploy against a staging server — the free tier includes one project and unlimited deploys, which is enough to wire up the full pipeline before you commit.

Production gotchas this workflow doesn't solve

Shell Server deployments are good but they aren't free of trade-offs. Three you'll hit:

No automatic blue/green. The script above stops the old container and starts the new one, with a few seconds of 502 in between unless your reverse proxy (Caddy, Traefik, Nginx) has retry-on-fail configured. For real zero-downtime on a single host, run two container versions side by side behind the proxy and flip the upstream — covered in the zero-downtime deployments feature page
No horizontal scale. One host, one running version. For multi-host orchestration, ECS/EKS or a managed Kubernetes is the right next step
State management is on you. Volumes, named volumes vs bind mounts, Postgres data outside the container — Docker doesn't help you here. The deploy script must never destroy a volume on rollback. Use docker volume ls to audit what's persistent before automating

If you want a worked Compose example end-to-end on Ubuntu, the Metabase Docker Compose walkthrough covers the YAML, the systemd unit, and the same Shell Server deploy script applied to a multi-container stack.

Conclusion

Docker container deployment with a DeployHQ Shell Server replaces three things at once: the GitHub Action that's almost-but-not-quite right, the EC2 runner that nobody patches, and the bash one-liner in someone's terminal that nobody else can reproduce. You write one script, the Shell Server runs it on every push, the build pipeline keeps your image immutable per commit, and rollback is a single click. That's the workflow.

For the Docker primer if any of this felt like a fast skim, see what Docker is and how containers, images, and registries fit together. For the orchestrator-side command reference when you graduate to Kubernetes, the kubectl cheatsheet is the page to bookmark.

Questions or running into a deploy that won't behave? Email us at support@deployhq.com or ping us on X (Twitter).

FAQs

What's the difference between a DeployHQ Shell Server and a Custom Action for Docker deployments?

A Shell Server runs your script over SSH on a host you own — your Hetzner box, your bare-metal server, your home lab. A Custom Action runs in a managed container that DeployHQ spins up per deploy, with no persistent host to maintain — that's what you use for ECS, EKS, or anywhere there's no SSH-able machine. Shell Servers fit single-VPS and small Compose stacks; Custom Actions fit cloud-native orchestrators.

Why tag images with the commit SHA instead of `:latest`?

Because rollback is then a single docker pull myorg/myapp:<previous-sha> && docker run ... against a specific, named image. With :latest-only, the previous version has been overwritten in the registry and there's nothing to roll back to. Tagging with ${REVISION} (the commit SHA) gives you an immutable per-deploy artefact that pairs with the rollback button on the DeployHQ dashboard.

Do I need a build pipeline, or can the Shell Server build the image too?

Either works. The Shell Server can run docker build and docker push if it has spare CPU and RAM. A build pipeline is cleaner because it decouples build from deploy — the build runs on DeployHQ's infrastructure, the deploy runs on your server, and a build failure never touches the production host. For production setups, prefer the build pipeline.

How do I keep registry credentials out of my repo?

Store them as Environment Variables under Project Settings , marked as protected. They get injected into the build pipeline and Shell Server session at deploy time. Never commit .env files, Docker config JSON, or AWS credentials into the repo — even private repositories leak via forks, mistakes, and git log --all.

Can I deploy Docker Compose stacks the same way?

Yes — replace the docker run step in Step 4 with docker compose pull && docker compose up -d --remove-orphans. Keep the docker-compose.yml on the server (in the working directory you configured for the Shell Server) and let the script trigger Compose to reconcile. The same health-check loop applies — wait for the new containers to be healthy before reporting success.

DeployHQ Managed VPS vs Render: Real Linux vs PaaS Sandbox

DeployHQ — Mon, 13 Jul 2026 08:49:34 +0000

DeployHQ Managed VPS and Render solve the same problem — get an app from a Git repository to a running production service — but they take opposite architectural bets. Render is fully managed PaaS: containers, autoscaling, managed databases, zero infrastructure decisions. DeployHQ Managed VPS is a real Linux box with full SSH access plus the deployment pipeline wired in.

The right choice depends on whether your workload needs real Linux (custom services, SSH access, anything outside a PaaS sandbox) or whether the PaaS abstraction's constraints are actually freedoms — fewer decisions to make, less operational surface to maintain.

This guide is a head-to-head comparison: features, pricing, lock-in, and when each one wins. (For broader Heroku-replacement framing — Render alongside Railway and Fly.io — our Heroku alternatives in 2026 roundup covers the wider migration story.)

TL;DR

If your application fits a PaaS shape — stateless web service, managed Postgres, autoscaling on CPU thresholds, no need to SSH into the box — Render is the cleaner answer. The PaaS model removes a meaningful amount of operational work, and Render's product surface is mature and well-designed.

If you need a real Linux box — for SSH access, custom services, cron jobs, third-party agents (monitoring, log shipping, backups), or any workload that needs to step outside a sandbox — DeployHQ Managed VPS is the right product. You get a real Ubuntu VPS plus the DeployHQ deployment pipeline already wrapped around it.

For broader context, our roundup of the best software deployment tools in 2026 places Render, DeployHQ, and the rest of the category side by side.

At a glance: feature comparison

Capability	DeployHQ Managed VPS	Render
Architectural model	Linux VPS + deployment pipeline	PaaS containers + managed services
Root SSH access	Yes	No (PaaS sandbox)
Custom services / cron / daemons	Yes (it's a real Linux box)	Cron jobs supported; custom binaries limited
Underlying infrastructure	DigitalOcean	AWS / GCP
Server sizes	1-2 vCPU / 1-4 GB (beta)	Container instances (Starter, Standard, Pro tiers)
Autoscaling	No (manual sizing)	Yes (CPU / memory thresholds)
Managed databases bundled	No (run your own or use external)	Yes (managed Postgres, Redis)
Build pipeline	DeployHQ generic pipeline	Render native build
Deploy other targets in same project	Yes (VPS, static, shared, S3)	No (Render-only)
One bill with deployment tool	Yes	Yes (Render bundles both)
Beta status	Yes (mid-2026)	GA
Vendor lock-in	Low (it's just Linux + SSH)	Medium-high (PaaS runtime + service bindings)

Real Linux on one side. PaaS sandbox on the other.

When DeployHQ Managed VPS is the right choice

You need SSH access to a real Linux box. This is the structural differentiator and it's where most I can't use Render for this decisions land. If your app needs to install system packages, run a background worker outside Render's supported types, set up a custom cron schedule with unusual semantics, run a third-party monitoring or log-shipping agent, or debug live with strace / tcpdump / journalctl, PaaS locks you out. DeployHQ Managed VPS gives you root over SSH and you do whatever Linux lets you do. The Managed VPS pillar guide walks through what you get out of the box.

You want a generic deployment pipeline that ships to many targets. Render's build-and-deploy is specific to Render — it builds, runs, and serves your code on Render. DeployHQ's pipeline ships any artifact to any target — Managed VPS, your own Hetzner box, DigitalOcean Droplets, shared hosting, S3 buckets, DeployHQ Static Hosting. If your project has any non-PaaS-shaped component (a worker that needs root, a static frontend you want on a separate edge, a service that has to live on shared hosting because compliance), DeployHQ handles all of it. Render handles the Render-shaped part.

You don't want PaaS lock-in on your runtime. Render's value-adds — managed Postgres bound to the app, autoscaling on dedicated tiers, the Render runtime conventions — are tightly coupled to staying on Render. If you outgrow Render's constraints or pricing, migration means re-architecting around a different runtime. DeployHQ Managed VPS runs stock Linux — your app already works anywhere Linux runs.

You want to mix targets in one project. A real example: production web on Managed VPS, background jobs on a separate Managed VPS or BYO VPS, static frontend on Static Hosting, all in one DeployHQ project with one billing relationship. Render can't host the static frontend at scale (Render Static Sites exists but lives in the Render ecosystem) and can't deploy to non-Render targets. DeployHQ handles all of it from one project.

When Render is the right choice

You don't want to manage Linux at all. Render is genuine PaaS — no OS to patch, no security updates to apply, no system packages to manage. If I don't want to think about the box, I just want to push code describes your team, Render delivers that cleanly. DeployHQ Managed VPS is less operational work than a raw VPS, but it's still a Linux box; if you'd rather not have that surface, Render's abstraction is what you want.

You need autoscaling. Render's dedicated tiers offer autoscaling on CPU and memory thresholds. DeployHQ Managed VPS is manually sized — pick a tier, resize as needed. If your workload spikes unpredictably and you want the platform to absorb it without intervention, Render is the right answer.

You want managed databases bundled in. Render offers managed Postgres and Redis with private networking, automatic backups, point-in-time recovery, and bindings into your app. DeployHQ Managed VPS doesn't bundle a database — you'd run Postgres yourself on the VPS (fine for many workloads), use a separate managed service (Neon, Supabase, DigitalOcean Managed Databases), or self-host in a separate VPS.

Your workload genuinely fits the PaaS shape. Stateless web service, reads from a managed database, writes to object storage — the canonical PaaS shape. If that describes your app and you don't need to step outside it, Render's constraints aren't really constraints. The simplicity is a feature.

Pricing: side by side

As of June 2026 — check vendor pages for current numbers.

Render offers a Free tier (with limitations: services sleep after idle, build minute caps, single concurrent build), then paid web service tiers starting from a Starter price point and scaling up to dedicated instances with autoscaling. Managed Postgres starts free with row limits and scales up with paid tiers offering increased storage and high availability. The current exact tier pricing is best checked directly on render.com — Render adjusts pricing periodically and a stale number here is worse than no number.

What's worth noting structurally: Render's pricing scales with usage in a few dimensions — instance size, instance count (for autoscaling), database tier, bandwidth, and additional service slots. For a single small web service plus a small database, Render is competitive with other PaaS options. For larger workloads with several services and a HA database, the bill can scale quickly.

DeployHQ Managed VPS charges a fixed monthly rate per server, shown on the provisioning form in your account's currency. Server sizes are currently 1 vCPU / 1 GB up to 2 vCPU / 4 GB in the beta. Pricing rolls into your DeployHQ plan on a single monthly invoice. Trial accounts can provision one Managed VPS at the smallest size at no charge.

The honest framing: a single small Render web service plus a small managed DB can be cheaper than DeployHQ Managed VPS plus a separately hosted Postgres if you only have one app. The math tilts toward DeployHQ when you have multiple deployment targets (one project deploying to multiple servers) or you're already paying for DeployHQ to deploy code elsewhere. Compare current DeployHQ pricing for the full breakdown.

Moving between them (it's not all-or-nothing)

Different architectural models means migration involves real work in either direction — not just DNS swaps.

From Render to DeployHQ Managed VPS: provision the VPS in DeployHQ, install your app's runtime (Node, Ruby, Python, Go — whatever Render was running), set up your service supervisor (systemd, PM2, Passenger), migrate your managed Postgres data to either a self-hosted Postgres on the same VPS or a separate managed-DB provider, and configure DeployHQ's pipeline to handle build + deploy. If Render was handling autoscaling for you, you'll either manually size the VPS for peak load or move to a different scaling model (load balancer + multiple VPS instances). The migrating to DeployHQ guide covers the broader migration pattern.

From DeployHQ Managed VPS to Render: re-architect around Render's runtime conventions. Define your render.yaml service spec, set up managed-DB bindings, adapt any custom services to Render-supported types. If your app used SSH-only operations (cron jobs with unusual semantics, custom binary execution, monitoring agents), find PaaS-compatible alternatives. This is harder in practice than the other direction because you're moving toward a more constrained runtime.

Or: combine them. Run web tier on Render for autoscaling and managed DB, run worker processes or background jobs on a DeployHQ Managed VPS where you can install whatever you need, and keep both in one DeployHQ project for unified deployment of the worker side. This combines the autoscaling story (Render) with the real-Linux story (DeployHQ Managed VPS) — both architectures get used for what they're good at.

If you're stepping up from shared hosting and weighing modern deployment options generally, 5 signs it's time to upgrade from shared hosting to automated deployments covers the inflection points.

The real Linux vs PaaS trade-off

Both products solve the deployment problem. They solve it for different application shapes.

Render is excellent for canonical PaaS workloads — stateless web services, standard runtimes, managed databases. It removes operational work in exchange for runtime constraints. Most CRUD apps fit this shape comfortably.
DeployHQ Managed VPS is excellent when the PaaS shape doesn't fit — when you need root access, custom services, third-party agents, or any workload that needs to step outside a sandbox. It's a real Linux box with deployment automation wrapped around it.

The honest answer for many teams is both. Run the canonical web tier on Render for the autoscaling and managed-DB ergonomics. Run the worker/cron/agent side on a Managed VPS where you can do whatever Linux lets you do. Use DeployHQ as the unifying deployment surface for whatever you put on the VPS side. The application splits along architectural lines instead of along vendor lines.

For Express / Node service deployments specifically, both platforms handle Node well — the choice comes down to whether you want the runtime managed for you or you want SSH into the box.

For the wider catalog of where Managed VPS fits with other DeployHQ hosting options, the hosting hub covers all five hosting types.

FAQ

Does DeployHQ Managed VPS allow SSH access like a regular VPS?Yes. It's a real Linux VPS. SSH in with the key DeployHQ generates (or your own key), install what you want, run any service. DeployHQ's deployment pipeline handles the build-and-deploy automation but doesn't restrict what runs on the box.

Does Render allow SSH access? No. Render is PaaS — you interact with the platform through its dashboard, CLI, and API. SSH into a running container isn't supported. This is by design — it's what makes the PaaS abstraction work.

Can I run a Laravel deployment on DeployHQ Managed VPS?Yes. PHP-FPM, Nginx, Composer, queue workers via Supervisor, Laravel scheduler via cron — all standard Linux setup. DeployHQ handles the build (Composer install, migrations, asset compilation), the VPS handles the runtime.

What about managed Postgres on DeployHQ Managed VPS?Not bundled. For small workloads, install Postgres on the VPS itself. For HA / point-in-time recovery / managed backups, point at a separate managed-DB service. DigitalOcean Managed Databases pairs well since the VPS is already on DO.

Is there a free tier on DeployHQ Managed VPS?Trial accounts can provision one Managed VPS at the smallest size at no charge. Custom SSH keys aren't available on trial; DeployHQ generates and uses a managed key automatically. Render has a free web service tier (with idle-sleep limitations) and free DB tier — both are useful for evaluation but typically not for production.

Get started

If you're already on DeployHQ, enable beta features under Settings > Beta Features and add a Managed VPS server to any project. The one-click rollback feature works on Managed VPS the same way it works on a BYO server.

If you're new, start a free trial and the included Managed VPS lets you ship a real project end-to-end before committing. For the wider picture of how Managed VPS fits with the other hosting options DeployHQ supports, see your universal deployment and hosting platform.

Render and DeployHQ Managed VPS are both good products in their lanes. Render wins when your workload fits PaaS. DeployHQ Managed VPS wins when it doesn't — or when you want real Linux for any reason. The split is structural, not feature-level; pick the architecture, not the feature list.

For more detail on the Managed VPS product, the Managed VPS support library has the full provisioning, lifecycle, and management documentation.

Questions or feedback on Managed VPS vs Render? Email support@deployhq.com or follow @deployhq on X for product updates.

Using Claude Code with SQLite: The Safest Way to Prototype Queries Locally

DeployHQ — Mon, 13 Jul 2026 08:49:24 +0000

Most guides about connecting an AI coding assistant to a database start with the hard case: a production Postgres cluster, credentials, network access, read-only roles. That is exactly backwards. If you are just getting comfortable with letting an assistant explore a schema and draft SQL for you, the smartest place to start is the database that lives entirely inside a single file on your laptop.

SQLite is that database. There is no server to run, no port to open, no user to grant. The whole thing is one .sqlite file you can open, copy, delete, and restore in seconds. That makes it the ideal sandbox for AI-assisted database work — a place where a bad query or a botched schema change costs you nothing, because rolling back is as simple as copying a file back over another one.

This post walks through pointing Claude Code at a local SQLite file, why a file-based database is the safest experimentation surface you can give an AI assistant, and how to prototype real queries before promoting anything to a server.

Why SQLite is the right place to start

Every other database engine assumes infrastructure. PostgreSQL and MySQL run as long-lived server processes, listen on a network port, and gate access behind users and roles. That is the correct model for production — but it is a lot of moving parts to stand up just to experiment with an AI assistant.

SQLite removes all of it. A SQLite database is a single ordinary file. Your application (or your assistant's tooling) opens the file directly and reads and writes rows in place. There is no daemon, no localhost:5432, no authentication handshake. If you have ever seen a .db or .sqlite file in a project, you have already been using it.

For AI-assisted work, three properties matter:

It is trivially reproducible. Delete the file, run your seed script, and you are back to a known state. No DROP DATABASE, no re-provisioning.
It is completely local. Nothing leaves your machine. There is no risk of an assistant accidentally touching shared staging data because there is no shared anything.
It is disposable by design. A SQLite file is meant to be copied, moved, and thrown away. That disposability is what turns it into a safe playground.

If you want the deeper trade-offs between the engines, the SQLite vs PostgreSQL vs MySQL comparison covers when each one earns its place. For learning the AI workflow, SQLite wins on setup cost alone.

Pointing Claude Code at a `.sqlite` file

Claude Code talks to databases through an MCP server — a small bridge process that exposes your database to the assistant as a set of tools. If the term is new, the complete guide to MCP servers explains what they are and why they matter. The one we use here is DBHub, and the full multi-engine setup lives in the step-by-step guide to querying databases with Claude Code and DBHub — this post won't re-run that whole setup, just the SQLite-specific piece.

DBHub supports SQLite directly, and the SQLite DSN is refreshingly short. Where Postgres needs a host, port, user, password, and database name, SQLite needs a path to a file:

sqlite:///./mydb.sqlite

That is the entire connection string. The sqlite:// scheme followed by a path — three slashes for a relative path, four for an absolute one like sqlite:////Users/you/data/mydb.sqlite.

In your Claude Code MCP configuration, DBHub takes that DSN as its --dsn argument:

{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub",
        "--transport", "stdio",
        "--dsn", "sqlite:///./mydb.sqlite"
      ]
    }
  }
}

Restart Claude Code, and it can now see your SQLite file's tables and columns. If you don't have a database to point at yet, DBHub also ships a demo mode that spins up an in-memory SQLite database, so you can kick the tires before pointing it at anything of your own. Keeping the exact DBHub flags handy is easier with the Claude Code cheatsheet open in another tab.

Why a file is the safest sandbox you can give an AI

Here is the property that makes SQLite genuinely different for AI-assisted work, not just easier to set up: your entire database is one file, so a complete backup is one copy command.

cp mydb.sqlite mydb.backup.sqlite

That single line is your rollback plan. Before you let the assistant run anything destructive — an ALTER TABLE, a bulk UPDATE, a schema rewrite it suggested — you copy the file. If the change goes sideways, you restore it:

cp mydb.backup.sqlite mydb.sqlite

You are back exactly where you started, byte for byte. There is no migration to reverse, no pg_restore, no hope the transaction rolled back cleanly. The safety net is the filesystem itself.

This changes how you can work with an assistant. On a shared server you approach every write cautiously, because a mistake affects other people and is annoying to undo. Against a copied SQLite file, you can be reckless on purpose: let the assistant try an aggressive denormalization, ask it to rewrite five tables, tell it to backfill a column three different ways and compare. Every experiment starts from a fresh copy and ends with a cp if it didn't pan out.

Prototype fearlessly, then promote deliberately. The whole point of a disposable local database is that undo is free — so use it to move fast locally, and save the careful, reviewed process for the moment your changes touch a real server. Start free with DeployHQ when you're ready to put a proper deployment pipeline behind those changes.

A good habit is one backup per experiment: copy the file, name the copy after what you're about to try (mydb.pre-index-test.sqlite), and keep the ones that produced results worth revisiting. Disk is cheap; a lost afternoon of exploration isn't.

Exploring schema and prototyping queries

With the file connected and a backup in your pocket, the workflow becomes conversational. Instead of memorizing table names, you ask.

Start by mapping the territory. Ask the assistant to describe the schema — tables, columns, types, foreign keys. Because DBHub exposes the structure as tools, Claude Code reads it directly rather than guessing, so what it tells you reflects the actual file, not a hallucinated model of it.

Then prototype against real shape. Describe what you want in plain English — show me the ten customers with the most orders in the last quarter — and let the assistant draft the SQL. Run it, read the result, and refine. Because you're working on a copy, you can run the query, realize the join is wrong, and iterate without any consequence beyond a few seconds.

Test schema changes the same way. Ask for an index, a new column, or a normalized table split, apply it to your working copy, and check whether queries behave the way you expected. If the change made things worse, restore the backup and try a different shape. This tight loop — propose, apply, inspect, keep-or-revert — is the core value of a disposable database.

A few practices keep the exploration honest:

Read the SQL before you run it. The assistant is drafting, not deciding. Skim every statement, especially anything that writes.
Back up before writes, not before reads. Selects can't hurt the file; UPDATE, DELETE, and ALTER can.
Seed deterministically. Keep a small script that rebuilds your test data so start over is always available.

The moment you point an assistant at a networked, multi-user database instead of a local file, that cp safety net disappears — which is exactly when you want to lock the connection down. Our guide to read-only guardrails for AI database access covers the dedicated-role and MCP-flag recipe that keeps a shared database as safe as a throwaway file.

When to graduate from SQLite

SQLite is a superb sandbox and a perfectly good production database for plenty of workloads — but there is a point where you outgrow it. Move to PostgreSQL or MySQL when you need real concurrency (many clients writing at once), network access from multiple application servers, or engine-specific features SQLite doesn't offer. The comparison linked earlier lays out exactly where each of those lines sits.

The reassuring part: the workflow you just learned transfers cleanly. Pointing Claude Code at Postgres or MySQL through DBHub is the same pattern, only the DSN changes from a file path to a host, port, and credentials (and MySQL adds a few connection quirks of its own). What you can't carry over is the cp-based safety net — which is precisely why doing your schema and query experimentation on SQLite first is worth it. You work out the shape where mistakes are free, and only take the validated result to an engine where they aren't.

Moving validated queries into a real deployment

Once a schema change or a set of queries has proven itself against your local file, it needs a disciplined path to production — because on a live database, the free-rollback luxury is gone. That is where the process flips from experiment freely to change carefully.

The safe pattern is to capture the validated change as a versioned migration and apply it as part of your deployment, not by hand. Our guide on how to handle database changes during a deployment covers version-controlling schema changes and running them automatically, and the deeper database migration strategies for zero-downtime deployments walks through applying those changes without taking the application offline.

DeployHQ fits at exactly this handoff. A build pipeline can run your migration step as part of every deploy, so the schema change you prototyped locally on SQLite ships the same way your code does — reviewed, versioned, and repeatable — instead of someone SSHing in to run SQL by hand. The local file gave you a place to be fearless; the pipeline gives you a place to be careful.

That is the arc of AI-assisted database work done well: experiment where undo is free, promote where it isn't, and never confuse the two. SQLite is where you start precisely because it makes the first half of that sentence effortless.

Ready to put a proper deployment pipeline behind your validated schema changes? Explore automated deployment for your stack and run your migrations automatically on every deploy.

Questions or feedback? Reach us at support@deployhq.com or on X at @deployhq.

Running AI Coding Agents in CI/CD: Claude Code, Codex, and Gemini CLI in Headless Mode

DeployHQ — Fri, 10 Jul 2026 14:47:36 +0000

This is Part 10 of our series on AI coding assistants for developers. See also: Agentic Workflows Explained and Comparing AI CLI Coding Assistants.

GitHub's Copilot Coding Agent is convenient — assign an issue and it opens a PR. But it's a black box. You don't choose the model, you can't add custom tools, and you're locked into GitHub's pricing and rate limits.

There's another way: run the same AI coding CLIs you use locally — Claude Code, Codex CLI, and Gemini CLI — as headless steps in your CI/CD pipeline. You control the prompt, the model, the tools, and the cost. The agent runs non-interactively, produces output, and the pipeline decides what to do with it.

This is the bring your own agent approach. It works on any CI platform that can run a shell command.

Headless Mode for Each CLI

Each tool has a way to run without interactive input — no terminal UI, no approval prompts, just input and output.

Claude Code

# Print mode — runs a single prompt, outputs result, exits
claude -p "Analyze the git diff and generate a changelog entry" \
  --allowedTools Edit,Write,Bash \
  --output-format json

# With stdin piping
git diff HEAD~1 | claude -p "Generate a changelog entry for these changes" \
  --output-format text

# With max tokens to control cost
claude -p "Fix the failing test in tests/auth.test.ts" \
  --allowedTools Edit,Read,Bash \
  --max-turns 10

Key flags: -p (print mode, non-interactive), --allowedTools (restrict what the agent can do), --output-format (json or text), --max-turns (limit iterations).

Codex CLI

# Full auto mode — no human approval needed
codex --approval-mode full-auto \
  --quiet \
  "Update the README with the latest API changes"

# With file restrictions
codex --approval-mode full-auto \
  --quiet \
  --full-auto-error-mode ask-user \
  "Add input validation to the user registration endpoint"

Key flags: --approval-mode full-auto (no interactive prompts), --quiet (minimal output).

Gemini CLI

# Non-interactive with prompt
echo "Generate unit tests for src/utils/validator.ts" | gemini

# With sandbox mode
gemini -s "Review the last commit for security issues" \
  --sandbox

Practical Use Cases with Full CI Config

1. Auto-Generate Changelog from Git Diff

The agent reads the diff since the last release tag and writes a human-readable changelog entry:

name: Generate Changelog

on:
  push:
    tags: ['v*']

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Generate changelog entry
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          PREV_TAG=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo "")
          DIFF=$(git log ${PREV_TAG}..HEAD --oneline --no-merges)

          echo "$DIFF" | claude -p "Generate a changelog entry in Keep a Changelog format. Group changes into Added, Changed, Fixed, Removed. Be concise — one line per change. Output only the changelog markdown, nothing else." \
            --output-format text > CHANGELOG_ENTRY.md

      - name: Create release with changelog
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh release create ${{ github.ref_name }} \
            --title "${{ github.ref_name }}" \
            --notes-file CHANGELOG_ENTRY.md

2. AI-Powered Code Review on Changed Files

Run the agent as a review step on every PR — it reads the diff and leaves comments:

name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run AI review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          DIFF=$(gh pr diff ${{ github.event.pull_request.number }})

          REVIEW=$(echo "$DIFF" | claude -p "Review this diff for:
          1. Security issues (SQL injection, XSS, hardcoded secrets)
          2. Missing error handling
          3. Performance concerns (N+1 queries, unnecessary loops)
          4. Missing input validation

          Format as a markdown list. If no issues found, say 'No issues found.' Be specific — reference file names and line numbers." \
            --output-format text \
            --max-turns 3)

          gh pr comment ${{ github.event.pull_request.number }} \
            --body "## AI Code Review

          $REVIEW

          ---
          *Automated review by Claude Code. This is advisory — human review is still required.*"

Once an agent produces a change that passes review, the last mile is shipping it. Wire your CI into an automated build pipeline and a green run deploys to your own server automatically — the agent writes, CI validates, and the release goes out with no manual step in between.

3. Auto-Fix CI Failures

When tests fail, the agent reads the error output and proposes a fix:

name: Tests with Auto-Fix

on:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci
      - name: Run tests
        id: tests
        continue-on-error: true
        run: npm test 2>&1 | tee test-output.txt

      - name: AI fix attempt
        if: steps.tests.outcome == 'failure'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npm install -g @anthropic-ai/claude-code

          claude -p "The tests failed. Here's the output:

          $(cat test-output.txt)

          Read the failing test files and the source code they test.
          Fix the source code to make the tests pass.
          Do NOT modify the test files — fix the implementation." \
            --allowedTools Read,Edit,Bash \
            --max-turns 15

      - name: Verify fix
        if: steps.tests.outcome == 'failure'
        run: npm test

      - name: Commit fix
        if: steps.tests.outcome == 'failure'
        run: |
          git config user.name "AI Agent"
          git config user.email "ai-agent@deployhq.com"
          git add -A
          git diff --staged --quiet || git commit -m "fix: auto-fix failing tests (AI-generated)"
          git push

4. Security Scanning with AI Triage

Run a SAST tool, then have the AI prioritize and explain findings:

name: Security Scan + AI Triage

on:
  pull_request:

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Semgrep
        run: |
          pip install semgrep
          semgrep --config auto --json --output semgrep-results.json . || true

      - name: AI triage
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npm install -g @anthropic-ai/claude-code

          TRIAGE=$(claude -p "Here are Semgrep security scan results:

          $(cat semgrep-results.json)

          Triage these findings:
          1. Remove false positives (explain why)
          2. Rank remaining issues by severity (Critical, High, Medium, Low)
          3. For each real issue, explain the attack vector in one sentence
          4. Suggest a fix for Critical and High issues

          Format as a markdown table." \
            --output-format text \
            --max-turns 3)

          echo "$TRIAGE" >> $GITHUB_STEP_SUMMARY

5. Generate Tests for Modified Code

When a PR changes source files, the agent generates missing tests:

name: Auto-Generate Tests

on:
  pull_request:

jobs:
  generate-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Generate tests for changed files
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          CHANGED=$(gh pr diff ${{ github.event.pull_request.number }} --name-only | grep -E '\.(ts|js)$' | grep -v test | grep -v spec)

          for FILE in $CHANGED; do
            TEST_FILE=$(echo "$FILE" | sed 's/\.ts$/.test.ts/' | sed 's|src/|tests/unit/|')

            if [! -f "$TEST_FILE"]; then
              claude -p "Read $FILE and generate a comprehensive unit test file.
              Use Vitest. Follow the existing test patterns in the project.
              Save the test file to $TEST_FILE.
              Test all exported functions including edge cases." \
                --allowedTools Read,Write \
                --max-turns 10
            fi
          done

      - name: Verify tests pass
        run: npm test

      - name: Commit generated tests
        run: |
          git config user.name "AI Agent"
          git config user.email "ai-agent@deployhq.com"
          git add tests/
          git diff --staged --quiet || git commit -m "test: add AI-generated tests for new code"
          git push

Other CI Platforms

The same patterns work on any CI platform:

GitLab CI:

ai-review:
  stage: review
  image: node:20
  script:
    - npm install -g @anthropic-ai/claude-code
    - git diff origin/main...HEAD | claude -p "Review this diff for bugs and security issues" --output-format text > review.md
    - cat review.md
  artifacts:
    reports:
      dotenv: review.md
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY

Bitbucket Pipelines:

pipelines:
  pull-requests:
    '**':
      - step:
          name: AI Code Review
          image: node:20
          script:
            - npm install -g @anthropic-ai/claude-code
            - git diff origin/main...HEAD | claude -p "Review for security issues" --output-format text

Connecting to Deployment

After the agent's changes pass CI, you can trigger a deployment automatically using the DeployHQ CLI:

- name: Deploy to Staging
  if: success()
  run: |
    curl -fsSL https://www.deployhq.com/install-cli.sh | bash
    dhq auth login --token "${{ secrets.DEPLOYHQ_API_KEY }}"
    dhq deploy --server staging --wait --json

This completes the loop: agent writes code → CI validates → agent fixes failures → the deployment pipeline ships it. The full pattern is covered in our companion post on connecting agentic CI/CD to DeployHQ.

Cost Management

Running AI agents in CI can get expensive fast. Here's how to keep costs under control:

Strategy	How	Savings
Limit turns	`--max-turns 10`	Prevents infinite loops
Restrict tools	`--allowedTools Read,Edit`	Fewer API calls per turn
Filter triggers	Only run on `src/` changes	Skip docs-only PRs
Use cheaper models	Claude Haiku for simple tasks	10x cheaper than Opus
Cache results	Skip review if diff unchanged	Eliminates duplicate runs
Set timeouts	`timeout-minutes: 10`	Hard stop on runaway agents

A typical AI review step costs $0.02-0.10 per PR with Claude Sonnet. Auto-fix attempts cost more ($0.20-1.00) because the agent reads files and makes multiple edits. Budget accordingly — for most teams, this is cheaper than the developer time it saves.

Security Considerations

Running an AI agent in CI means giving it access to your code and (potentially) your secrets. Lock it down:

Scope secrets tightly. The agent needs an API key for its model provider. It does NOT need your database credentials, deployment tokens, or SSH keys. Use GitHub's environment-level secrets to control access.
Restrict file access. Use --allowedTools to prevent the agent from running arbitrary shell commands. Read,Edit is sufficient for most review tasks.
Validate output. Don't blindly commit agent-generated changes. Run your full test suite after any agent modification.
Audit agent commits. Tag agent-generated commits with a machine author (ai-agent@yourcompany.com) so they're easy to identify in git history.
Don't run agents on forks. Disable AI review steps on PRs from forked repositories — the fork author could craft a prompt injection in the diff.

When to Use What

Approach	Best For	Trade-offs
Platform agent (Copilot)	Issue-to-PR automation, managed infrastructure	Less control, GitHub-only, opaque
Headless CLI (Claude/Codex/Gemini)	Custom review, fix, and generation workflows	More setup, you manage costs, any CI platform
Dedicated review tool (CodeRabbit)	PR review specifically	Best review UX, less flexible for other tasks
No agent	Simple projects, strict security requirements	Maximum control, minimum risk

Most teams end up combining approaches: a dedicated review tool (CodeRabbit or Copilot) for every PR, plus headless CLI agents for specific workflows like changelog generation or test scaffolding.

Running your own AI agent in CI gives you control that platform-managed agents can't match. You choose the model, the prompt, the tools, and the budget. The trade-off is setup and maintenance — but once the workflow YAML is written, it runs on every PR without intervention.

Start with one workflow — changelog generation or AI code review — and expand from there. Keep costs visible, scope permissions tightly, and always run tests after agent modifications.

Ready to connect your AI-powered CI pipeline to deployment? DeployHQ deploys to any server you own with zero-downtime deployments, one-click rollback, and a CLI built for CI/CD automation. Get started for free.

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

Managing Secrets: .env Files, .env.example, and Config in DeployHQ

DeployHQ — Wed, 08 Jul 2026 07:18:27 +0000

Every application needs configuration that changes between environments — database URLs, API keys, feature flags. The .env file is the standard way to manage these values locally without hardcoding them into your source code. This guide explains what .env files are, how they work across languages, and how to handle them safely from development through deployment.

What Is a .env File?

A .env file is a plain text file that sits in the root of your project and stores configuration as key-value pairs:

DATABASE_URL=postgres://localhost:5432/myapp
API_KEY=sk-abc123def456
DEBUG=true
PORT=3000

Your application reads this file at startup and loads the values into the process environment. This keeps sensitive credentials and environment-specific settings out of your codebase.

The name .env follows the Unix convention where dot-prefixed files are hidden by default — present but unobtrusive.

The KEY=VALUE Format

The syntax is simple, but there are rules worth knowing:

# This is a comment
DATABASE_URL=postgres://localhost:5432/myapp

# Quoted values preserve whitespace
APP_NAME="My Application"

# Single quotes prevent variable expansion
GREETING='Hello $USER'

# No spaces around the equals sign
CORRECT=value
# WRONG = value <-- this breaks most parsers

Key rules:

No spaces around =. KEY=value is correct; KEY = value breaks most parsers
Comments start with # at the beginning of a line
Empty lines are ignored
Quotes are optional for simple values. Use double quotes for values with spaces, single quotes to prevent variable interpolation
No export keyword. Unlike shell scripts, .env files omit export. Some parsers accept it, but it's not standard

How Different Frameworks Load .env Files

The .env file doesn't load itself. Your language or framework needs a library to read it and inject values into the process environment.

Node.js

The dotenv package is the standard:

npm install dotenv


require('dotenv').config();

const dbUrl = process.env.DATABASE_URL;
const port = process.env.PORT || 3000;

Node.js 20.6+ has a built-in --env-file flag that eliminates the package entirely:

node --env-file=.env app.js

Python

pip install python-dotenv


from dotenv import load_dotenv
import os

load_dotenv()

db_url = os.getenv("DATABASE_URL")
debug = os.getenv("DEBUG", "false").lower() == "true"

Django projects often use django-environ for typed access:

import environ
env = environ.Env()
environ.Env.read_env()

DEBUG = env.bool("DEBUG", default=False)
DATABASE_URL = env.db()

Ruby

# Gemfile
gem 'dotenv', groups: [:development, :test]

# Load early in boot
require 'dotenv/load'

db_url = ENV['DATABASE_URL']

Rails projects use dotenv-rails, which loads automatically before the app initializes.

PHP

composer require vlucas/phpdotenv


$dotenv = Dotenv\Dotenv::createImmutable( __DIR__ );
$dotenv->load();

$dbUrl = $_ENV['DATABASE_URL'];

// Require specific variables (throws exception if missing)
$dotenv->required(['DATABASE_URL', 'API_KEY']);

Laravel loads .env automatically. Access values with the env() helper:

$debug = env('APP_DEBUG', false);

If you're shipping a Laravel app to production, our zero-downtime Laravel deployment guide walks through build pipelines and environment configuration end to end.

Security Best Practices

The .env file often contains the most sensitive data in your project. Mishandling it is one of the most common security mistakes in web development.

Never Commit .env to Version Control

Add .env to your .gitignore immediately:

.env
.env.local
.env.*.local

If you've already committed a .env file, removing it from .gitignore isn't enough — the values are still in your Git history. Rotate every exposed secret, then use BFG Repo-Cleaner to scrub the history. Our guide to protecting your API keys covers rotation and leak response in more depth.

Use .env.example as a Template

Create a .env.example that documents every required variable with placeholder values:

# .env.example - Copy to .env and fill in real values
DATABASE_URL=postgres://user:password@localhost:5432/dbname
API_KEY=your-api-key-here
DEBUG=false
PORT=3000

Commit this file. New developers copy it, fill in their values, and they're ready to go.

Restrict File Permissions

On Unix systems:

chmod 600 .env

This ensures only the file owner can read or write it.

Environment-Specific Files

Most frameworks support a hierarchy of .env files that override each other:

.env # Shared defaults (committed)
.env.local # Local overrides (not committed)
.env.development # Development-specific
.env.test # Test-specific
.env.production # Production-specific

The typical loading order (varies by framework):

.env — base defaults
.env.local — local overrides (skipped in test)
.env.{environment} — environment-specific values
.env.{environment}.local — local environment overrides

Vite only exposes variables prefixed with VITE_ to client-side code. Next.js uses NEXT_PUBLIC_. Create React App uses REACT_APP_. These prefixes prevent accidental exposure of server-side secrets to the browser.

Common Patterns and Gotchas

Variable Expansion

Some parsers support referencing other variables:

BASE_URL=https://api.example.com
USERS_API=${BASE_URL}/users
POSTS_API=${BASE_URL}/posts

The dotenv-expand package enables this in Node.js. Python's python-dotenv supports it natively. Not all parsers handle expansion, so test before relying on it.

Multiline Values

Multiline values require double quotes:

PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA0Z3VS5JJcds3xfn/ygWyF...
-----END RSA PRIVATE KEY-----"

If your parser struggles with this, base64-encode the value instead:

PRIVATE_KEY_BASE64=TUlJRXBBSUJBQUtDQVFF...


const key = Buffer.from(process.env.PRIVATE_KEY_BASE64, 'base64').toString();

Boolean Values

There's no standard for booleans. These are all common:

DEBUG=true
DEBUG=1
DEBUG=yes

Pick one convention and be consistent. Always parse explicitly:

const debug = process.env.DEBUG === 'true';

Configuring Secrets in DeployHQ: UI, CLI, and API

During local development, .env files are convenient. In production, you should not deploy .env files to your servers. Once your secrets are out of your repository, you still need a way to store them and inject them at deploy time. DeployHQ gives you three ways to do that — the web UI, the dhq command-line tool, and the API — so you can pick whichever fits a one-off change or an automated workflow.

Config Files vs Environment Variables

Before configuring anything, it helps to know which of the two mechanisms you actually need:

Config files are whole files uploaded at deploy time and not stored in your repository — think a production .env, a credentials.json, or a settings.yml.
Environment variables are individual values injected into the build and referenced from config files or SSH commands.

The rule of thumb is simple: if you're managing a single value, use an environment variable; if you're managing an entire file, use a config file.

The UI Method

For a one-off change, the DeployHQ web UI is the fastest path.

Config files live under Settings → Config Files. They're uploaded during deployment rather than stored in your repository, which makes them ideal for sensitive data like database configuration. When you create one, you specify:

The full path as the filename (this is where the file lands on the server)
The file content
An optional description
A language for syntax highlighting

Two toggles shape how the file is used. Build Pipeline Integration makes the config file available during your build commands. Server Distribution lets you upload it to all current and future servers and server groups, or target specific ones. You can also set up multiple config files per environment type — development, staging, and production — and only deploy them where they belong. Config files can go out with a standard deployment, or via a dedicated Config file deployment that ships only config files with no other changes.

Environment variables live in the project sidebar under Environment Variables. These are dynamic values usable in config files, SSH commands, and notifications. To create one:

The name must start with a letter and contain only uppercase letters, numbers, and underscores
Enter a value
Toggle Use this variable with the Build Pipeline if the build needs it
Choose which server or server group can access it

In the build pipeline, these are exported as real environment variables, so tools like Vite, Webpack, Next.js, and Create React App read them via process.env.VARIABLE_NAME with no .env file setup at all. In deployments, config files, and SSH commands, you reference them with the %VARIABLE_NAME% syntax.

On security: all variable values are encrypted at rest and never visible in logs or the UI. Values can also be locked , which prevents viewing or changing them while they keep working in deployments. When the same variable is defined at multiple levels, targeting precedence runs highest to lowest: server-specific overrides a server group, which overrides all-servers. DeployHQ also ships roughly 20 built-in variables — such as %environment%, %branch%, %deployer%, and %status% — that you can reference without defining anything.

If you're new to how the build stage fits into a deployment, the DeployHQ build pipeline explains where these variables and files are injected.

The CLI Method

The dhq command-line tool is a single binary that brings the DeployHQ workflow to your terminal — deploy, monitor, manage servers, and automate, all without leaving the shell.

Install it with Homebrew, the install script, or a prebuilt binary:

brew install deployhq/tap/dhq
# or
curl -fsSL https://raw.githubusercontent.com/deployhq/deployhq-cli/main/install.sh | sh

You can also grab a binary directly from GitHub Releases.

Authenticate once with dhq auth login, which stores your credentials in the OS keyring. dhq hello gives you a guided login/signup flow plus project selection, and for CI/CD you authenticate via environment variables instead of the interactive login.

The commands relevant to secrets are:

dhq env-vars — manage a project's environment variables
dhq global-env-vars — manage account-wide environment variables
dhq config-files — manage configuration files
dhq api — reach the full set of 144+ API endpoints

The CLI also offers JSON output for scripting and shell completions for faster typing.

The exact create, set, and update sub-command syntax isn't fixed here — run dhq <command> --help (for example, dhq env-vars --help) to see the current usage for your version rather than guessing at flags.

The API Method

For fully programmatic management, DeployHQ exposes 144+ API endpoints , reachable either through dhq api or directly. This is the right layer when you want to script secret provisioning — for instance, auto-creating a standard set of environment variables and config files every time you onboard a new project or client.

Which One Should You Use?

The CLI and API make your secrets reproducible and automatable, which is exactly what you want when they need to live in CI or in an onboarding script that spins up a new project the same way every time. The UI, by contrast, is the quickest route for a one-off change. Most teams end up using all three: the UI to eyeball and tweak, the CLI and API to codify.

flowchart LR
  A[Code in Git] --> B[DeployHQ]
  B --> C[Build with env vars]
  C --> D[Deploy to server]
  E[Secure variable store] --> B

The end-to-end workflow looks like this:

Development : Use .env files locally
CI/Build : Environment variables and config files set in DeployHQ's project configuration
Deployment : Variables available during build commands and injected into config files
Runtime : Application reads from the server's environment

If you deploy from GitHub or GitLab, DeployHQ connects to your repository and handles the rest. For agencies managing multiple client projects, each project gets an isolated variable store so credentials never leak between clients. This same config-in-the-environment discipline is the backbone of the 12-Factor App methodology, and it applies just as much to a static site on Cloudflare's edge as it does to a traditional server.

Ready to get your secrets out of Git for good? Start a DeployHQ project and add your first encrypted environment variable in a couple of minutes.

FAQ

Should I commit .env.example to Git? Yes. It documents which variables your app requires with placeholder values. Never put real credentials in it.

What happens if a variable is defined in both .env and the system environment? In most libraries, system environment variables take precedence. This lets your deployment platform override defaults without modifying files.

Can I use .env files in Docker containers? Yes. Docker supports --env-file natively, and Docker Compose reads .env in the project root automatically for variable substitution.

How do I handle .env files across a team? Use .env.example as the shared template. Each developer maintains their own .env with local values. For shared secrets, use a password vault rather than distributing files via chat.

Are .env files secure enough for production? For local development, yes. For production, use your platform's built-in secrets management — like DeployHQ's secure environment variables, which are encrypted at rest and injected at deploy time.

Ready to stop worrying about environment configuration? Automate deployments with DeployHQ's build pipeline and manage your environment variables securely from day one. See pricing for team plans.

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