Skip to content

flemay/3musketeers

Repository files navigation

3 Musketeers

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

Build Status Netlify Status License

Table of Contents

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

Animated 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

Hello, World!

Create the following 2 files:

# docker-compose.yml
version: '3.8'
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 website built with VitePress. This section explains how to develop, test, and deploy using the 3 Musketeers.

Prerequisites

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 Netlify. This section shows how to create site, deploy, and delete using Netlify CLI. This is handy for previewing new changes.

Create a new site

This section creates a new empty Netlify site. Ensure the .env file contains the access token.

# All the following commands will be run inside a container
make shell

# Disable telemetry (optional)
yarn run netlify --telemetry-disable

# Create new Netlify blank site
yarn run netlify sites:create --disable-linking
# Answer the questions regarding the team and site name
# Site name can be something like 3musketeers-preview-{random 5 digit numbers}
Site Created

Admin URL: https://app.netlify.com/sites/site-name
URL:       https://site-name.netlify.app
Site ID:   site-id

# You can always get back that information
yarn run netlify sites:list

# Copy the ID to .env

# Exit the container
exit

Deploy

This section deploys the website to an existing netlify site. Ensure the .env file contains the right site ID and access token.

# Build the website
make build
# Deploy to netlify
make deploy
# Test the website
curl https://site-name.netlify.app
# Clean up directory
make prune

Delete

This section deletes a netlify site. Ensure the .env file contains the right site ID and access token.

# All the following commands will be run inside a container
make shell
# Disable telemetry (optional)
yarn run netlify --telemetry-disable
# Delete the site (optional)
yarn run netlify sites:delete
# Exit the container
exit

CI/CD

GitHub Actions is used to test PRs and deploy changes made to main branch to Netlify.

  • A dedicated Netlify personal access token has been created for Github Actions
  • Environment variables required for deploying to Netlify are set as secrets for GitHub Actions
  • The GitHub Actions workflows follow the 3 Musketeers pattern so it is a good real life example

Visual elements

  • 3 Musketeers logo
  • 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
  • README badges

Contributing

CONTRIBUTING.md

Thanks goes to contributors.

References

Stargazers over time

Stargazers over time

License

MIT