Start a WordPress Project with Docker in 3 Easy Steps
- Run
kool create wordpress my-project - Run
kool start - Update Database Information
Yes, using kool + Docker to create and work on new WordPress projects is that easy!
Requirements
If you haven't done so already, you first need to install Docker and the kool CLI.
Also, make sure you're running the latest version of kool. Run the following command to compare your local version of kool with the latest release, and, if a newer version is available, automatically download and install it.
$ kool self-update
Please note that it helps to have a basic understanding of how Docker and Docker Compose work to use Kool with Docker.
1. Run kool create wordpress my-project
Use the kool create PRESET FOLDER command to create your new WordPress project:
$ kool create wordpress my-project
Under the hood, this command will create your project directory and automatically run kool preset wordpress, which helps you easily set up the initial tech stack for your project using an interactive wizard.
$ Preset wordpress is initializing!
? Which PHP version do you want to use [Use arrows to move, type to filter]
> PHP 8.0
PHP 7.4
? Which database service do you want to use [Use arrows to move, type to filter]
> MySQL 8.0
MySQL 5.7
PostgreSQL 13.0
none
? Which cache service do you want to use [Use arrows to move, type to filter]
> Redis 6.0
Memcached 1.6
none
? Which javascript package manager do you want to use [Use arrows to move, type to filter]
> npm
yarn
$ Preset wordpress initialized!
Now, move into your new WordPress project:
$ cd my-project
The kool preset command auto-generated the following configuration files and added them to your project, which you can modify and extend.
+.env
+docker-compose.yml
+kool.yml
While WordPress does not normally use .env files, one was added to your project to store the DB_USERNAME and DB_PASSWORD credentials needed to open a SQL client session in your database container using kool run mysql or kool run psql, depending on which database you selected (see the "Connect to Docker Database Container" section below).
Now's a good time to review the docker-compose.yml file and verify the services match the choices you made earlier using the wizard.
2. Run kool start
Run the kool start command to spin up your Docker environment using a Kool-optimized Docker image and the docker-compose.yml file generated by kool create. The kool start process will also automatically copy all the WordPress files into your project directory.
$ kool start
Once kool start finishes, verify your Docker container is running using the kool status command.
+----------+---------+------------------------------------------------------+---------------------------------+
| SERVICE | RUNNING | PORTS | STATE |
+----------+---------+------------------------------------------------------+---------------------------------+
| app | Running | 0.0.0.0:80->80/tcp, :::80->80/tcp, 9000/tcp | Up 9 seconds |
| cache | Running | 6379/tcp | Up 9 seconds (health: starting) |
| database | Running | 0.0.0.0:3306->3306/tcp, :::3306->3306/tcp, 33060/tcp | Up 9 seconds (health: starting) |
+----------+---------+------------------------------------------------------+---------------------------------+
Run kool logs app to see the logs from the running app container.
Use
kool logsto see the logs from all running containers. Add the-foption afterkool logsto follow the logs (i.e.kool logs -f app).
$ kool logs app
Attaching to my-project_app_1
app_1 | WordPress not found in /app - copying now...
app_1 | WARNING: /app is not empty! (copying anyhow)
app_1 | Complete! WordPress has been successfully copied to /app
app_1 | time="2021-05-01T21:02:05Z" level=info msg="create process:php-fpm"
app_1 | time="2021-05-01T21:02:05Z" level=info msg="create process:nginx"
app_1 | time="2021-05-01T21:02:05Z" level=info msg="stop listening"
app_1 | time="2021-05-01T21:02:05Z" level=info msg="try to start program" program=php-fpm
app_1 | time="2021-05-01T21:02:05Z" level=info msg="try to start program" program=nginx
app_1 | time="2021-05-01T21:02:05Z" level=debug msg="wait program exit" program=nginx
app_1 | time="2021-05-01T21:02:05Z" level=debug msg="wait program exit" program=php-fpm
app_1 | [01-May-2021 21:02:05] NOTICE: fpm is running, pid 28
app_1 | [01-May-2021 21:02:05] NOTICE: ready to handle connections
app_1 | time="2021-05-01T21:02:06Z" level=info msg="success to start program" program=php-fpm
app_1 | time="2021-05-01T21:02:06Z" level=info msg="success to start program" program=nginx
3. Update Database Information
You should now be able to access your new WordPress installation at http://localhost and see the WordPress welcome page (or, right after you select your language). Hooray!
In order to get started, WordPress will ask you for some information about the database. Use the following default values to match the settings in your auto-generated docker-compose.yml file.
| Database Settings | Default Value |
|---|---|
| Database Name | wordpress |
| Database Username | user |
| Database Password | pass |
| Database Host | database |
| Table Prefix | wp_ |
The "Database Username" and "Database Password" values must be the same as those in the .env file that was added to your project by
kool create.
After the wp-config.php file is created with the above database settings, you'll be asked to provide some more information to complete the installation process (i.e. Site Title, Username, Password, Email Address).
That's it! Log in to your new WordPress site, customize your theme, and start posting :)
Backups and Restoration
For backups and restoration, we recommend using Updraft Plus:
- Install Plugin on your local
- Create Backup
- Download Backup
- Install Plugin on the destination with a fresh WordPress Installation
- Upload Backup
- Restore it
Using Kool
Say hello to kool.yml, say goodbye to custom shell scripts!
As mentioned above, the kool preset command added a kool.yml file to your project. Think of kool.yml as a super easy-to-use task helper. Instead of writing custom shell scripts, add your own scripts to kool.yml (under the scripts key), and run them with kool run SCRIPT (e.g. kool run wp). You can add your own single line commands (see php below), or add a list of commands that will be executed in sequence.
To help get you started, kool.yml comes prebuilt with an initial set of scripts (based on the choices you made earlier using the preset wizard).
scripts:
mysql: kool exec -e MYSQL_PWD=$DB_PASSWORD database mysql -u $DB_USERNAME $DB_DATABASE
npm: kool exec app npm
npx: kool exec app npx
php: kool exec app php
wp: kool exec app wp
Run Commands in Docker Containers
Use kool exec to execute a command inside a running service container:
# kool exec [OPTIONS] SERVICE COMMAND [--] [ARG...]
$ kool exec app ls
Try kool run wp --info to execute the kool exec app wp --info command in your running app container and print out information about WordPress CLI.
Open Sessions in Docker Containers
Similar to SSH, if you want to open a Bash session in your app container, run kool exec app bash, where app is the name of the service container in docker-compose.yml. If you prefer, you can use sh instead of bash (kool exec app sh).
$ kool exec app bash
bash-5.1#
$ kool exec app sh
/app #
Connect to Docker Database Container
You can easily start a new SQL client session inside your running database container by executing kool run mysql (MySQL) or kool run psql (PostgreSQL) in your terminal. This runs the single-line mysql or psql script included in your kool.yml.
Access Private Repos and Packages in Docker Containers
If you need your app container to use your local SSH keys to pull private repositories and/or install private packages (which have been added as dependencies in your package.json file), you can simply add $HOME/.ssh:/home/kool/.ssh:delegated under the volumes key of the app service in your docker-compose.yml file. This maps a .ssh folder in the container to the .ssh folder on your host machine.
volumes:
- .:/app:delegated
+ - $HOME/.ssh:/home/kool/.ssh:delegated
Staying kool
When it's time to stop working on the project:
$ kool stop
And when you're ready to start work again:
$ kool start
Additional Presets
We have more presets to help you start projects with kool in a standardized way across different frameworks.
Missing a preset? Make a request, or contribute by opening a Pull Request. Go to https://github.com/kool-dev/kool/tree/main/presets and browse the code to learn more about how presets work.