WordPress

Overview

WordPress is the open-source content management system for websites and blogs. This template deploys Apache with PHP, a bundled MariaDB database, and a shared volume holding WordPress core, plugins, themes and the media library. The administrator account is created before the site accepts its first request. WordPress runs in exactly one location of your GVC, and wordpress.replicas adds interchangeable replicas that share the same volume and database.

This template deploys into an existing GVC that you already have — it does not create or manage a GVC. The location you set must already be one of that GVC’s locations; if it is not, WordPress starts nothing in the GVC.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-wordpress`	Site and `/wp-admin` on HTTP port `80` (standard, `wordpress.replicas` replicas, pinned to `location`)	—
Volume set	`RELEASE_NAME-wordpress-vs`	Shared volume at `/var/www/html`: core, plugins, themes, uploads and `wp-config.php`	—
Identity	`RELEASE_NAME-wordpress-identity`	Bound to the WordPress workload	—
Policy	`RELEASE_NAME-wordpress-policy`	Grants that identity `reveal` on exactly the administrator and database credentials secrets	—
Policy	`RELEASE_NAME-wordpress-gvc-policy`	Grants that identity `view` on the install GVC only, for a location check at boot	—
Workload	`RELEASE_NAME-maria`	Bundled MariaDB from the mariadb template (stateful, 1 replica) on TCP `3306`	—
Volume set	`RELEASE_NAME-maria-vs`	MariaDB data directory	—
Identity	`RELEASE_NAME-maria-identity`	Bound to the MariaDB workload and its backup job	—
Policy	`RELEASE_NAME-maria-policy`	Grants the MariaDB identity `reveal` on its two credential secrets	—
Workload	`RELEASE_NAME-phpmyadmin`	phpMyAdmin console (serverless) on HTTP `80`, reachable inside the GVC only by default	`mariadb.phpMyAdmin.enabled: true`
Workload	`RELEASE_NAME-maria-backup`	Scheduled database dump to S3 or GCS (cron)	`mariadb.backup.enabled: true`

Your administrator, database and root password secrets are not created by the template — see Prerequisites.

Prerequisites

Three secrets must exist before you install, and the GVC should have one location (see the last step). Secrets are org-level, so no --gvc flag is involved, and their values never pass through Helm values.

Create the administrator secret

A dictionary secret with username, password and email. WordPress creates its administrator account from it on first boot.

cpln secret create-dictionary --name ADMIN_SECRET_NAME \
  --entry username=wpadmin \
  --entry password="$(openssl rand -base64 18)" \
  --entry email=admin@example.com

Set admin.secretName to this name.

Create the database credentials secret

A dictionary secret the bundled MariaDB initializes with and WordPress connects with:

cpln secret create-dictionary --name DB_CREDENTIALS_SECRET_NAME \
  --entry username=wordpress \
  --entry password="$(openssl rand -hex 24)" \
  --entry database=wordpress

Set mariadb.credentialsSecretName to this name. Secret names are org-wide, so give each release its own secrets.

Create the MariaDB root password secret

An opaque secret holding the MariaDB root password. WordPress never reads it.

printf '%s' "$(openssl rand -hex 32)" | cpln secret create-opaque --name DB_ROOT_SECRET_NAME --encoding plain -f -

Set mariadb.rootPasswordSecretName to this name.

Use a GVC with one location

WordPress runs only in the location named by location, which must already be a location of your GVC. The bundled MariaDB starts in every location of the GVC, and each extra location would hold its own separate database. A fresh install on a GVC with more than one location is refused; do not add or remove GVC locations under a live release.

Create all three secrets before installing. Installing without one reports success, but the deployment never becomes ready and cpln logs stays empty; status.versions[].message from the command below names the missing secret:

cpln workload get-deployments RELEASE_NAME-wordpress --gvc GVC_NAME -o yaml

Creating the secret afterwards does not unblock the deployment. Run cpln workload force-redeployment on RELEASE_NAME-maria and on RELEASE_NAME-wordpress; see Troubleshooting.

Scheduled database backups need a bucket and a cloud account first; see Backing Up.

Installation

Once your three secrets exist, install from the marketplace registry, pointing the keys at them and location at a location of your GVC:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/wordpress \
  --version 1.0.0 --gvc GVC_NAME \
  --set location=LOCATION_NAME \
  --set admin.secretName=ADMIN_SECRET_NAME \
  --set mariadb.credentialsSecretName=DB_CREDENTIALS_SECRET_NAME \
  --set mariadb.rootPasswordSecretName=DB_ROOT_SECRET_NAME

Other ways to install and manage the template:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Location

# The ONE location of your GVC that WordPress runs in; it must be a location the GVC has.
location: aws-us-east-1

Use a bare location name such as aws-us-east-1.

wordpress:
  image: wordpress:7.1.4-php8.4-apache # seeds the docroot on first boot only; later bumps change PHP and Apache, not core
  replicas: 1 # 2+ share one docroot volume and one database
  siteTitle: My WordPress Site # first boot only; change it later in Settings > General
  siteUrl: "" # public base URL, e.g. https://www.example.com; empty = the canonical *.cpln.app endpoint
  tablePrefix: wp_ # first boot only; change only when importing an existing database
  debug: false # WP_DEBUG: PHP notices to the container log
  resources:
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 1Gi

PHP Limits

php:
  uploadMaxSize: 64M # upload_max_filesize and post_max_size (stock PHP caps uploads at 2M)
  memoryLimit: 256M # memory_limit

Administrator Account

admin:
  secretName: my-wordpress-admin # MUST EXIST BEFORE INSTALL: dictionary with username, password, email (first boot only)

Content Storage

volumeset:
  capacity: 10 # GiB (minimum 10): core, plugins, themes, uploads and wp-config.php

Access

publicAccess:
  enabled: true # HTTPS site and wp-admin on the canonical *.cpln.app endpoint
internalAccess:
  type: same-gvc # none | same-gvc | same-org | workload-list
  workloads: [] # used only with workload-list, e.g. //gvc/GVC_NAME/workload/WORKLOAD_NAME

With workload-list, include RELEASE_NAME-wordpress in the list. none isolates WordPress only together with publicAccess.enabled: false.

MariaDB

mariadb:
  image: mariadb:11.8.9
  credentialsSecretName: my-wordpress-db-credentials # MUST EXIST BEFORE INSTALL: dictionary with username, password, database
  rootPasswordSecretName: my-wordpress-db-root-password # MUST EXIST BEFORE INSTALL: opaque (encoding plain), the root password
  resources:
    minCpu: 150m # keeps cpu:minCpu under the stateful 4:1 cap
    maxCpu: 500m
    minMemory: 256Mi
    maxMemory: 1Gi
  volumeset:
    capacity: 10 # GiB (minimum 10)
  internalAccess:
    type: same-gvc # WordPress connects like any workload: never none
  # Optional scheduled database backups to AWS S3 or GCS (see "Storage setup" in the README).
  backup:
    enabled: false
    provider: aws # aws | gcp
    aws:
      bucket: my-backup-bucket
      region: us-east-1
      cloudAccountName: my-backup-cloudaccount
      policyName: my-backup-policy
      prefix: wordpress/backups
    gcp:
      bucket: my-backup-bucket
      cloudAccountName: my-backup-cloudaccount
      prefix: wordpress/backups

Every knob of the mariadb template is available under mariadb, including the phpMyAdmin console (mariadb.phpMyAdmin.enabled: true). mariadb.internalAccess.type may not be none, and a workload-list must include RELEASE_NAME-wordpress.

Connecting

What	Address	Notes
Public site	`status.canonicalEndpoint` from `cpln workload get RELEASE_NAME-wordpress --gvc GVC_NAME -o yaml`	The `*.cpln.app` endpoint
Admin dashboard	`SITE_URL/wp-admin`	`username` and `password` from the administrator secret (`cpln secret reveal ADMIN_SECRET_NAME -o yaml`)
Internal	`http://RELEASE_NAME-wordpress.GVC_NAME.cpln.local` (port `80`)	From other workloads in the GVC
Health	`GET /cpln-health.php`	Answers `ok` when PHP, the database and the install all work
MariaDB	`RELEASE_NAME-maria.GVC_NAME.cpln.local:3306`	Internal only; values from the database credentials secret (`cpln secret reveal DB_CREDENTIALS_SECRET_NAME -o yaml`)

