Wordpress Site Setup (SCHOELLCONF2019)

README.md

Wordpress Site Setup

These notes are from Eran Schoellhorn's April 2019 walkthrough of Wordpress Site Setup using Docker.

Docker

We use Docker to manage the environment for each site. This way you don't need to concern yourself with mismatched versions or missing dependencies. Install it and run it if you haven't already.

A note about ports

Docker containers talk to each other through port-mapping. Traefik is a reverse proxy service that helps manage this through namespaced subdomains (eg. wordpress.myproject.docker.local vs mariadb.myproject.docker.local) which are easier to read. Traefik comes included in the next step!

Docker4WordPress

Docker4WordPress is a set of docker images optimized for WordPress. The default services are good, but you may also want to switch on these:

• phpMyAdmin for database management
• varnish for caching

Steps

1. Download the lastest release of Docker4WordPress and unzip it.

2. Move and/or rename the folder if you like. It will be your root project folder.

3. Edit the .env file.

   • Update the PROJECT_NAME (eg. my_project)
   • Update the PROJECT_BASE_URL (eg. my_project.docker.localhost) Note, this will become the basis for the "Local Dev URL", which includes protocol and port, (eg. http://my_project.docker.localhost:8000).

4. Edit docker-compose.override.yml and replace codebase with ./web. Note, while the name is arbitrary, Pantheon users may have issues calling it ./src.

5. Open a terminal window in the root folder and run make up. (Note that if you have another site running already, you may get port conflicts. Run make down on the other site to shut it down first.)

6. Open the Local Dev URL in a browser (ie. http://my_project.docker.localhost:8000). You can set up the site now, or do it later.

Theming

We use Sage for its preconfigured webpack pipeline and Blade templating language. To install Sage, we use Composer, a package manager tool for PHP. (You probably already have it installed.)

Steps

1. Delete the existing theme folders from wp-content/themes.

2. Access the Docker container file system from the root folder:

   make shell

3. Install Sage:

   composer create-project roots/sage my-theme

4. Answer the CLI prompts.

   • For "Local development URL of WP site", enter the Local Dev URL (eg. http://my_project.docker.localhost:8000).
   • For "Path to theme directory", enter the full path from the root (eg. /wp-content/themes/my-theme).

5. Open the Local Dev URL (eg. http://my_project.docker.localhost:8000), access the Wordpress admin, and switch to the new theme under "Appearance > Themes".

Build & Develop

Note: You may have issues with Node 11.x and up. If so, run these commands with Node 10.x.

Note: You will probably need to update your hosts file (manually or using Gas Mask and add 127.0.0.1 my_project.docker.localhost.

• Run yarn in the theme folder to install dependencies.
• Run yarn build to compile client assets (CSS, JS, etc.).
• Run yarn start in the theme folder. (This will open Browsersync on http://localhost:3000/.)

Customizing the Sage Theme

• Review composer.json and package.json for customization.
• Remember to modify the theme's README.md as you make changes to the theme.

Issues & Troubleshooting

• Mailhog may not capture all the sent emails when using another system like Mailgun.
• WooCommerce may be a pain with Blade templating.