StarterKit foundation - is a WordPress environment boilerplate for fast and easy start projects with docker containers, convenient credential settings, improved configuration.
- Docker Engine v24+
- Docker Compose v2.21+
- GitHub SSH key or Personal Access Token
-
Check your GitHub SSH with
ssh -T git@github.com
or use PAT in.env.secret
COMPOSER_AUTH
-
Create a new project directory and clone this repository into the project folder.
-
Update environment variables in the
./config/environment/.env.main
file. ChangeAPP_NAME
, etc. -
Update
./config/environment/.env.type.local
,.env.type.dev
,.env.type.stage
,.env.type.prod
- specific environment types for local, development, staging, and production. You can add any new environment type. ChangeAPP_DOMAIN
, and other variables -
Follow next installation steps.
-
Create a project folder and clone this repository if you haven't already done so
-
Run installation process:
make install [environment_type]
Where environment_type
- any type that exist in ./config/environment/.env.type.*.
local
is the default. This will create a .env.secrets
file with passwords, run PHP Composer, and NPM dependencies installation, build containers, set up the database, with WordPress tables, and create a wp-admin user. So, as a result, the project will be fully accessible in the browser with the domain you added to .env.type
files.
For example, to use production environment run:
make install prod
And .env.type.prod
will be used with defined APP_DOMAIN, APP_PROTOCOL, and other settings.
BTW: We recommend using the /srv
folder instead of /var/www
for your web content. This recommendation is based on the Filesystem Hierarchy Standard (FHS), which suggests /srv for site-specific data served by the system.
The project is ready to use immediately after installation, but you can stop, recreate, launch the containers in different environments. To run containers use command:
make up [environment_type]
Where environment_type
- any type that exist in ./config/environment/.env.type.*
. local
is the default.
Examples:
make up
make up stage
make up prod
Do not edit the automatically concatenated root .env
file. It will be overwritten every time the app runs.
After the installation, you can add your custom secrets π to .env.secret
, but keep in mind that your secrets will not appear in the repository and will not be visible to other users. There is a ./sh/env/.env.secret.template
file for this. It has a template of secrets, without secret data.
You can add secret variables names there without secret data, just for structure. A password generator will replace the special word generate_this_pass
with the real password when you run make install
or make secret
(bash sh/env/secret-gen.sh
).
To run PHP Composer, you need to run the composer
container and enter it:
make run composer
Command make run <service_name>
will run bash inside selected service (container).
Inside the container, you can use the command line to run any command you need in any folder of your project. For example, to install packages defined in the main composer.json file, in default folder /srv
use:
composer install
or
composer update
To use watch with BrowserSync run:
make watch
To run other npm scripts need to run node
container and enter it:
make run node
It has another default folder /srv/web
- root WordPress folder. Use cd
command to go to your theme and run any command.
- Place your certificate files in
./config/nginx/ssl/
with the names<your-app-domain.com>.crt
and<your-app-domain.com>.key
. - Update the variable
APP_PROTOCOL=https
in your.env.type.prod
file to enable HTTPS. - Start containers with HTTP to HTTPS redirect:
make up prod
The configuration file ./config/nginx/templates/config/https.conf.template
will be used instead of ./config/nginx/templates/config/http.conf.template
make install [environment_type]
make secret
make watch
- run node watchermake up [environment_type]
-docker compose up -d --build
make upd [environment_type]
-docker compose up --build
make down
-docker compose down -v
make restart
-docker compose restart
make recreate
-docker compose up -d --build --force-recreate
make import <sql_file_name>
- import sql file to WordPress databasemake export
- will export current database to sql filemake replace [search_domain] [replace_domain]
- search replace domain in the databasemake pma
make run <service_name>
-docker compose run -it --rm .... <service_name> ...
make exec <service_name>
-docker compose exec -it .... <service_name> ...
make lint
- run php, js, and css lintersmake docker clean
- remove all built containers, images, volumes, etc
Image names are defined in ./config/environment/.env.main
. Images are pulled from the registry by Docker. Use a custom containers registry for your project's Docker containers, such as GitHub Registry or Docker Hub.
To build and push images to the registry, use the following commands from the root of your project directory:
make docker build
make docker push
βββ backups/ # Daily and weekly WordPress media, and database backups
βββ config/ # Global config files
βββ db-data/ # Database docker mounted volume
βββ dockerfiles/ # Docker images (Dockerfiles). Need just for build
βββ iac/ # IaC Terraform and Ansible configuration for server setup
βββ logs/ # System and WordPress logs
βββ sh/ # Bash scripts
β βββ cron/ # Cron scripts
β βββ database/ # Database management
β βββ env/ # Operations with environment files
β βββ utils/ # Additional bash utils
β βββ wp-cli/ # Scripts that used WP-CLI commands
βββ web/ # Web application folder
β βββ wp-config/ # wp-config.php & files that should be copied to web root dir
β βββ wp-content/ # wp-content folder
β β βββ mu-plugins/ # Must use plugins
β β βββ plugins/ # Plugins folder. Add your plugins here
β β βββ themes/ # Themes folder. Add your theme here
β β βββ uploads/ # Media uploads folder. All subfolders content is gitignored
β βββ wp-core/ # WordPress core files, docker mounted volume
βββ composer.json # Manage version of WordPress, plugins & dependencies
βββ docker-compose.build.yml # Docker compose configuration file with utility services
βββ docker-compose.yml # Main docker compose file
βββ Makefile # Make commands configuration
wp-config
folder contents will copy to wp-core
folder every time composer update/install runs.
wp-content
- docker mounted WordPress folder. Add plugins and custom theme here.
wp-core
- web public directory. WordPress core files. Do not edit files in this folder, it installs by composer.
Docker containers do not have a custom SMTP server. We use an SMTP relay service. You can set up an SMTP server like Gmail, AWS, Sendinblue, Mailgun, etc, or use another server you like.
Just edit sSMTP config block in your .env.secret
file.
sSMTP config files ./docker/wordpress/config/ssmtp.conf.template
and ./docker/wordpress/config/revaliases.template
automatically loaded into the WordPress container
See an example of ssmtp.conf
You can use an SSH tunnel to connect to database from an external app (for example MySQL Workbench, HeidiSQL or PHPStorm)
- Uncomment ports directive in database service in
docker-compose.yml
ports:
- 127.0.0.1:${SSH_TUNNEL_EXT_PORT}:3306
-
Edit the
.env.main
file, findSSH_TUNNEL_EXT_PORT
- make sure that the port is unique. If you are using multiple instances, change the port value. -
Open your database management app and configure SSH tunnel, database connection
To use phpMyadmin need to run the phpMyadmin container first. It's not running by default.
-
Edit the
.env.main
file, findPMA_EXT_PORT
- make sure that the port is unique. If you are using multiple instances, change the port value. -
Run phpMyadmin container:
make pma
- Open the
your-app-domain.com:PMA_EXT_PORT
URL in the browser to access phpMyadmin. For example, we usePMA_EXT_PORT=8801
. Openyour-app-domain.com:8801
- In
docker-compose.yml
file uncommentcommand: --skip-grant-tables
in mariadb service - Restart containers:
make restart
- Enter inside mariadb container:
make exec mariadb
- Inside container run:
mariadb> FLUSH PRIVILEGES; ALTER USER 'root'@'%' IDENTIFIED BY 'new_password';
Where 'new_password' - new root password
You can reset another database user password too - just change the username, host, and add new password.
For example, there are two root
users in database - with %
host and with localhost
. Use this command to see all users:
SELECT User, Host FROM mysql.user;
-
Revert back changes in
docker-compose.yml
-
Restart containers:
make restart
For control your servers infrastructure use following steps:
- Check
./iac/terraform/*.tf
files, update your provider and infrastructure settings - Add provider credentials. For example for AWS use
~/.aws/credentials
file. Addaws_access_key_id
andaws_secret_access_key
. Configuration and credential file settings - Add your deployment public key
id_rsa.pub
to./iac/terraform/public_keys/
folder - Run terraform commands:
make terraform [command]
Examples:
make terraform init
make terraform plan
make terraform apply
For running server setup automations use this steps:
- Add public key to
~/authorized_keys
file on servers (usemake terraform apply
command if you haven't already done so) - Check your credentials in
./.ssh
folder. Use ssh config file to simplify connections. - Check
./iac/ansible/inventory.yml
servers and credentials, host names should be the same as on ssh config file. - Check
./iac/ansible/playbook.yml
file hosts and tasks. Hosts must correspond to inventory hosts. - Run ansible command:
make ansible
This will run main playbook ansible-playbook -i iac/ansible/inventory.yml iac/ansible/playbook.yml
for all hosts.
To run playbook for specific host use command:
make ansible -- --limit [host]
After that you will be able to run CI/CD deployment pipelines automations.
Use GitHub Actions, GitLab CI/CD or other pipelines.
- Add deploy public key to
~/authorized_keys
file on servers (usemake terraform apply
command if you haven't already done so) - Check required apps already installed on servers (use
make ansible
command if you haven't already done so) - Add secrets variables to repo options:
SSH_KEY
- Private key from deploy pair that used for servers accessSSH_CONFIG
- SSH config for servers with address, port, user, etc. See the exampleCOMPOSER_AUTH
- Composer authentication JSON object with Personal Access Token, see Managing your personal access tokens on GitHub and Personal access tokens on GitLab. For local usage in.env.secret
file use a serialized unescaped JSON object without spaces, for GitHub secrets use escaped JSON object without spaces.
SSH config example:
# SSH_CONFIG
Host *
IdentitiesOnly yes
StrictHostKeyChecking no
# Develop server ssh alias
Host develop.starter-kit.io
HostName 00.00.00.00
User serverusername
Port 22
# Prod server ssh alias
Host starter-kit.io
HostName 00.00.00.00
User serverusername
Port 22
COMPOSER_AUTH example for GitHub secrets:
{\"github-oauth\":{\"github.com\":\"ACCESS_TOKEN_GITHUB\"}}
COMPOSER_AUTH example for local usage:
{"github-oauth":{"github.com":"ACCESS_TOKEN_GITHUB"}}
- Check CI/CD jobs config file, use
./.github
for GitHub Actions - Push some changes to deployment branch and check pipelines logs
The system has automatic backups. Launched by a cronjob. By default, daily and weekly backups work. With a retention period of 7 and 31 days, respectively. You can customize the frequency and content of backups yourself.
To activate backups:
-
Edit
./config/environment/.env.type.[environment_type]
file - enableAPP_WP_BACKUP_ENABLE
-
Check crontab file in
./config/crontabs
- change cronjob time if it needs. -
If you have more than one database (maybe custom databases), check
mariadb-dump
command parameters in./docker/cron/start-backup.sh
Backups will appear in the ./backups
folder, logs in the docker cron container logs
Contributions are welcome from everyone. Developing with β€οΈ.