Verify the site through a tunnel:

cpln port-forward RELEASE_NAME-wordpress 8080:80 --gvc GVC_NAME
curl -s http://localhost:8080/cpln-health.php

The response must be ok. The first boot seeds the content volume and runs the installer, so the workload takes several minutes to become ready.

First Run

The administrator account already exists from your administrator secret; sign in at /wp-admin. Set wordpress.siteUrl to your own domain once DNS points at the endpoint. With publicAccess.enabled: false, reach the site through a tunnel. WordPress builds every link from its site URL, so set wordpress.siteUrl to the tunnel address (http://localhost:8080), run cpln helm upgrade, open the tunnel above and browse http://localhost:8080/wp-admin/. Set wordpress.siteUrl back to "" (or your custom domain) before turning the public endpoint on again.

Operations

Backing Up

Database backups are off by default. Enable mariadb.backup.enabled: true and choose a provider of aws or gcp; the bucket, cloud account and IAM setup are described in Backing Up, and the backup block above uses the same keys. A backup is a database dump: it does not include the media library, and the template takes no snapshot of the content volume. Keep your own copy of wp-content/uploads, because uninstalling the release deletes the volume.

Restoring a Backup

Restore steps for the database belong to the underlying template: Restoring a Backup. Restoring the media library is manual; copy your own copy of wp-content/uploads back onto the content volume.

Resetting the Administrator Password

The administrator secret is read on first boot only. To reset the password, run this in the container; user 1 is the administrator created at install:

cpln workload exec RELEASE_NAME-wordpress --gvc GVC_NAME --container wordpress -- \
  php -r '$_SERVER["HTTP_HOST"]="localhost"; require "/var/www/html/wp-load.php"; wp_set_password("YOUR-NEW-PASSWORD", 1);'

Changing the Database Password

The database secrets are read when MariaDB first initializes. Run ALTER USER in MariaDB first, then update the secret and redeploy both workloads:

cpln workload force-redeployment RELEASE_NAME-maria --gvc GVC_NAME
cpln workload force-redeployment RELEASE_NAME-wordpress --gvc GVC_NAME

Updating WordPress

Changing wordpress.image does not update WordPress core: the image seeds the content volume only while it is empty, and afterwards a new image changes PHP and Apache only. Update core, plugins and themes from the dashboard.

Scaling and Availability

wordpress.replicas: 2 or more keeps the site up while a WordPress replica restarts, because every replica mounts the same volume and database. The bundled MariaDB is a single instance and bounds availability: the site is down while it restarts. With one replica, a change that restarts the workload, such as wordpress.siteUrl or publicAccess.enabled, briefly takes the site down.

Troubleshooting

Deployment never becomes ready and the logs are empty

Symptom: cpln helm install reported success, cpln logs returns nothing, and cpln workload get-deployments RELEASE_NAME-wordpress --gvc GVC_NAME -o yaml shows

The secret SECRET_NAME no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.

under status.versions[].message. Cause: A prerequisite secret does not exist. The message names the missing one. Fix: Create it (see Prerequisites), then run cpln workload force-redeployment RELEASE_NAME-maria --gvc GVC_NAME and cpln workload force-redeployment RELEASE_NAME-wordpress --gvc GVC_NAME.

WordPress starts nothing and reports it is deactivated

Symptom: The deployment message reads This workload location is deactivated because maxScale is set to 0. Cause: location is not one of the GVC’s locations. The default is aws-us-east-1. Fix: Set location to a location your GVC already has, and run cpln helm upgrade.

Redirect loops or broken links through a tunnel

Symptom: The browser loops or links point at the public endpoint while you use cpln port-forward. Cause: WordPress builds every link from wordpress.siteUrl. Fix: Set wordpress.siteUrl to the tunnel address, such as http://localhost:8080, and run cpln helm upgrade; see First Run.

Password reset and invitation emails never arrive

Symptom: WordPress reports success but no email is delivered. Cause: The container has no mail transport. Fix: Install an SMTP plugin from the dashboard.

Render refuses the install

Symptom: cpln helm install fails with a message beginning wordpress:, such as wordpress: `location` is required or wordpress: wordpress.replicas must be at least 1. Cause: A required value is missing or invalid. Fix: Set the value the message names and install again.

Important Notes

Install into a single-location GVC and set location to that location; do not add or remove GVC locations under a live release.
A location the GVC does not have runs nothing; set it to one the GVC lists.
The media library is not backed up and uninstalling deletes it; keep your own copy of wp-content/uploads.
wordpress.siteTitle, wordpress.tablePrefix and the three secrets apply on first boot only; change the title in Settings > General.
Outbound email does not work until you install an SMTP plugin.
A firewall change after changing publicAccess.enabled or internalAccess takes from 30 seconds to a few minutes to apply.

External References

WordPress Documentation

Official user documentation

Advanced Administration Handbook

Security, performance and server configuration

wp-config.php Reference

Every setting WordPress reads

Official WordPress Docker Image

Image variants and environment variables

Template Catalog

Templates

WordPress

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Location

WordPress

PHP Limits

Administrator Account

Content Storage

Access

MariaDB

Connecting

First Run

Operations

Backing Up

Restoring a Backup

Resetting the Administrator Password

Changing the Database Password

Updating WordPress

Scaling and Availability

Troubleshooting

Important Notes

External References

WordPress Documentation

Advanced Administration Handbook

wp-config.php Reference

Official WordPress Docker Image

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Location

​WordPress

​PHP Limits

​Administrator Account

​Content Storage

​Access

​MariaDB

​Connecting

​First Run

​Operations

​Backing Up

​Restoring a Backup

​Resetting the Administrator Password

​Changing the Database Password

​Updating WordPress

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

WordPress Documentation

Advanced Administration Handbook

wp-config.php Reference

Official WordPress Docker Image

Overview

What Gets Created

Prerequisites

Installation

Configuration

Location

WordPress

PHP Limits

Administrator Account

Content Storage

Access

MariaDB

Connecting

First Run

Operations

Backing Up

Restoring a Backup

Resetting the Administrator Password

Changing the Database Password

Updating WordPress

Scaling and Availability

Troubleshooting

Important Notes

External References