3 Musketeers

Test, build, and deploy your apps from anywhere, the same way!

Overview

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.

Why?

Consistency

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.

Control

Take control of languages, versions, and tools you need, and version source control your pipelines with your preferred VCS like GitHub and GitLab

Confidence

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.

Demo

The demo was generated with VHS using the 3 Musketeers (source).

Getting started

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.

Prerequisites

• Docker
• Compose
• Make

Hello, World!

Create the following 2 files:

# docker-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.

3 Musketeers website development

This repository is the 3 Musketeers website built with VitePress. This section explains how to develop, test, and deploy using the 3 Musketeers.

Prerequisites

• Docker
• Compose
• Make
• Cloudflare account

Development

# 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://localhost:8080/
# \<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://localhost:8080/
# \<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

Deployment

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).

0. Cloudflare account ID and API token

To interact with Cloudflare Pages with Wrangler CLI, Cloudflare account ID and API token are required.

1. Account ID: Find account and zone IDs
2. API token
   1. Create API token
   2. Use Edit Cloudflare Workers template
   3. Permissions:
      • Account - Cloudflare Pages - Edit
   4. Set a TIL
3. These values will be used in section 1. Envfile
4. Do not forget to delete the API token once it is not longer used

1. Envfile

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

2. Create

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

3. Deploy

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.

4. Delete

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

CI/CD

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

Visual elements

• 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
• 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
  • Mermaid is used to generate diagrams
  • All diagrams are in the directory diagrams

Contributing

CONTRIBUTING.md

Thanks goes to contributors.

References

• Docker
• Compose
• Make
• VitePress
• Cloudflare Pages
• GitHub Actions
• Vectornator
• Procreate
• favicon.io
• Mermaid
• Preparing a perfect image for the og:image tag

License

MIT