itabara / wordpress-starter

A slightly less shitty wordpress development workflow

Visible Wordpress Starter

A Docker Wordpress development environment by the team at Visible and some awesome contributors. Our goal is to make Wordpress development slightly less frustrating.

Requirements

Well, to run a Docker environment, you will need Docker. The Dockerfile is only for an Apache+PHP+Wordpress container, you will need a MySQL container to run a website. We use Docker Compose 1.6+ for the orchestration.

---

Getting started

This project has 2 parts: the Docker environment and a set of tools for theme development. To quickly get started, you can simply run the following:

# copy the files
git clone https://github.com/visiblevc/wordpress-starter.git
rm -rf .git Dockerfile run.sh

# start the website at localhost:8080
docker-compose up

---

Documentation

We wrote a series of articles explaining in depth the philosophy behind this project:

• Intro: A slightly less shitty WordPress developer workflow
• Part 1: Setup a local development environment for WordPress with Docker
• Part 2: Setup an asset pipeline for WordPress theme development
• Part 3: Optimize your wordpress theme assets and deploy to S3
• Part 4: Auto deploy your site on your server (coming)

The Docker environment

The only thing you need to get started is a docker-compose.yml file:

version: '2'
services:
  data:
    image: busybox
    volumes:
      - /app
      - /var/lib/mysql
  wordpress:
    image: visiblevc/wordpress:latest
    links:
      - db
    ports:
      - 8080:80
      - 443:443
    volumes:
      - ./data:/data # Required if importing an existing database
      - ./wp-content/uploads:/app/wp-content/uploads
      - ./yourplugin:/app/wp-content/plugins/yourplugin # Plugin development
      - ./yourtheme:/app/wp-content/themes/yourtheme   # Theme development
    environment:
      DB_NAME: wordpress
      DB_PASS: root # must match below
      PLUGINS: >-
        academic-bloggers-toolkit,
        co-authors-plus
      SEARCH_REPLACE: yoursite.com,localhost:8080
      WP_DEBUG: true
  db:
    image: mysql:5.7
    ports:
      - 3306:3306
    volumes:
      - data:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: root
volumes:
  data: {}

MySQL Credentials

• username: root
• password: root (can be changed with the MYSQL_ROOT_PASSWORD and DB_PASS environment variables)
• database: wordpress (can be changed with the DB_NAME environment variable)
• admin email: admin@${DB_NAME}.com

WordPress Container Environment variables

• DB_PASS (required): Must match MYSQL_ROOT_PASSWORD of the mysql container
• DB_NAME (optional): Defaults to wordpress
• ADMIN_EMAIL (optional): Defaults to admin@${DB_NAME}.com
• WP_DEBUG (optional): Defaults to false
• THEMES (optional): Comma-separated list of themes you want to install.
• PLUGINS (optional): Comma-separated list of plugins you want to install.
• SEARCH_REPLACE (optional): Comma-separated string in the form of current-url,replacement-url.
  • When defined, current-url will be replaced with replacement-url on build (useful for development environments utilizing a database copied from a live site).
  • IMPORTANT NOTE: If you are running Docker on Mac or PC (using Docker Machine), your replacement url MUST be the output of the following command: echo $(docker-machine ip <your-machine-name>):8080

DB Container Environment variables

• MYSQL_ROOT_PASSWORD (required): Must match DB_PASS of the wordpress container

Working with databases

If you have an exported .sql file from an existing website, drop the file into the data/ folder. The first time you run the container, it will detect the SQL dump and use it as a database. If it doesn't find one, it will create a fresh database.

If the SQL dump changes for some reason, you can reload the database by running:

docker-compose run wordpress wp db import "$(find /data/*.sql | head -n 1)" --allow-root

If you want to create a dump of your development database, you can run:

docker-compose run wordpress wp db export /data --allow-root

Finally, sometimes your development environment runs on a different domain than your live one. The live will be example.com and the development localhost:8080. This project does a search and replace for you. You can set the SEARCH_REPLACE: example.com,localhost:8080 environment variable in the docker-compose.yml.

Use wp-cli

You can access wp-cli by running npm run wp .... Here are some examples:

npm run wp plugin install <some-plugin>
npm run wp db import /data/database.sql

---

Development

You can find Development instructions in the Wiki.