> ## Documentation Index
> Fetch the complete documentation index at: https://paper.brimble.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Deploy WordPress
> A simple, step-by-step guide to put a WordPress site online on Brimble: database, WordPress, storage, security, and optional domain.
This guide is for site owners and WordPress builders. You do **not** need to know servers, Docker, or PHP under the hood.
Follow the steps in order. Each important screen has a screenshot so you can match what you see in the dashboard.
When you finish, you will have:
* A live WordPress site on a free Brimble address (`https://your-name.brimble.app`)
* A database that stores posts, pages, and users
* Storage so photos and plugins do not disappear when you redeploy
* Optional security for WordPress (recommended)
* Optional custom domain and small config files
## Before you start
| You need | Why |
| --------------------------------------------------- | ------------------------------------------- |
| A [Brimble account](https://app.brimble.io) | To use the dashboard |
| A plan that allows websites, databases, and storage | WordPress needs all three for a normal site |
| About 15-20 minutes | First setup takes a little longer |
Put the database and WordPress in the **same region** (for example both in Germany). That keeps the site faster and more reliable.
## The big picture
WordPress on Brimble is two projects that work together:
1. **A database**: where posts, pages, and logins are stored
2. **WordPress itself**: the website software, run from the official WordPress image
You create the **database first**, then create WordPress and connect it.
## Checklist
1. Create the database
2. Create WordPress and connect it
3. Turn on storage for uploads
4. Finish the setup wizard in your browser
5. Turn on WordPress protection (recommended)
6. (Optional) Add your own domain
7. (Optional) Raise upload limits with a small config file
***
## Step 1: Create the database first
WordPress cannot run without a database. Do this **before** you create the WordPress site.
1. Open the [Brimble dashboard](https://app.brimble.io).
2. Click **New project**.
3. Choose **Database**.
4. Pick **MySQL** or **MariaDB** (both work with WordPress).
5. Leave the version as the default unless you know you need another one.
6. Choose a **region**: remember it; WordPress must use the same one.
7. Pick a size. **Start small**; you can upgrade later.
8. Give it a clear name, for example `my-blog-db`.
9. Click **Create** / **Provision**.
Wait until the status is **Active** (often one or two minutes).
### Where the connection details live
Open the database project. You will see a list of **secrets** (connection details). You will copy these into WordPress in the next step.
You mainly need:
| What WordPress needs | What it looks like in the list |
| -------------------- | ---------------------------------------------------------------------------------------------- |
| Database host | Prefer the **private / internal** host when both projects are in the same workspace and region |
| Port | Usually shown as the service port |
| Username | MySQL / MariaDB user |
| Password | MySQL / MariaDB password |
| Database name | The database name |
**Recommended:** use the **private** connection when WordPress and the database are in the same place on Brimble. It is faster and stays on Brimble’s private network.
**Also fine:** use the **public** host if you prefer, or if private is not available.
More detail: [Deploy a database](/projects/deploy-a-database).
***
## Step 2: Create WordPress
1. Click **New project** again.
2. Choose **Docker image** (you are not connecting a Git repo for standard WordPress).
3. For the image name, use the official WordPress image, for example:
```text theme={null}
wordpress:latest
```
You can also use a more specific tag such as `wordpress:php8.2-apache` if you prefer.
4. Leave private registry credentials empty for this public image.
5. Choose the **same region** as the database.
6. Pick a small compute size to start.
7. Give the project a name (this becomes your free URL, for example `https://my-blog.brimble.app`).
### Secrets: how WordPress finds the database
On the create screen (and later under the **Secrets** tab), add these values.
**Important:** set **PORT** to **80**. The official WordPress image expects that.
| Name | What to put | Plain English |
| ----------------------- | ------------------------------------ | ------------------------------- |
| `PORT` | `80` | Which door WordPress listens on |
| `WORDPRESS_DB_HOST` | host and port, like `something:3306` | Where the database lives |
| `WORDPRESS_DB_USER` | from the database project | Login username for the database |
| `WORDPRESS_DB_PASSWORD` | from the database project | Login password for the database |
| `WORDPRESS_DB_NAME` | from the database project | Which database to use |
#### Easiest option: reference the database project
If your database project is named `my-blog-db`, you can point WordPress at it with **references** (Brimble fills in the real values at deploy time). Adjust the name to match **your** database project:
```bash theme={null}
PORT=80
WORDPRESS_DB_HOST={{@my-blog-db.PRIVATE_SERVICE_HOST}}:{{@my-blog-db.SERVICE_PORT}}
WORDPRESS_DB_USER={{@my-blog-db.MYSQL_USER}}
WORDPRESS_DB_PASSWORD={{@my-blog-db.MYSQL_PASSWORD}}
WORDPRESS_DB_NAME={{@my-blog-db.MYSQL_DATABASE}}
```
For a **public** host instead of private, use `SERVICE_HOST` instead of `PRIVATE_SERVICE_HOST`.
You can also open the database secrets list and paste the values by hand.
After the site exists, you can review or edit the same list under **Secrets**:
Learn more: [Environment variable references](/environments/env-references).
***
## Step 3: Turn on storage for uploads
If you skip storage, media uploads and many plugins can be lost when the site restarts or redeploys.
1. Turn on **Persistent Storage** (when creating the project, or later under **Configuration → Resources**).
2. Set the **mount path** exactly to:
```text theme={null}
/var/www/html/wp-content
```
That folder holds themes, plugins, and uploads.
**Do not** mount the whole site path (`/var/www/html`). Only **`wp-content`**.
You can create a **new** volume or attach one you already have in the same region.
### Storage price (typical)
Storage is charged by size each month. In the size dropdown you will see options similar to:
| Size | About |
| ----- | --------------- |
| 10 GB | \$2.50 / month |
| 20 GB | \$5.00 / month |
| 30 GB | \$7.50 / month |
| 40 GB | \$10.00 / month |
| 50 GB | \$12.50 / month |
| 60 GB | \$15.00 / month |
That is about **\$0.25 per GB per month**. Always trust the price shown in the dashboard.
**10 GB** is enough for most small sites.
### Deploy WordPress
Click **Deploy project**. Wait until the deploy finishes successfully.
***
## Step 4: Finish setup in your browser
1. Open your free URL: `https://YOUR-PROJECT-NAME.brimble.app`
2. Choose language, site title, and admin username.
3. Use a **strong** password (not `admin` / `password`).
4. Complete the wizard and log in to the WordPress dashboard.
You should see the normal WordPress home screen:
### If you see “Error establishing a database connection”
Work through this list:
* Database project status is **Active**
* All four `WORDPRESS_DB_*` secrets are filled in
* **PORT** is **80**
* Database host includes the **port** (for example `:3306`)
* Database and WordPress are in the **same region** if you used the private host
* You **redeployed** after changing secrets
***
## Step 5: Turn on WordPress protection (recommended)
This blocks common automated attacks on WordPress (fake logins, known exploit paths, and similar noise).
1. Open your **WordPress** project.
2. Open the **Networking** tab.
3. Under **Network** (edge cache, headers & firewall), click **Configure**.
4. Open the **Firewall** tab.
5. Turn **WordPress protection** **on**.
6. Leave **Path blocking** on.
7. Click **Save changes**.
A few plugins or phone apps need **XML-RPC**. If something stops working after you enable protection, turn WordPress protection off temporarily and contact support if you need a special rule. Most sites do not need XML-RPC open.
***
## Step 6: Add your own domain (optional)
Still on the **Networking** tab:
1. Click **+ Add domain**.
2. Follow the DNS instructions Brimble shows (usually at your domain registrar).
3. Wait until the domain shows as **Active** and HTTPS is ready.
Then in WordPress go to **Settings → General** and set:
* **WordPress Address (URL)** to your live `https://…` address
* **Site Address (URL)** to the same
Save.
Full guide: [Custom domains](/domains/custom-domains).
***
## Step 7: Larger uploads (optional)
If media uploads fail because files are “too large”, you can raise PHP limits with the **Files** feature.
This is for **small text config files only** (not for photos; photos go in the media library and live on your volume).
1. Open the WordPress project.
2. Open **Files** and click **Add file**.
3. Example:
| Field | Example |
| ---------- | --------------------------------------------------------------- |
| Name | `Custom WordPress configuration` |
| Mount path | `/usr/local/etc/php/conf.d/zz-custom.ini` |
| Secret | On if the file has sensitive values; off is fine for PHP limits |
Example file content:
```ini theme={null}
upload_max_filesize = 64M
post_max_size = 64M
memory_limit = 256M
max_execution_time = 120
```
4. Click **Create**.
5. **Redeploy** so the file is mounted.
6. Try the upload again.
Limits: text files only, **1 MB** max per file, path must start with `/`.
***
## Common problems
**Error establishing a database connection**\
Check Active database, secrets, PORT **80**, same region for private host, then redeploy.
**Uploads disappear after redeploy**\
Turn on persistent storage at `/var/www/html/wp-content`.
**Site feels broken after attaching storage**\
Mount path must be `/var/www/html/wp-content`, not `/var/www/html`.
**Upload says file is too large**\
Use Step 7 (Files) and check free space on the volume.
**Extra check page when logging in**\
WordPress protection may show a short browser check. Complete it, or turn protection off temporarily.
**App or plugin that needs XML-RPC stopped working**\
Turn WordPress protection off or ask support for a custom rule.
**Site shows an error right after deploy**\
Wait a minute for first boot, open **Deployments** / logs, confirm the image is `wordpress:…` and **PORT is 80**.
***
## Quick checklist before you go live
* [ ] Strong WordPress admin password
* [ ] Database created **before** WordPress
* [ ] Private database host when possible
* [ ] **PORT** is **80**
* [ ] Storage at `/var/www/html/wp-content`
* [ ] **WordPress protection** on
* [ ] **Path blocking** on
* [ ] Site URLs use **https\://** in WordPress settings
* [ ] Only trusted plugins and themes; keep WordPress updated
***
## Related guides
* [Deploy a database](/projects/deploy-a-database)
* [Deploy from a Docker image](/projects/deploy-from-docker-image)
* [Persistent disk](/projects/persistent-disk)
* [Volumes](/volumes/overview)
* [Environment variables](/environments/environment-variables)
* [Environment variable references](/environments/env-references)
* [Custom domains](/domains/custom-domains)
* [Networking overview](/networking/overview)