Table of Contents
The 3 Musketeers is a pattern for developing software in a repeatable and consistent manner. It leverages Make as an orchestration tool to test, build, run, and deploy applications using Docker and Docker Compose. The Make and Docker/Compose commands for each application are maintained as part of the application’s source code and are invoked in the same way whether run locally or on a CI/CD server.
Run the same commands no matter where you are: Linux, MacOS, Windows, CI/CD tools that supports Docker like GitHub Actions, Travis CI, CircleCI, and GitLab CI.
Take control of languages, versions, and tools you need, and version source control your pipelines with your preferred VCS like GitHub and GitLab
Test your code and pipelines locally before your CI/CD tool runs it. Feel confident that if it works locally, it will work in your CI/CD server.
The demo was generated with VHS using the 3 Musketeers (source).
Let's print out Hello, World!
in the terminal using the 3 Musketeers. The command make echo
will be calling Docker to run the command echo 'Hello, World!'
inside a container.
Create the following 2 files:
# compose.yml
services:
alpine:
image: alpine
# Makefile
echo:
docker compose run --rm alpine echo 'Hello, World!'
Then simply run:
make echo
For more information, visit 3 Musketeers website.
This repository is the 3 Musketeers website built with VitePress. This section explains how to develop, test, and deploy using the 3 Musketeers.
- Docker
- Compose
- Make
- Cloudflare account
# Create a .env file
make envfile ENVFILE=env.example
# Install dependencies
make deps
# Start vitepress server for local development
make dev
# Wait till the message 'vite v2.5.3 dev server running at' appears
# Access the website in your browser at http://127.0.0.1:5173/
# \<ctrl-c\> to stop
# Build static site
make build
# Serve static site for local development
make serveDev
# Access the website in your browser at http://127.0.0.1:5173/
# \<ctrl-c\> to stop
# Serve static website (headless)
make serve
# Test static website
make test
# Prune
make prune
# Contributing? Make sure the following command runs successfully
make all
The 3 Musketeers website is deployed to Cloudflare Pages. This section shows how to create, deploy, and delete a Pages project using Wrangler CLI. This is handy for previewing new changes.
Given build, test and deployment are going to be done with GitHub Actions, this section follows the Direct Upload and Run Wrangler in CI/CD directives.
Lastly, this section assumes the application was built and tested (see previous section Development
).
To interact with Cloudflare Pages with Wrangler CLI, Cloudflare account ID and API token are required.
- Account ID: Find account and zone IDs
- API token
- Create API token
- Use
Edit Cloudflare Workers
template - Permissions:
- Account - Cloudflare Pages - Edit
- Set a TIL
- These values will be used in section
1. Envfile
- Do not forget to delete the API token once it is not longer used
The following sections use the values from the file .env
. Create file .env
(based on env.template
) with the correct values.
Example:
# .env
ENV_CLOUDFLARE_BRANCH_NAME=main
ENV_CLOUDFLARE_PROJECT_NAME=3musketeers-test
ENV_SECRET_CLOUDFLARE_ACCOUNT_ID=id-from-previous-section
ENV_SECRET_CLOUDFLARE_API_TOKEN=token-from-previous-section
Verify:
make shell
env | grep ENV_
# List current projects
npx wrangler pages project list
# If `ENV_CLOUDFLARE_PROJECT_NAME` is part of the list, skip section `2. Create`
# or update file `.env` with a new project name
exit
This section creates a new Pages project.
# All the following commands will be run inside a container
make shell
# Create a new project
npx wrangler pages project create "${ENV_CLOUDFLARE_PROJECT_NAME}" --production-branch="${ENV_CLOUDFLARE_BRANCH_NAME}"
#✨ Successfully created the '3musketeers-test' project. It will be available at https://3musketeers-test.pages.dev/ once you create your first deployment.
#To deploy a folder of assets, run 'wrangler pages deploy [directory]'.
# The new project should be listed and take note of the project domain
npx wrangler pages project list
# Project is empty which should not be hosted! (My project domain for this example is 3musketeers-test.pages.dev)
curl -I https://3musketeers-test.pages.dev
#HTTP/2 522
#...
# Exit the container
exit
This section deploys the website to an existing Cloudflare Pages project.
# All the following commands will be run inside a container
make shell
# Deploy!
npx wrangler pages deploy docs/.vitepress/dist \
--project-name="${ENV_CLOUDFLARE_PROJECT_NAME}" \
--branch="${ENV_CLOUDFLARE_BRANCH_NAME}" \
--commit-message="Deploy!"
#✨ Success! Uploaded 81 files (4.28 sec)
#✨ Deployment complete! Take a peek over at https://some-id.3musketeers-test.pages.dev
# Project is no longer empty!
curl -I https://3musketeers-test.pages.dev
#HTTP/2 200
#...
# Exit the container
exit
As a side note, make deploy
can be used instead.
This section shows how to delete a Cloudflare Pages project.
# All the following commands will be run inside a container
make shell
# Delete the Pages project
npx wrangler pages project delete "${ENV_CLOUDFLARE_PROJECT_NAME}"
#? Are you sure you want to delete "3musketeers-test"? This action cannot be undone. › y
#Deleting 3musketeers-test
#Successfully deleted 3musketeers-test
# Check the site is not there
curl -I https://3musketeers-test.pages.dev
#HTTP/2 530
#...
# Exit the container
exit
GitHub Actions is used to test PRs and deploy changes made to main
branch to Cloudflare Pages.
- A dedicated Cloudflare API token has been created for Github Actions
- Environment variables required for deploying to Cloudflare Pages are set as variables and secrets in GitHub Actions
- The GitHub Actions workflows follow the 3 Musketeers pattern
- 3 Musketeers logo
- Created by me with Procreate and Vectornator
- Neat tools used are offset path and mask objects
- 2048px by 2048px SVG image
- Images are in folder
docs/public/img
- Created by me with Procreate and Vectornator
- Favicon
- Source image is an exported png format of the logo
- Use the website favicon.io
- The generated content is in
docs/public/favicon_io
- File docs/public/favicon.io is a copy of the file in
docs/public/favicon_io
- By default, browsers searches for /favicon.io
- HTML
link
tags have been set in file/docs/.vitepress/config.js
- Social media preview
- This is for displaying preview of the website on Twitter, Facebook, GitHub, etc
- Created a new vector image 1280x640px with the scale down logo at the center
- The size is suggested by GitHub in General settings
- According to artegence article, the ideal image that works on different social platforms
- Is 1200x630px
- Has the logo (630x630) centered
- Use png format (very high quality and transparency)
- Use jpg format (high quality and very good size compression)
- HTML
meta
tags have been set in file/docs/.vitepress/config.js
- The social image is also set in the general settings of the repository
- Diagrams
Thanks goes to contributors.