Zero-configuration, multi-tenant CLI and Docker orchestrator for self-hosting Ghost CMS across any cloud provider.
Important
Beta Stage Notice: pubctl is currently in active beta. Core orchestration features (Traefik SSL, isolated MySQL, S3 storage, backups, and standalone binary execution) are operational, but commands, flags, and configuration formats may evolve before the stable release. Please report issues, feedback, or feature requests on GitHub!
pubctl (Pub (Publishing or Publication) + ctl (control)) automates the lifecycle of multi-tenant Ghost CMS instances on a single virtual server (AWS EC2, Hetzner, DigitalOcean, Linode, etc.). It orchestrates automatic Let's Encrypt SSL certificates via Traefik v3, per-tenant isolated MySQL 8.0 databases, S3-compatible cloud media storage, automated zero-touch administrative provisioning, point-in-time backups, and recoverable restart updates.
- π Automated SSL/TLS: Traefik reverse proxy automatically provisions and renews Let's Encrypt certificates over HTTP/HTTPS.
- ποΈ Multi-Tenant Database Isolation: Automatically creates dedicated databases and restricted MySQL users per blog.
- βοΈ S3 / Cloudflare R2 Media Offloading: Seamless support for AWS S3, Cloudflare R2, MinIO, and DigitalOcean Spaces to keep local disk usage minimal.
- π Headless Zero-Touch Setup: Automatically bootstraps the Ghost admin account and password, bypassing manual setup screens.
- π¦ Point-in-Time Backups: Temporarily pauses a tenant while its MySQL dump and content archive are created.
- π Recoverable Updates: Restores the previous container automatically if a replacement fails to start.
- π Zero Runtime Dependencies: Distributed as a single, self-contained native binary compiled with Bunβno Node.js or npm required on target hosts.
Installs the standalone native binary to /usr/local/bin/pubctl with zero dependencies:
curl -sSL https://raw.githubusercontent.com/officialrajdeepsingh/pubctl/main/install.sh | bashNote: Works on Linux (x64 & ARM64) and macOS. Requires only Docker to be installed.
If you have Node.js (v18+) installed:
# Using pnpm
pnpm add -g pubctl
# Using npm
npm install -g pubctlDownload pre-compiled binaries directly from GitHub Releases:
# Example for Linux x64
curl -sSL -o pubctl https://github.com/officialrajdeepsingh/pubctl/releases/latest/download/pubctl-linux-x64
chmod +x pubctl
sudo mv pubctl /usr/local/bin/- Docker Engine: Docker must be running on your host:
docker --version
- MySQL Root Password: Generate and retain a strong password before initialization. It must also be available to later
create,backup, anddeletecommands:export MYSQL_ROOT_PASSWORD="$(openssl rand -base64 32)"
- Ports 80 & 443: Available on the host for Traefik to bind and issue Let's Encrypt SSL certificates.
- DNS Records: Point your domain or subdomains (A / AAAA records) to your server's public IP address.
Run this once on a fresh server to launch the shared Docker bridge network, Traefik SSL proxy, and MySQL 8.0 container:
export MYSQL_ROOT_PASSWORD="$(openssl rand -base64 32)"
pubctl init --email admin@example.comIf upgrading an installation created by an older release, use the current root password in MYSQL_ROOT_PASSWORD and rotate it in the same command:
PUBCTL_NEW_ROOT_PASSWORD="$(openssl rand -base64 32)"
export MYSQL_ROOT_PASSWORD="the-current-password"
export PUBCTL_NEW_ROOT_PASSWORD
pubctl init --email admin@example.com --rotate-mysql-root-password
export MYSQL_ROOT_PASSWORD="$PUBCTL_NEW_ROOT_PASSWORD"Deploy a new publication with automated database provisioning and admin credentials:
pubctl create \
--name techblog \
--domain blog.example.com \
--admin-email admin@example.com \
--title "My Tech Blog"Once provisioning completes, pubctl displays your live blog URL, admin panel link, and automatically generated secure admin password!
Offload all image and media uploads to S3-compatible cloud storage:
pubctl create \
--name mediahub \
--domain media.example.com \
--admin-email admin@example.com \
--storage s3 \
--s3-bucket my-ghost-bucket \
--s3-key YOUR_R2_ACCESS_KEY_ID \
--s3-secret YOUR_R2_SECRET_ACCESS_KEY \
--s3-endpoint https://<account_id>.r2.cloudflarestorage.com \
--s3-asset-host https://cdn.example.comSets up Traefik v3 (with automatic ACME HTTP/TLS challenge support) and MySQL 8.0.
pubctl init --email <email>| Option | Required | Description |
|---|---|---|
--email <email> |
Yes | Email address registered with Let's Encrypt for certificate expiration notices |
Provisions a new isolated Ghost CMS tenant.
pubctl create [options]| Option | Shorthand | Required | Default | Description |
|---|---|---|---|---|
--name <name> |
-n |
Yes | β | Unique tenant identifier (e.g., techblog) |
--domain <domain> |
-d |
Yes | β | Fully qualified domain name (e.g., blog.example.com) |
--version <version> |
-v |
No | 6-alpine |
Ghost Docker image tag or custom repository (e.g., 6-alpine, 5-alpine) |
| Option | Default | Description |
|---|---|---|
--storage <type> |
local |
Storage driver: local or s3 |
--s3-bucket <bucket> |
β | Bucket name (required if --storage s3) |
--s3-key <key> |
β | Access Key ID (required if --storage s3) |
--s3-secret <secret> |
β | Secret Access Key (required if --storage s3) |
--s3-endpoint <url> |
β | Custom endpoint URL (e.g., Cloudflare R2, MinIO) |
--s3-asset-host <url> |
β | Custom CDN domain prefix for media assets |
--s3-region <region> |
auto |
Bucket region (e.g., us-east-1, auto for R2) |
--s3-force-path-style |
false |
Enable path-style URLs (useful for MinIO) |
| Option | Description |
|---|---|
--smtp-host <host> |
Outgoing SMTP server host (e.g., smtp.mailgun.org) |
--smtp-user <user> |
SMTP authentication username |
--smtp-pass <pass> |
SMTP authentication password |
Creates a point-in-time snapshot by pausing the tenant while it writes the MySQL dump (db.sql) and gzipped content archive (content.tar.gz).
pubctl backup -n <name> [-o <output_dir>]| Option | Shorthand | Required | Default | Description |
|---|---|---|---|---|
--name <name> |
-n |
Yes | β | Tenant identifier |
--output <dir> |
-o |
No | ./backups |
Target directory to store the backup |
Performs a recoverable restart update while preserving database data, environment credentials, and storage volumes. If the replacement fails, the prior container is restored automatically.
pubctl update -n <name> -t <version>| Option | Shorthand | Required | Description |
|---|---|---|---|
--name <name> |
-n |
Yes | Tenant identifier |
--to <version> |
-t |
Yes | Target Ghost image tag (e.g., 6-alpine, 5-alpine) |
Stops and removes the Ghost container. By default, it purges the isolated MySQL database, user credentials, and Docker volume.
pubctl delete -n <name> [--keep-data]| Option | Shorthand | Description |
|---|---|---|
--name <name> |
-n |
Tenant identifier |
--keep-data |
β | Preserve the database and content volume on disk |
Ghost requires the storage adapter package ghost-storage-adapter-s3 inside the container at /var/lib/ghost/content/adapters/storage/s3/.
We provide a ready-to-build Dockerfile.ghost-s3 that defaults to Ghost 6:
# Default build (Ghost 6):
docker build -t my-ghost-s3:6-alpine -f Dockerfile.ghost-s3 .
# Legacy Ghost 5 build:
docker build --build-arg GHOST_VERSION=5-alpine -t my-ghost-s3:5-alpine -f Dockerfile.ghost-s3 .- In Cloudflare Dashboard, go to R2 Storage and create a bucket (e.g.,
my-ghost-bucket). - Generate an R2 API Token with Read & Write permissions.
- Note your Endpoint URL:
https://<account_id>.r2.cloudflarestorage.com. - (Optional) Connect a custom domain to your bucket (e.g.,
https://media.example.com). - Deploy:
pubctl create \ --name blog \ --domain blog.example.com \ --admin-email admin@example.com \ --version my-ghost-s3:6-alpine \ --storage s3 \ --s3-bucket my-ghost-bucket \ --s3-key <R2_ACCESS_KEY_ID> \ --s3-secret <R2_SECRET_ACCESS_KEY> \ --s3-endpoint https://<account_id>.r2.cloudflarestorage.com \ --s3-asset-host https://media.example.com \ --s3-region auto
pubctl create \
--name blog \
--domain blog.example.com \
--admin-email admin@example.com \
--version my-ghost-s3:6-alpine \
--storage s3 \
--s3-bucket my-aws-ghost-bucket \
--s3-key AKIAIOSFODNN7EXAMPLE \
--s3-secret wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
--s3-region us-east-1For MinIO or local S3 instances, pass --s3-force-path-style:
pubctl create \
--name blog \
--domain blog.example.com \
--admin-email admin@example.com \
--version my-ghost-s3:6-alpine \
--storage s3 \
--s3-bucket ghost-uploads \
--s3-key minioadmin \
--s3-secret minioadmin \
--s3-endpoint https://minio.internal.example.com \
--s3-force-path-style Internet (Port 80 / 443)
β
βΌ
βββββββββββββββββββββββββββββββββββββ
β Traefik SSL Proxy Container β
β (Auto Let's Encrypt Wildcard) β
βββββββββββ¬ββββββββββββββββ¬ββββββββββ
β β
ββββββββββββββ ββββββββββββββ
βΌ βΌ
βββββββββββββββββββββ βββββββββββββββββββββ
β Ghost: blog-1 β β Ghost: blog-2 β
β (tenant: blog1) β β (tenant: blog2) β
βββββββββββ¬ββββββββββ βββββββββββ¬ββββββββββ
β β
βΌ βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β MySQL 8.0 (pubctl-mysql) β
β - Database: pubctl_blog1 - Database: pubctl_blog2 β
β - User: usr_blog1 - User: usr_blog2 β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β β
βΌ βΌ
βββββββββββββββββββββ βββββββββββββββββββββ
β Local / S3 Media β β Local / S3 Media β
βββββββββββββββββββββ βββββββββββββββββββββ
- Traefik Ingress: Dynamically routes traffic based on Docker labels (
traefik.http.routers.<name>.rule=Host(...)). Adding or removing tenants requires zero proxy restarts or reload commands. - Network Isolation: All containers run on an isolated bridge network (
pubctl-net). Database ports are never exposed to the public internet. - Customizable Namespace: Centralized in
src/config.ts. ChangingAPP_NAMEupdates all container names, networks, volumes, and labels.
# Clone the repository
git clone https://github.com/officialrajdeepsingh/pubctl.git
cd pubctl
# Install dependencies
pnpm install
# Run during development
pnpm dev --help
# Build TypeScript to dist/index.js (for Node.js & npm)
pnpm run build
# Compile standalone Linux x64 binary (zero external dependencies)
pnpm run compile:linux-x64MIT Β© Rajdeep Singh