Repository files navigation

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

The 3 Musketeers is a pattern for developing software in a repeatable andconsistent manner. It leverages Make as an orchestration tool to test, build,run, and deploy applications using Docker and Docker Compose. The Make andDocker/Compose commands for each application are maintained as part of theapplication’s source code and are invoked in the same way whether run locally oron a CI/CD server.

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

• Docker
• Compose
• Make
• Cloudflare account

# Create a .env filemake envfile ENVFILE=env.example# Install dependenciesmake deps copyDepsToHost# Format and checkmake fmt check# Start Astro server for local developmentmake 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 sitemake build# Serve static site for local developmentmake previewDev# Access the website in your browser at http://127.0.0.1:4321/# \<ctrl-c\> to stop# Serve static website in the backgroundmake preview# Test static websitemake testPreview# Cleanmake clean

The 3 Musketeers website is deployed toCloudflare Pages.This section shows how to create, deploy, and delete a Pages project usingWrangler CLI. This is handy for previewing newchanges.

Given build, test and deployment are going to be done with GitHub Actions, thissection follows theDirect Upload andRun Wrangler in CI/CD directives.

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

1. Account ID:Find account and zone IDs
2. API token
   1. Create API token
   2. UseEdit Cloudflare Workers template
   3. Update theToken name
   4. Permissions:
      1. Account - Cloudflare Pages - Edit
      2. Remove other permissions
   5. Include your account
   6. Set a short-lived TTL
   7. ClickContinue to summary
3. These values will be used in the following section1. Envfile

The following sections use the values from the file.env. Create file.env(based onenv.template) with the correct values.

Example:

# .envENV_CLOUDFLARE_BRANCH_NAME=mainENV_CLOUDFLARE_PROJECT_NAME=random-project-nameENV_SECRET_CLOUDFLARE_ACCOUNT_ID=id-from-previous-sectionENV_SECRET_CLOUDFLARE_API_TOKEN=token-from-previous-section

Verify:

make shell# Check the env vars are correctly setenv| grep ENV_# List current projects on CloudFlaredeno task deploy:listexit

This section creates a new Pages project. This step is only needed ifENV_CLOUDFLARE_PROJECT_NAME wasn't listed in step1. Envfile.

make shell# Create a new projectdeno task deploy:create# The new project and its domain should be listeddeno task deploy:list# Project is empty which should not be hostedcurl -I https://${ENV_CLOUDFLARE_PROJECT_NAME}.pages.dev#HTTP/2 522#...# Exit the containerexit

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

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

Note:make deploy can also be used.

This section shows how to delete a Cloudflare Pages project.

make shelldeno 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 listeddeno task deploy:listexit

GitHub Actions is used to test PRs and deploy changes madetomain 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 asvariables andsecrets in GitHub Actions
• The GitHub Actions workflows follow the 3 Musketeers pattern

• 3 Musketeers logo
  • Created by me withProcreate and Vectornator
    • Neat tools used areoffset path andmask 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 websitefavicon.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 toartegence article, the ideal image thatworks 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 directorydiagrams
• Thedemo was generated bycharmbracelet/vhs

CONTRIBUTING.md

Thanks goes tocontributors.

MIT