Configure
WordPress Capsules are configured through environment variables in the Config tab of your Capsule's page. All configuration is applied at container start — changes take effect on the next deploy or restart.
Database Connection
Your WordPress Capsule requires a MySQL Data Capsule. In the Config tab, click Edit in the WordPress Config section to select a MySQL Capsule from your Space.
The following database environment variables are injected automatically:
| Variable | Description |
|---|---|
WORDPRESS_DB_HOST | MySQL host (set by the platform) |
WORDPRESS_DB_NAME | Database name (default: app) |
WORDPRESS_DB_USER | Database username |
WORDPRESS_DB_PASSWORD | Database password |
You can change the database name by editing WORDPRESS_DB_NAME in the WordPress Config section.
Storage
Your WordPress Capsule requires a Persistent Storage Capsule for uploaded media, plugin files, and theme files. Select one in the WordPress Config section.
The storage volume mounts at /var/www/html/wp-content/* to <PERSISTENT_STORAGE_DIR>/. Without it, uploaded files are lost on every deploy.
Site URL
The public URL of your site is injected as APP_URL. WordPress uses this to generate links, enqueue scripts, and handle redirects.
If you change your domain, update APP_URL and run a search-replace on the database to update stored URLs:
cc wp search-replace 'https://old-domain.com' 'https://new-domain.com' --all-tables
You would need to proxy connect to the MySQL Database or run a search and replace plugin once the domain changes.
See Routing for more on domain configuration.
PHP Settings (WORDPRESS_CUSTOM_INI)
Override PHP configuration values using the WORDPRESS_CUSTOM_INI environment variable. Values are written to a .ini file loaded by PHP-FPM on startup.
WORDPRESS_CUSTOM_INI=memory_limit = 512M
upload_max_filesize = 128M
post_max_size = 128M
max_execution_time = 120
Multiple settings are separated by newlines.
Common PHP settings
| Setting | Default | Description |
|---|---|---|
memory_limit | 256M | Max memory per PHP request |
upload_max_filesize | from MAX_UPLOAD_SIZE | Max size of a single uploaded file |
post_max_size | from MAX_UPLOAD_SIZE | Max total POST body size |
max_execution_time | 60 | Max seconds a PHP request may run |
max_input_vars | 3000 | Max number of input variables (increase for complex ACF layouts) |
opcache.validate_timestamps | 1 | Set to 0 on production to skip file-change checks |
opcache.jit | off | Set to tracing to enable PHP 8 JIT |
opcache.jit_buffer_size | — | Set to 64M when enabling JIT |
See Performance for a full tuning guide.
Upload Size (MAX_UPLOAD_SIZE)
Set a single variable to configure the upload limit consistently across both nginx and PHP:
MAX_UPLOAD_SIZE=128M
This sets:
- Nginx
client_max_body_size - PHP
upload_max_filesize - PHP
post_max_size
Accepted suffixes: M (megabytes), G (gigabytes). Default is 64M.
If you also set upload_max_filesize or post_max_size via WORDPRESS_CUSTOM_INI, those values override MAX_UPLOAD_SIZE for PHP only.
PHP-FPM Pool (WORDPRESS_FPM_CONF)
Override PHP-FPM process manager settings using WORDPRESS_FPM_CONF. Values are appended to the [www] pool configuration.
WORDPRESS_FPM_CONF=[www]
pm = dynamic
pm.max_children = 5
pm.start_servers = 2
pm.min_spare_servers = 2
pm.max_spare_servers = 3
Choosing the right worker count
A typical WordPress page uses 30–80 MB of memory per worker. WooCommerce pages may use 100–150 MB. Estimate:
max_children ≈ available_memory ÷ average_worker_memory
Recommended settings by capsule size:
| Capsule RAM | pm | max_children | Notes |
|---|---|---|---|
| 512 MB | dynamic | 3 | Minimal |
| 1 GB | dynamic | 5 | Small blog or portfolio |
| 2 GB | static | 8 | Medium site with consistent traffic |
| 4 GB | static | 16 | WooCommerce or high-traffic content |
See Performance for the full scaling guide.
Security Configuration
| Variable | Default | Description |
|---|---|---|
SESSION_COOKIE_SECURE | 1 | HTTPS-only session cookies. Set to 0 for local development. |
CSP_HEADER | permissive default | Content-Security-Policy header value. Empty string to disable. |
XMLRPC_ENABLED | false | Enable XML-RPC endpoint (required for Jetpack and the WordPress mobile app) |
NGINX_EXTRA_CONF | — | Raw nginx directives injected into the server block |
See Security for the full security reference.
Caching Configuration
| Variable | Default | Description |
|---|---|---|
CACHE_TTL_SECONDS | unset (disabled) | Page cache TTL in seconds. Must be a positive integer. Unset to disable. |
DEBUG_HEADERS | false | Expose X-Cache header for cache diagnostics |
See Caching for the full caching reference.
Cron Configuration
| Variable | Default | Description |
|---|---|---|
DISABLE_PUBLIC_WP_CRON | true | Restrict wp-cron.php to internal platform calls only |
Also set in WORDPRESS_CONFIG_EXTRA:
define('DISABLE_WP_CRON', true);
See Cron for the full cron reference.
Rate Limiting
| Variable | Default | Description |
|---|---|---|
RATE_LIMIT_NORMAL_ROUTES_RPM | 120 | Requests per minute for public pages |
RATE_LIMIT_PROTECTED_ROUTES_RPM | 30 | Requests per minute for wp-admin and wp-login.php |
RATE_LIMIT_API_ROUTES_RPM | 60 | Requests per minute for the REST API |
RATE_LIMIT_MAX_CONN_PER_IP | 30 | Max concurrent connections per IP address |
All Environment Variables
| Variable | Default | Description |
|---|---|---|
WORDPRESS_DB_HOST | injected | MySQL host |
WORDPRESS_DB_NAME | app | Database name |
WORDPRESS_DB_USER | injected | Database username |
WORDPRESS_DB_PASSWORD | injected | Database password |
APP_URL | injected | Site public URL |
MAX_UPLOAD_SIZE | 64M | Upload limit for nginx and PHP |
WORDPRESS_CUSTOM_INI | — | PHP ini overrides (newline-separated) |
WORDPRESS_FPM_CONF | — | PHP-FPM pool overrides (ini format) |
WORDPRESS_CONFIG_EXTRA | — | PHP constants injected into wp-config.php |
CACHE_TTL_SECONDS | unset (disabled) | Page cache TTL in seconds. Unset to disable caching. |
DEBUG_HEADERS | false | Expose X-Cache response header |
DISABLE_PUBLIC_WP_CRON | true | Restrict wp-cron.php to internal access |
XMLRPC_ENABLED | false | Enable XML-RPC endpoint |
CSP_HEADER | permissive | Content-Security-Policy header value |
SESSION_COOKIE_SECURE | 1 | HTTPS-only session cookies |
RATE_LIMIT_NORMAL_ROUTES_RPM | 120 | Rate limit for public routes |
RATE_LIMIT_PROTECTED_ROUTES_RPM | 30 | Rate limit for admin routes |
RATE_LIMIT_API_ROUTES_RPM | 60 | Rate limit for REST API |
RATE_LIMIT_MAX_CONN_PER_IP | 30 | Max concurrent connections per IP |
NGINX_EXTRA_CONF | — | Custom nginx directives in the server block |