Adfish Docs

Appearance

Getting Started ​

Complete first-time setup guide for the Adfish WordPress development environment.

Prerequisites ​

Docker ​

Install Docker Desktop (Mac/Windows) or Docker Engine + the Compose plugin (Linux). Verify both are available:

bash
docker --version
docker compose version

PHP and Composer ​

Required on the host for PHPCS (code standards checking). PHP 8.2 is recommended to match the container.

bash
php --version
composer --version

AWS CLI ​

The project uses the default AWS profile (the named adfish profile was removed). Configure it:

bash
aws configure
# Enter: Access Key ID, Secret Access Key, region (us-east-1), output (json)

Verify access:

bash
aws sts get-caller-identity

Terraform >= 1.5 ​

Install via tfenv or the official binary. Do not use the snap package on Linux — it cannot read ~/.aws/credentials due to sandbox restrictions. Use apt install terraform or the manual binary instead.

bash
terraform version

SSH key ​

An ED25519 key pair named adfish-dev is used for SSH access to Lightsail instances. The private key lives at ~/.ssh/adfish-dev. If you do not have this key, get it from the team — it is not in the repository.

The corresponding public key is registered as a Lightsail key pair in AWS. This is the same key used by GitHub Actions for deploys.

Access to milkshake (for local HTTPS) ​

The local development domain adfish.dev.milkshake10.com is served over HTTPS via a LAN server called milkshake (192.168.8.115). To use the local domain:

  • You must be on the milkshake LAN
  • milkshake must be reachable via SSH (ssh milkshake)
  • The Route 53 wildcard record *.dev.milkshake10.com → 192.168.8.115 must resolve

If you are working off-LAN, see local-dev.md for alternative options.

Clone the repository ​

bash
git clone git@github.com:nickgourley/adfish-wp.git
cd adfish-wp

Install Composer dependencies. This installs CMB2, WPackagist plugins (SEO Framework, WP Super Cache, Classic Editor), PHPCS, PHPUnit, and wp-phpunit:

bash
composer install

Configure the environment ​

Copy the example env file:

bash
cp .env.example .env

Open .env and set your local domain:

bash
LOCAL_DOMAIN=adfish.dev.milkshake10.com

Other values in .env — database credentials, WordPress salts, admin user — are pre-filled with sensible defaults for local development. You should not need to change them unless you are running multiple sites simultaneously.

Start the environment ​

bash
make up

This starts the WordPress container (PHP 8.2 + Apache) and the MySQL 8.0 container in the background.

First-time WordPress installation ​

On a fresh database volume, the database is empty. Run the WordPress install:

bash
make wp cmd='core install \
  --url=https://adfish.dev.milkshake10.com \
  --title="Adfish Dev" \
  --admin_user=admin \
  --admin_password=password \
  --admin_email=dev@example.com'

Then create the test database (needed once per fresh database volume):

bash
make test-db

On subsequent starts, make up is all you need.

Verify the setup ​

Open https://adfish.dev.milkshake10.com in your browser. You should see the WordPress site.

WordPress admin: https://adfish.dev.milkshake10.com/wp-admin

Default credentials (local only): admin / password

Check that the plugin and theme are active:

bash
make wp cmd='plugin list --status=active'
make wp cmd='theme list --status=active'

You should see adfish-core in plugins and adfish-theme-stafwf as the active theme.

Pull real content from the server (optional) ​

If the server is running and you want to work with real content locally:

bash
make pull

This downloads the server database and uploads, rewrites URLs for local development, and places uploads in ./uploads/. See deployment.md for the full pull/push workflow.

WARNING

make pull overwrites your local database. A backup is saved to ./backups/ before the pull.

Common first-day tasks ​

bash
# Check code standards
composer phpcs

# Run the test suite
make test

# View container logs
make logs

# Shell into the WordPress container
make shell

# Run a WP-CLI command
make wp cmd='option get siteurl'

Troubleshooting first-time setup ​

Domain does not resolve: Confirm you are on the milkshake LAN. The DNS record *.dev.milkshake10.com only resolves to 192.168.8.115 from within the LAN.

WordPress shows database connection error: The MySQL container may still be starting. Wait a few seconds and try make up again, or check make logs for MySQL startup messages.

Composer autoloader not found: Run composer install on the host. The ./vendor directory is bind-mounted into the container at /var/www/html/vendor.

PHP errors in the browser: Errors are logged to wp-content/debug.log inside the container. Check with:

bash
make shell
tail -f /var/www/html/wp-content/debug.log

See troubleshooting.md for more common issues.

Adfish Group internal documentation