Hello World!

L’ Hello World è il primo programma che un developer scrive per verificare che il suo setup funzioni correttamente.

Come “Hello World” par il mio blog ho voluto mostrare come ho creato questo sito, partendo dallo Static Site Generator di mia scelta - Hugo - e concludendo mostrando come ho hostato il tutto su Cloudflare utilizzando Pages.

Disclaimer

#

Potrebbe sembrare abbastanza paradossale che un appassionato di open source, privacy e sovranità dei propri dati personali si metta ad hostare il proprio sito su Cloudflare¹ e farci tutorial a riguardo.

Vorrei precisare che questo è un setup provvisorio, adatto anche a chi non ha la possibilita di self-hostare un sito, sia per motivi di sicurezza che per motivi di CGNAT² (dannato IPv4).

Per chi fosse interessato, è in programma un articolo su come fare il forwarding delle porte anche attraverso il CGNAT, però per ora continuiamo ad usare quel maledetto di Cloudflare.

Creare un sito con Hugo

#

Per gestire tutti i contenuti su questo sito uso Hugo, un generatore di siti statici che mi permette di scrivere pagine ed articoli in un semplice linguaggio di markup, come Markdown. Hugo poi prenderà i contenuti ed un tema e li combinerà, producendo HTML, CSS e JavaScript statici.

Per cominciare, bisogna installare Hugo e creare un nuovo progetto:

hugo new site <site-name>
cd <site-name>
git init

Se vuoi visualizzare il tuo sito in un server di sviluppo:

hugo server

Adesso all’URL http://localhost:1313/ dovresti vedere una pagina 404: Page Not Found. Per sistemare questo problema dobbiamo installare un tema.

Scegliere un tema

#

Per avere un’idea di quali temi possiamo installare possiamo andare nella sezione “Themes” del sito di Hugo. Ovviamente nulla ci vieta di crearci il nostro tema da zero, in rete ci sono diversi tutorial a riguardo.

Per una questione di semplicità, per questo tutorial andrò a scegliere il tema PaperMod.

Per aggiungere un tema bisogna prima scaricarlo come sottomodulo Git nella directory themes/:

git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/papermod

Poi bisogna specificare il tema che Hugo deve usare nel file di configurazione:

echo "theme = 'papermod'" >> hugo.toml

Se riavviamo il dev server dovremmo vedere una pagina simile a questa:

Il nostro sito comincia finalmente ad avere un po’ di colore, ma è ancora troppo spoglio e generico per i miei gusti.

Personalizzare il sito

#

Per rendere il sito meno generico bisogna modificare i file di configurazione. Ad esempio all’interno del file hugo.toml possiamo modificare le prime variabili:

baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'
theme = 'papermod'

Per configurare a fondo il sito è necessario consultare la documentazione del tema scelto, ad esempio questa è la documentazione per il tema PaperMod.

Purtroppo non c’è una documentazione comune per tutti i temi, quindi bisogna prendersi un po’ di tempo e leggersi la documentazione del proprio tema.

Aggiungere degli articoli

#

Ora il nostro blog ha un bell’aspetto, ma al momento è un po’ vuoto. Possiamo risolvere creando il nostro primo articolo:

hugo new content posts/<article-name>.md

Con questo comando Hugo copierà il file archetypes/default.md nel percorso contents/posts/, lo rinominerà e scambierà le variabili contenute al suo interno:

+++
title = 'Test Article'
date = 2024-04-22T00:00:00+02:00
draft = true
+++

Vorrei far notare la variabile draft = true nel preambolo del nostro articolo: quando questa è impostata a true Hugo nasconderà l’articolo in fase di compilazione, in modo che si possa compilare tutto il sito senza che ci si debba preoccupare di visualizzare degli articoli incompleti.

Possiamo comunque mostrare le bozze quando eseguiamo il dev server passando l’argomento --buildDrafts al comando hugo server.

Ora possiamo iniziare a scrivere il nostro post utilizzando il linguaggio Markdown:

Una volta finito di scrivere i nostri articoli possiamo compilare il nostro blog utilizzando il comando:

hugo

I risultati della compilazione si possono trovare nella directory public/.

Pubblicare il sito con Cloudflare Pages

#

Ora che abbiamo un sito compilato staticamente possiamo pubblicarlo su una piattaforma come Cloudflare Pages.

Esistono tante piattaforme che permettono di pubblicare pagine statiche, come GitHub Pages o Vercel. Ho scelto Cloudflare Pages solo per comodità, dato che in passato avevo registrato presso Cloudflare il dominio “nicolabelluti.me” per utilizzare Cloudflare Tunnel, sul quale arriverà presto un articolo³.

Per creare un sito con Cloudflare Pages, bisogna recarsi nella Dashboard di Cloudflare e navigare su Workers & Pages cliccare su Pages.

Creare un nuovo progetto, dargli un nome e salvarlo senza caricare alcun file.

Ora se torniamo indietro alla voce Workers & Pages della barra laterare, dovreste vedere il nuovo progetto.

In caso voleste inserire il vostro dominio, potete farlo nella sezione Custom domains del progetto. Assicuratevi di inserire sia il dominio base che il sottodominio www..

Ora siamo pronti per pubblicare il sito! Per farlo basta recarsi nella sezione Deployments e cliccare su Upload assets.

Pubblicare il sito usando Wrangler

#

Fare il login sulla Dashboard di Cloudflare e aggiornare il sito manualmente ogni volta che dobbiamo aggiornare qualcosa può essere un po’… sub-optimale.

Per questo motivo possiamo usare uno strumento molto comodo per caricare in automatico tutti i nostri file dalla linea di comando: il suo nome è Wrangler CLI.

Possiamo installarlo tramite npm con:

npm install -g wrangler

Per utilizzarlo ci servirà una chiave API, in modo che Wrangler CLI possa aggiornare il sito per nostro conto.

Per creare una chiave bisogna andare nella sezione “My Profile” della Dashboard di Cloudflare per poi recarsi in API Tokens > Create Token e poi Create Custom Token in fondo alla pagina.

Il token deve avere i seguenti parametri:

• Name: Chiamalo come vuoi, io lo chiamerò “blog”
• Permissions: Account > Cloudflare Pages > Edit
• Account Resources: Include > La mail del tuo account
• Client IP Address Filtering: opzionale
• TTL: opzionale, ma consiglio caldamente di impostarlo

Clicca su Continue to summary > Create Token e salva il token API.

Infine, bisogna copiare l’account ID tornando nella Dashboard di Cloudflare e aprendo il proprio dominio. L’account ID si può trovare nella barra laterale destra, sotto la sezione “API”.

Ora, con la chiave API e l’account ID possiamo eseguire Wrangler con:

hugo  # Bisogna prima compilare il sito

export CLOUDFLARE_ACCOUNT_ID=<Il tuo account ID>
export CLOUDFLARE_API_TOKEN=<Il token API>
npx wrangler pages deploy 'public/' --project-name=<Il nome del progetto>