statamic-deploy.md

Deployment

Creating and configuring a new site / environment occurs occasionally. Often, to update the underlying server software.

This site has been built with:

• Statamic v3 is a flat file CMS
• Statamic is a Laravel v9 package
• CSS via Tailwind v3
• Javascript via AlpineJS v3
• Composer is the PHP package manager
• NPM is the JS package manager

Useful tools

• Google's Dig or a DNS Checker to understand the public DNS values
• HTTP Status to check status codes & redirect chains.
• Laravel Shift to upgrade Laravel or Tailwind across major versions

Server

• Laravel Forge is used to provision and manage servers on Digitalocean (servers = 'Droplets')
• create a server (Forge)
• "App server" with Ubuntu 20.04 LTS (Focal)
• Name appropriately: ie example-prod-2 or example-dev-3
• PHP 8.1

Site

• create a site (Forge)
• Root domain: set with the (eventual) domain it'll be served on.
  • 'Eventual', as sometimes a temp domain if necessary for minimising downtime
  • In this situation, add a temp domain as an alias on a domain you control (ie: prod-temp.example.com)
• Project type: General PHP / Laravel
• Web Directory: /public
• PHP version: 8.1

Add repo

• App > Git Repository:
  • Repository: wesort/example-web
  • Branch: main
  • Install composer dependencies: yes / checked

SSH into the server (Secure Shell, Terminal, etc)

• username: forge
• hostname: ###.##.##.### (IP address of newly created server)
• port: 22
• ssh: select identity
  • If not already configured, Digitalocean > Settings > Security > Add SSH Key
  • SSH key content: public key
  • Name: eg: wesort-type-of-key-v1
• check presense of site: ll and ensure repo has finished cloing (Forge)
• create .env from template:
  • prod: cp docs/prod.env .env
  • dev: cp docs/dev.env .env
• ensure .env contents are correct (update APP_ENV, APP_URL, etc.)
• install PHP packages from composer.json: composer install`
• install JS package from package.json: npm install
• run build script:
  • production: npm run prod
  • active development: npm run watch (runs each times files change)
  • static development: npm run dev

SSL certificate

• Check the DNS is ready: letsdebug.net
• If ok, issue the SSL cert: site > SSL > Let's Encrypt (use defaults)

Nginx configuration

• replace the location / block with to allow for static caching

location / {
    try_files /static${uri}_${args}.html $uri /index.php?$args;
}

• append after location ~ /\.(?!well-known).* { ... }

# Enable gzip compression
gzip on;
gzip_min_length  1100;
gzip_buffers  4 32k;
gzip_types  text/plain application/javascript application/x-javascript text/javascript text/xml text/css;
gzip_vary on;

# Expire headers on static assets
# Media: images, icons, video, audio, HTC
location ~* \.(?:jpg|jpeg|gif|png|ico|cur|gz|svg|svgz|mp4|ogg|ogv|webm|htc|eot|ttf|woff|woff2)$ {
    try_files $uri /index.php?$query_string;
    expires 1y;
    access_log off;
    add_header Cache-Control "public";
}
# CSS and Javascript
location ~* \.(?:css|js)$ {
    try_files $uri /index.php?$query_string;
    expires 1y;
    access_log off;
    add_header Cache-Control "public";
}

Build Glide presets

• Glide is a library used by Statamic to generate versions of images
• This site has a variety of presets to optimise for srcset
• Presets are built when:
  • an asset is originally uploaded
  • by running php please assets:generate-presets in the root of the site.
• NB: depending on the number of assets and presets and server speed, this command can take 5 minutes to 5 hours to complete.

🧪 Test, test, test 🧪

• visit the front-end from a few devices
• login to the control panel example.com/cp
• check the console in Dev Tools
• run Lighthouse

Automated 'backup' with git

• autobackup.sh is a script to bring changes from production into the repo
• It adds, commits and pushes via a cronjob
• Instructions in the file.
• More active projects could run more frequently.