Skip to content

Example WordPress — Getting Started with WordPress on Gubernator

This is the first example to run. It demonstrates the complete basic workflow of Gubernator on a single node (your local machine), showcasing a multi-service deployment (WordPress + MySQL) utilizing persistent volumes, internal DNS service discovery, and automatic Caddy Ingress routing.

What You Will Deploy

The stack file docker-compose.yml located in examples/example-wordpress/ defines: - db: A MySQL database container storing data in a persistent Docker volume (db_data). - wordpress: A WordPress container connected to the database via internal DNS and exposed to external traffic using Caddy Ingress.

Prerequisites

  • Docker running on your local machine.
  • Go 1.24+ installed (or download the pre-built gbnt binary from Releases).

Step 1: Start Gubernator

Open a terminal at the repository root and compile the Gubernator binary:

go build -o gbnt ./cmd/gbnt

Start the Manager with the Web UI and SRE Monitor enabled:

GBNT_API_TOKEN=admin \
GBNT_WEB=true \
GBNT_WEB_USER=admin \
GBNT_WEB_PASSWORD=admin \
GBNT_MONITOR=true \
./gbnt serve

Leave this terminal running. It will output orchestrator logs as containers start up.

Open the Dashboard

Navigate to http://localhost:4001 (admin/admin) to view the live dashboard, watch logs, and manage stacks.

Step 2: Register the Local Node

Before deploying stacks, Gubernator needs at least one active node. Open a second terminal and register your machine as a worker node:

# Terminal 2
export GBNT_API_TOKEN=admin

# Initialize the cluster control plane
./gbnt legion init

Copy the gbnt legion join command output by the initialization and run it:

./gbnt legion join --token <YOUR_TOKEN> --manager 127.0.0.1:4000

Step 3: Deploy the WordPress Stack

In a third terminal, deploy the WordPress stack using the CLI:

# Terminal 3
export GBNT_API_TOKEN=admin

./gbnt stack deploy -c examples/example-wordpress/docker-compose.yml

[!NOTE] The stack name is automatically defined as wp inside the docker-compose.yml file using the stack.name placement constraint. This ensures that the generated CoreDNS service domain resolves correctly to db.wp.gbnt as defined in WordPress's database connection settings.

Step 4: Verify the Deployment

Wait a few seconds for the Docker daemon to pull the images and start the containers.

1. Check Tasks via CLI

./gbnt task ls
You should see both the db and wordpress tasks listed as running.

2. Verify with Docker

docker ps | grep gbnt
You will see the active container instances running, linked to the gbnt-net bridge network.

3. Access WordPress

  • Direct Access: Open http://localhost:8080 in your browser. You should see the WordPress setup screen.
  • Caddy Ingress: Caddy routes traffic from the local host name http://hello-101.gbnt.test directly to the WordPress task container.

Note: If you configured your host OS resolver as described in the Installation guide, hello-101.gbnt.test will automatically resolve to 127.0.0.1 natively without editing /etc/hosts.

[!TIP] Trusting Local HTTPS with Caddy: If you are using local HTTPS and want your host machine to trust the temporary self-signed certificate generated by Caddy, copy the root certificate from the container and add it to your trust store: 

# 1. Copy the root certificate from the container
docker cp gbnt-caddy:/data/caddy/pki/authorities/local/root.crt ./caddy-root.crt

# 2. Install and trust it on macOS (Keychain)
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ./caddy-root.crt

Step 5: Edit & Scale from the Web UI

  1. Open http://localhost:4001.
  2. Browse to the Legion Stacks tab.
  3. Select the wp stack and click the Edit YAML button.
  4. You can edit configurations on the fly or adjust scale replicas, then click Save & Redeploy.

Step 6: Clean Up

When you are done testing, tear down the stack:

# Get the stack ID
./gbnt stack ls

# Remove the stack (stops and cleans up all associated containers and volumes)
./gbnt stack rm <stack_id>

What You Learned

  • Multi-service Stacks: How to deploy complex applications with backend dependencies.
  • Service Discovery: Using Gubernator's built-in CoreDNS to resolve container IPs via <service>.<stack>.gbnt.
  • Caddy Ingress: Exposing services under custom domain names using the ingress.host placement constraint.
  • YAML Mapping Compatibility: Gubernator automatically supports both list (- KEY=VALUE) and map (KEY: VALUE) formats for environment variables.