Alitrum

Purpose

This page covers additional information and thoughts on the Alitrum.com project, i.e. this site.

The purpose of the site was to help document the items I’m working on, blog the experience and to serve as a sort of portfolio if/when I explore additional employment opportunities.

It’s an interesting mix in target audience as it’s primarily for myself. Usage of “I”, “Me” and other first-person pronouns when authoring technical documentation outside of a work environment is… interesting to say the least.

Static Site Generator

The site was built using the Hugo static site generator and utilizes the Hugo Relearn Theme. Hexo was another contender but didn’t quite make the cut for various reasons.

Deployment is facilitated via the standard GitHub > Azure deployment process. The site initially lived in GitLab pages before it was moved to Azure for the following reasons:

GitLab deployment was a proof of concept to see how their Pages process works.
I was breaking my own standard around the KISS principle.
- Centralized hosting and management - almost all things cloud are in Azure
- A brief exploration into deploying to Azure from GitLab would require a larger time investment then point #1 called for.

All of the creation, deployment, etc. was completed following the standard documentation available for both Hugo and the Relearn theme. There are some items worth calling out from the experience.

Explore Themes Early

File structures can differ from theme to theme and transitioning to a new theme can be incredibly tedious. I was lucky enough that I had only invested and handful of hours in content creation before realizing I was spending too much time fighting with my initial choice.

Git Submodules

Submodules are pretty slick. This was a new concept when deploying Hugo - something just never encountered before. There were some initial growing pains as thought processes had to shift, but afterwards, they’re a pretty neat management mechanism.

Azure Hosting

The Site is hosted on Azure under a simple Static Web App and is deployed via their GitHub integration. The default documentation is simple enough to follow and will result in a working site (assuming the site works locally when running hugo server -D).

HTTP Headers

My deployment got an “A” grade on the Qualys SSL analyzer, however, the http headers need to be addressed.

You can configure Static Web Apps via the staticwebapp.config.json file. Simply create the file in the root of the hugo site and it will be included in the GitHub Action workflow by default. If customizations around site deployment are made then add a step to the steps: section of the deployment script to copy the staticwebapp.config.json file to the public folder. e.g.

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
          lfs: false
      - name: Copy staticwebapp.config.json
        run: cp staticwebapp.config.json ...<some_path>/public/
...

My static.webapp.config.json includes the following:

{
    "globalHeaders": {
      "Access-Control-Allow-Origin": "https://alitrum.com",
      "Access-Control-Allow-Methods": "POST, GET, OPTIONS",
      "Content-Security-Policy": "script-src 'self'",
      "X-Frame-Options": "SAMEORIGIN",
      "Permissions-Policy": "geolocation=(), microphone=(), camera=(), fullscreen=(), payment=(), usb=()"
    }
  }

Detailed information on various header options and values can be found on Mozilla’s developer site.

Domain Redirects

“To WWW or not to WWW, that is the question”

… and it’s a pretty important question to! Unfortunately, the devil is in the details. I prefer the www format since ANAME, ALIAS and CNAME flattening isn’t widely available. However, others will want to consider the following:

Routing the apex root domain to a hostname via ANAME/ALIAS records or CNAME Flattening
- Basically, setting the top level alitrum.com (no www) to a CNAME destination can/will result in all sorts of issues at the DNS level for third party integrations and services UNLESS your DNS provider supports these unique records.
- My DNS provider does, however, I went ahead as if they don’t.
where will the www/non-www redirect occur? Which system is the authority telling visitors, “Hey, you shouldn’t go that way - go over here instead.”
- Many CDN providers offer the ability to redirect at the edge, before traffic even hits a server you control. Cloudflare is both a DNS and a CDN provider and makes this process incredibly easy.
- Other CDN services like Azure Front Door can perform rewrites (or redirects) at the edge.
- The hosting service may have a mechanism to handle the rewrite. e.g. cPanel which is the backend for most WordPress hosting services.
- Self-hosted sites would require url rewrite rules in the web server. e.g. IIS, Nginx, Apache, Caddy, etc. configured to do the rewrite.

For this setup:

Traffic to the apex domain is proxied via Cloudflare (essentially as a CDN service) with a dummy A record pointing to 192.0.2.1
- This allows Cloudflare to control the traffic
- Live environments will have a live IP, and that should be OK in most setups as the page rule is only handling https:// requests
A page rule was created to redirect https://alitrum.com/* to https://www.alitrum.com/$1
The www domain was set as the default in the Azure portal
The www CNAME record is also proxied in Cloudflare
- Any ERR_TOO_MANY_REDIRECTS is down to Azure forcing HTTPS and introducing a loop
  - These are probably solutions for Azure resources with strict HTTPS behind a reverse proxy
  - Set the Encryption Mode in Cloudflare appropriately
  - OR disable any “HTTPS only” toggles
    - Verify access via the unique Azure provided FQDN is still https//