> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# WordPress

> Ready-to-run WordPress container template you can run directly or inherit to integrate a CMS into your stack.

## Overview

This template provides a production‑ready WordPress instance as a Monk runnable. You can:

* Run it directly to get a managed WordPress site with database
* Inherit it in your own runnable to seamlessly add a CMS to your stack

WordPress powers over 40% of all websites on the internet. It's a powerful, flexible CMS for blogs, e-commerce sites, and enterprise portals.

## What this template manages

* WordPress container (`wordpress` image, configurable tag)
* MySQL or MariaDB database
* Network service on ports 80/443
* Persistent volumes for uploads, themes, and plugins
* Optional initialization of database and security keys

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run WordPress stack

```bash theme={null}
monk run wordpress/stack
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `wordpress/stack.yaml`, then `monk load MANIFEST` and run.

Once started, access WordPress at `http://localhost:80` and complete the famous 5-minute installation.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  # WordPress
  wordpress-image-tag: "latest"       # container image tag
  wordpress-port: "80"                # HTTP port
  wordpress-https-port: "443"         # HTTPS port (env: WORDPRESS_HTTPS_PORT)
  wordpress-table-prefix: "wp_"       # database table prefix (env: WORDPRESS_TABLE_PREFIX)
  
  # Database
  wordpress-db-host: "mysql"          # database host (env: WORDPRESS_DB_HOST)
  wordpress-db-name: "wordpress"      # database name (env: WORDPRESS_DB_NAME)
  wordpress-db-user: "wordpress"      # database user (env: WORDPRESS_DB_USER)
  wordpress-db-password: "..."        # database password (env: WORDPRESS_DB_PASSWORD)
  
  # Security
  wordpress-auth-key: "..."           # generate unique keys
  wordpress-secure-auth-key: "..."    # at wordpress.org/secret-key
  wordpress-logged-in-key: "..."      # (env: WORDPRESS_AUTH_KEY, etc.)
  wordpress-nonce-key: "..."
```

Data is persisted under `${monk-volume-path}/wordpress` and `${monk-volume-path}/mysql` on the host.

## Use by inheritance (recommended for websites)

Inherit the WordPress runnable in your application and declare a connection. Example:

```yaml theme={null}
namespace: mysite
cms:
  defines: runnable
  inherits: wordpress/stack
  variables:
    wordpress-db-password: <- secret("wordpress-db-password")
    wordpress-auth-key: <- secret("wordpress-auth-key")
    wordpress-secure-auth-key: <- secret("wordpress-secure-auth-key")
    wordpress-logged-in-key: <- secret("wordpress-logged-in-key")
    wordpress-nonce-key: <- secret("wordpress-nonce-key")
```

Then set the secrets once and run your site:

```bash theme={null}
monk secrets add -g wordpress-db-password="STRONG_PASSWORD"
monk secrets add -g wordpress-auth-key="<generated-key>"
# Generate security keys at https://api.wordpress.org/secret-key/1.1/salt/
monk run mysite/cms
```

## Ports and connectivity

* HTTP: TCP port `80`
* HTTPS: TCP port `443` (if configured with SSL)
* Admin panel: `http://\<host>/wp-admin/`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the WordPress host.

## Persistence and configuration

* WordPress files: `${monk-volume-path}/wordpress/html:/var/www/html`
* Uploads: `${monk-volume-path}/wordpress/uploads:/var/www/html/wp-content/uploads`
* Plugins: `${monk-volume-path}/wordpress/plugins:/var/www/html/wp-content/plugins`
* Themes: `${monk-volume-path}/wordpress/themes:/var/www/html/wp-content/themes`
* MySQL data: `${monk-volume-path}/mysql:/var/lib/mysql`

## Related templates

* Combine with databases (MariaDB, MySQL) for content storage
* Use with CDN for static asset delivery
* Integrate with object storage (S3, Minio) for media files

## Troubleshooting

* Access WordPress admin at `http://localhost/wp-admin/`
* For database connection errors, verify MySQL is running and credentials are correct
* If you changed `wordpress-db-password` but the container has existing data, authentication may fail. Either reset the data volume or update the password inside the DB to match.
* Enable WordPress debug mode in `wp-config.php`:

```php theme={null}
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
```

* Check logs:

```bash theme={null}
monk logs -l 500 -f wordpress/wordpress
monk logs -l 500 -f wordpress/mysql
```

* For white screen of death, check PHP error logs
* For plugin conflicts, rename plugins folder to disable all
* For theme issues, switch to default theme