Hugo-site implementeren in AWS S3

Wanneer de site gegenereerd is met hugo is het tijd om deze te implementeren op een hostingplatform. Hieronder staat hoe je deze kunt pushen naar AWS S3 en laten serveren met AWS CloudFront CDN.

Voorbereiding site

Ik zal hier niet beschrijven hoe je een Hugo siteproject kunt aanmaken of artikelen of blogposts kunt toevoegen. Aangenomen wordt dat je dit al hebt gedaan.

Als dit niet het geval is, hier is een Hugo quickstart

Implementatieopties

Er zijn verschillende opties beschikbaar om een met Hugo gegenereerde site te implementeren en te hosten (https://gohugo.io/hosting-and-deployment/). Ik persoonlijk vind

• Hoe hugo site kan worden gehost op github
• AWS Amplify voor het bouwen en implementeren.
• en het implementeren naar s3 met hugo deploy opdracht en het laten serveren met AWS CloudDront CDN en AWS Route53 en AWS Lambda.

Hieronder beschrijf ik precies deze - laatste - methode.

1. Maak s3 bitbucket met relaxed permissions

ga naar: https://console.aws.amazon.com/s3

1. maak een bucket aan met een naam zoals site naam, bijvoorbeeld: “microsoft.com”

2. klik op de bucket => eigenschappen, verder beneden => statische website hosting

3. klik op bewerken, klik dan - inschakelen, en “host een statische website”

4. plaats daar ook in index: index.html en in fout: 404.html
5. klik op opslaan, onthoud “bucket website endpoint”, het ziet er ongeveer zo uit: http://microsoft.com.s3-website-ap-southeast-2.amazonaws.com
6. ga naar bucket permissions, zie de afbeeldingen hieronder. publieke toegang mag niet worden geblokkeerd.

7. bucket beleid (vervang microsoft.com met je domeinnaam):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "PublicReadGetObject",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::microsoft.com/*"
        }
    ]
}

2. Maak certificaat

ga naar AWS certificate manager https://console.aws.amazon.com/acm kies de juiste regio.

1. klik op aanvragen
2. publiek certificaat
3. domeinnamen: neem twee zoals: “microsoft.com” en “www.microsoft.com”
4. je kunt vragen om meer subdomeinen zoals “blog.microsoft.com”, “xmpp.microsoft.com” enz.
5. voer de DNS validatie uit. Het is veel makkelijker om dit via de Route53 console te doen/pushen als je registratie is bij AWS.

3. Implementeer Lamnda functie naar Lambda@Edge

De Lambda@Edge functie zal de urls van de Hugo QuickStart projectmap herstellen naar een standaardobject, index.html. Zo wordt Cloudfront de URI ‘/posts/my-post/’ met inhoud ‘/posts/my-post/index.html’ teruggeven met 200 in plaats van 404.

Flavor Cafe (Scotch) Lambda@Edge Code

// Hugo op Cloudfront, Lambda@Edge functie 
// Flavor Cafe (Scotch)
// @starpebble op github
//
// Twee herschrijfregels voor hugo subdirectory URI's.
// Voorbeeld:
//   1. herschrijf URI /posts/ naar /posts/index.html
//   2. herschrijf URI /posts naar /posts/index.html
//
// Voeg zoveel bestandsextensies toe als je wilt voor regel 2.
// URI's die eindigen op een bekende bestandsextensie worden niet herschreven door regel 2.

'use strict';

// @starpebble op github
// hugo flavor cafe (scotch)

const DEFAULT_OBJECT = 'index.html';

exports.handler = (event, context, callback) => {
  const cfrequest = event.Records[0].cf.request;
  if (cfrequest.uri.length > 0 && cfrequest.uri.charAt(cfrequest.uri.length - 1) === '/') {
    // bijvoorbeeld /posts/ naar /posts/index.html
    cfrequest.uri += DEFAULT_OBJECT;
  }
  else if (!cfrequest.uri.match(/.(css|md|gif|ico|jpg|jpeg|js|png|txt|svg|woff|ttf|map|json|html)$/)) {
    // bijvoorbeeld /posts naar /posts/index.html
    cfrequest.uri += `/${DEFAULT_OBJECT}`;
  }
  callback(null, cfrequest);
  return true;
}; 

4. Maak AWS CloudFront CDN aan

ga naar https://console.aws.amazon.com/cloudfront

1. Maak distributie aan
2. maak oorsprong aan die wijst naar je s3 bucket

3. Certificaat voor je site
4. wanneer het je vraagt om te converteren naar statische website - stem toe
5. maak gedrag aan dat wijst naar je oorsprong, en omleiding van Http naar Https

6. onderin gedrag/functieassociaties - in Oorsprongaanvraag - selecteer je Lambda functie

7. opslaan
8. Ga naar de Algemene tab van je distributie en kopieer de domeinnaam van je distributie. Het moet er ongeveer zo uitzien: asdfasdfasdf.cloudfront.net

5. Stel AWS Route53 DNS in op je CloudFrount

ga naar https://console.aws.amazon.com/route53/v2/hostedzones

1. maak of klik op je site’s hosted zone. Het moet er ongeveer zo uitzien: bijvoorbeeld: “microsoft.com”
2. maak een lege “A” record aan die wijst naar je CloudFront distributie (domeinnaam van distributie)
3. maak een “A” “www” record aan die wijst als alias naar je eerste “A” record

6. Installeer aws cli

1. Installeer aws client commandline tools https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html
2. configureer aws cli verbinding
   1. controleer het bestand ~/.aws/credentials, het moet er ongeveer zo uitzien

[default]
aws_access_key_id = .......
aws_secret_access_key = .......

3. test de verbinding, typ iets als hieronder om je s3 bucket te zien

aws s3 ls

7. Werk je config.toml bij

1. open je hugo.toml of config.toml in je hugo project
2. voeg aan het einde toe (vervang opnieuw microsoft.com met je eigen):

[[deployment.targets]]
# Een willekeurige naam voor dit doel.
name = "lfs3"

# S3; zie https://gocloud.dev/howto/blob/#s3
# Voor S3-compatibele eindpunten, zie https://gocloud.dev/howto/blob/#s3-compatible
URL = "s3://microsoft.com?region=ap-southeast-2"

# Als je een CloudFront CDN gebruikt, zal deploy de cache onnodig ongeldig maken.
cloudFrontDistributionID = 	""

Als je je configuraties in config.yml hebt, moet het er ongeveer zo uitzien

deployment:
  targets:
    name: "lfs3"
    URL: "s3://microsoft.com?region=ap-southeast-2"
    cloudFrontDistributionID:	"E123123123"

3. sla dit bestand op
4. compileer je site

hugo

5. implementeer het met hugo deploy command

hugo deploy

6. open je site url in de browser om te zien of dit allemaal werkt

Nuttige links

• Google Form indienen op Hugo website
• Structuurdata markup toevoegen aan de Hugo website
• Hugo Cheat Sheet
• Gitea Actions gebruiken om Hugo website te implementeren op AWS S3
• Hugo quickstart: https://gohugo.io/getting-started/quick-start/
• Grote lijst van Hugo thema voorbeelden: https://themes.gohugo.io/
• Hugo hosting en implementatie: https://gohugo.io/hosting-and-deployment/
• Afbeeldingbehandeling in Mainroad Hugo Thema: Mainroad thema afbeeldingsbehandeling
• AWS Command Line Interface (AWS CLI) installeren: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html
• Populairste thema’s voor Hugo
• Hoe je miniaturen afbeeldingen opslaat in de pagina bundelmap voor Hugo sites met Mainroad thema

Ik hoop dat dit kleine howto document je helpt. Veel plezier!