Setup

This guide walks through setting up the local development environment from a fresh clone. Make sure you have all prerequisites installed first.

Automated Setup (Recommended)

The setup script handles Composer dependencies, .env creation, and Docker container startup in one step:

git clone git@github.com:Tinnitus-App/tinnitus-wordpress.git
cd tinnitus-wordpress
./scripts/setup.sh

The script performs the following:

1. Runs composer install to download WordPress core, plugins, and dev tools
2. Copies .env.example to .env and sets Docker-friendly defaults (DB_HOST='db', DB_NAME='wordpress', etc.)
3. Starts Docker containers with docker compose up -d --build

After the script completes, the site is available at http://localhost:8080.

Generate Security Salts

The setup script does not generate unique security salts. Visit roots.io/salts.html, generate a set of salts, and paste them into .env, replacing the generateme placeholder values.

Warning

Do not skip salt generation. The placeholder values are publicly known and provide no security.

Manual Setup

If you prefer to run each step yourself:

git clone git@github.com:Tinnitus-App/tinnitus-wordpress.git
cd tinnitus-wordpress

# 1. Install Composer dependencies
composer install

# 2. Create environment file
cp .env.example .env

# 3. Edit .env with Docker-appropriate values

Open .env and set these values:

DB_NAME='wordpress'
DB_USER='wordpress'
DB_PASSWORD='wordpress'
DB_HOST='db'
WP_HOME='http://localhost:8080'

Then generate and paste in unique salts from roots.io/salts.html.

# 4. Install frontend dependencies
npm install

# 5. Start containers
docker compose up -d --build

Docker Services

The docker-compose.yml defines two services:

Service	Image	Port	Purpose
wordpress	Custom (Dockerfile)	8080	PHP + Apache serving the Bedrock project
db	mariadb:10.6	3306	MariaDB database with health checks

The database uses a named volume (db_data) so data persists across container restarts. To reset the database entirely:

docker compose down -v

Verify the Installation

Once containers are running, confirm:

1. Site loads: Open http://localhost:8080. On first run, you will see the WordPress installation wizard.
2. Database connects: The WordPress installer reaching the "site title" step confirms the database connection is working.

3. Containers are healthy:

   docker compose ps
   

   Both services should show status Up (the db service should report (healthy)).

Note

If the site does not load, check docker compose logs wordpress for errors. The most common issue is the database container still starting up --- the health check ensures WordPress waits, but the first build can take a minute.

Daily Workflow

After initial setup, you only need:

docker compose up -d     # Start containers
docker compose down      # Stop containers
docker compose logs -f   # Follow logs (useful for debugging)

For the full list of available commands, see the Commands reference.

Next: First Steps covers accessing the admin panel, running quality checks, and building the theme CSS.