3 Musketeers

<div align="center"> <img src="src/assets/logo/hero-v2.svg" width="300">

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

</div> <details> <summary>Table of Contents</summary> <!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

• Overview
• 3 Musketeers website
  • Prerequisites
  • Development
  • Deployment
    • 0. Cloudflare account ID and API token
    • 1. Envfile
    • 2. Create
    • 3. Deploy
    • 4. Delete
  • CI/CD
  • Visual elements
• Contributing
• License

<!-- END doctoc generated TOC please keep comment here to allow auto update --> </details>

Overview

<!-- Part of src/content/docs/about/what-is-3musketeers.md -->

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.

[!NOTE] To learn more, please visit the official website.

3 Musketeers website

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

Prerequisites

• Docker
• Compose
• Make
• Cloudflare account

Development

# Create a .env file
make envfile ENVFILE=env.example
# Install dependencies
make deps copyDepsToHost

# Format and check
make fmt check

# Start Astro server for local development
make dev
# Wait till the message 'dev-1  | 20:13:41 watching for file changes...' appears
# Access the website in your browser at http://127.0.0.1:4321/
# \<ctrl-c\> to stop

# Build static site
make build

# Serve static site for local development
make previewDev
# Access the website in your browser at http://127.0.0.1:4321/
# \<ctrl-c\> to stop

# Serve static website in the background
make preview

# Test static website
make testPreview

# Clean
make clean

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.

[!NOTE] This section requires the static site to be have been generated with make build

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. Update the Token name
   4. Permissions:
      1. Account - Cloudflare Pages - Edit
      2. Remove other permissions
   5. Include your account
   6. Set a short-lived TTL
   7. Click Continue to summary
3. These values will be used in the following section 1. Envfile

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=random-project-name
ENV_SECRET_CLOUDFLARE_ACCOUNT_ID=id-from-previous-section
ENV_SECRET_CLOUDFLARE_API_TOKEN=token-from-previous-section

Verify:

make shell
# Check the env vars are correctly set
env | grep ENV_
# List current projects on CloudFlare
deno task deploy:list
exit

2. Create

This section creates a new Pages project. This step is only needed if ENV_CLOUDFLARE_PROJECT_NAME wasn't listed in step 1. Envfile.

make shell
# Create a new project
deno task deploy:create
# The new project and its domain should be listed
deno task deploy:list
# Project is empty which should not be hosted
curl -I https://${ENV_CLOUDFLARE_PROJECT_NAME}.pages.dev
#HTTP/2 522
#...
# Exit the container
exit

3. Deploy

This section deploys the website to an existing Cloudflare Pages project.

make shell
# Deploy the files to the project
deno task deploy
# Project is no longer empty!
curl -I https://${ENV_CLOUDFLARE_PROJECT_NAME}.pages.dev
#HTTP/2 200
#...
# Exit the container
exit

Note: make deploy can also be used.

4. Delete

This section shows how to delete a Cloudflare Pages project.

make shell
deno task deploy:delete
#? Are you sure you want to delete "<ENV_CLOUDFLARE_PROJECT_NAME>"? This action cannot be undone. › y
# Check the project is no longer listed
deno task deploy:list
exit

[!IMPORTANT] The CloudFlare token created in section 0. Cloudflare account ID and API token can be deleted

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 ./src/assets/logo/
• Favicon
  • Source image is an exported png format of the logo
  • Use the website favicon.io
  • The generated content is in ./public/favicon_io
  • Instructions to copy HTML <link> tags into the <head> was set in ./astro.config.mjs
• 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)
  • The social image is also set in the general settings of the repository
  • Astro Startlight sets all of the <meta> tags in the <head> section
• Diagrams
  • Mermaid is used to generate diagrams
  • All diagrams are in the directory diagrams
• The demo was generated by charmbracelet/vhs

Contributing

CONTRIBUTING.md

Thanks goes to contributors.

License

MIT