Added the "Hello World!" article

content/posts/2024/04/hello-world/index.it.md

@@ -0,0 +1,258 @@
++++
+title = "Hello World!"
+summary = "Come costruire il proprio blog usando Hugo e Cloudflare Pages"
+date = "2024-04-22"
+
+tags = ["Hugo", "Cloudflare", "Pages", "Wrangler"]
+categories = ["Tutorial"]
+
+draft = true
++++
+
+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](https://gohugo.io/) - e concludendo mostrando come ho hostato il tutto
+su Cloudflare utilizzando [Pages](https://pages.cloudflare.com/).
+
+### Disclaimer
+
+{{< alert icon="triangle-exclamation" cardColor="#e6d237" iconColor="#1d3557"
+textColor="#1d3557" >}}
+Cloudflare? [**Absolutely propriatery**](https://i.imgflip.com/6kaqvc.jpg)!
+{{< /alert >}}
+
+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[^1] e farci tutorial a riguardo.
+
+[^1]: [old.reddit.com - ELI5 why CloudFlare is depicted as evil, and what's
+    wrong with using their DNS
+    (1.1.1.1)](https://old.reddit.com/r/privacy/comments/d52kop/)
+
+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[^2] (*dannato IPv4*).
+
+[^2]: [en.wikipedia.org - Carrier-grade
+    NAT](https://en.wikipedia.org/wiki/Carrier-grade_NAT)
+
+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](https://gohugo.io/), 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](https://github.com/gohugoio/hugo/releases/latest) e creare un nuovo
+progetto:
+
+```shell
+hugo new site <site-name>
+cd <site-name>
+git init
+```
+
+Se vuoi visualizzare il tuo sito in un server di sviluppo:
+
+```shell
+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"](https://themes.gohugo.io/) 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](https://github.com/adityatelange/hugo-PaperMod/).
+
+Per aggiungere un tema bisogna prima scaricarlo come sottomodulo Git nella
+directory `themes/`:
+
+```shell
+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:
+
+```shell
+echo "theme = 'papermod'" >> hugo.toml
+```
+
+Se riavviamo il *dev server* dovremmo vedere una pagina simile a questa:
+
+![Homepage del blog con il tema PaperMod](images/01-papermod.jpg "La homepage
+del nostro blog col tema PaperMod")
+
+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:
+
+```toml
+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](https://adityatelange.github.io/hugo-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:
+
+```shell
+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:
+
+```toml
++++
+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](https://commonmark.org/):
+
+![Un articolo di prova](images/02-article.jpg "Ecco un articolo di prova")
+
+Una volta finito di scrivere i nostri articoli possiamo compilare il nostro
+blog utilizzando il comando:
+
+```shell
+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](https://pages.cloudflare.com/).
+
+Esistono tante piattaforme che permettono di pubblicare pagine statiche, come
+[GitHub Pages](https://pages.github.com/) o [Vercel](https://vercel.com/). Ho
+scelto Cloudflare Pages solo per comodità, dato che in passato avevo registrato
+presso Cloudflare il dominio "nicolabelluti.me" per utilizzare [Cloudflare
+Tunnel](https://www.cloudflare.com/products/tunnel/), sul quale arriverà presto
+un articolo[^3].
+
+[^3]: Si, so che Cloudflare Tunnel non è altro che un
+    [MITM](https://en.wikipedia.org/wiki/Man-in-the-middle_attack), arriverà
+    anche un articolo sul come sostituire Cloudflare Tunnel con una propria
+    VPN Wireguard.
+
+Per creare un sito con Cloudflare Pages, bisogna recarsi nella [Dashboard di
+Cloudflare](https://dash.cloudflare.com/) e navigare su `Workers & Pages`
+cliccare su `Pages`.
+
+Creare un nuovo progetto, dargli un nome e salvarlo senza caricare alcun file.
+
+![Qua bisogna inserire il nome del progetto](images/03-pages-creation.jpg "Qua
+bisogna inserire il nome del progetto")
+
+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`.
+
+![Il pulsante "Upload assets"](images/04-upload-assets.jpg "Il pulsante
+\"Upload assets\". Possiamo notare una scritta in piccolo sotto il bottone...")
+
+### 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:
+
+```shell
+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](https://dash.cloudflare.com/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*
+
+![Parametri del token API](images/05-api-token.jpg "Ecco tutti i parametri che
+dovete aver impostato")
+
+Clicca su `Continue to summary` > `Create Token` e salva il token API.
+
+{{< alert >}}
+**Salva il token in un posto sicuro, verrà mostrato solo questa volta**
+{{< /alert >}}
+
+Infine, bisogna copiare l'account ID tornando nella [Dashboard di
+Cloudflare](https://dash.cloudflare.com/) 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:
+
+```shell
+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>
+```

content/posts/2024/04/hello-world/index.md

@@ -0,0 +1,250 @@
++++
+title = "Hello World!"
+summary = "Building your first blog using Hugo and Cloudflare Pages"
+date = "2024-04-17"
+
+tags = ["Hugo", "Cloudflare", "Pages", "Wrangler"]
+categories = ["Tutorial"]
+
+draft = true
++++
+
+*Hello World* is the first program a developer writes to check if their setup
+is working properly.
+
+As a kind of "Hello World" for my blog, I wanted to show how I created this
+site, starting from the Static Site Generator I chose -
+[Hugo](https://gohugo.io/) - and ending with showing how I hosted everything on
+Cloudflare using [Pages](https://pages.cloudflare.com/).
+
+### Disclaimer
+
+{{< alert icon="triangle-exclamation" cardColor="#e6d237" iconColor="#1d3557"
+textColor="#1d3557" >}}
+Cloudflare? [**Absolutely proprietary**](https://i.imgflip.com/6kaqvc.jpg)!
+{{< /alert >}}
+
+It might seem quite paradoxical that an open-source enthusiast would host their
+site on Cloudflare[^1] and even make a tutorial about it.
+
+[^1]: [old.reddit.com - ELI5 why CloudFlare is depicted as evil, and what's
+    wrong with using their DNS
+    (1.1.1.1)](https://old.reddit.com/r/privacy/comments/d52kop/)
+
+I just want to make clear that this is a temporary setup, suitable even for
+those who can't self-host a website, for security reasons or the CGNAT[^2]
+(*damned IPv4*).
+
+[^2]: [en.wikipedia.org - Carrier-grade
+    NAT](https://en.wikipedia.org/wiki/Carrier-grade_NAT)
+
+For those interested, I'm making an article about how to forward the port
+through CGNAT, but for now let's continue using the damned Cloudflare.
+
+## Creating a site with Hugo
+
+To manage all the content on this site, I use [Hugo](https://gohugo.io/), a
+static site generator that allows me to write pages and articles in a simple
+markup language, like Markdown. Hugo will then take the content and a theme and
+combine them, producing static HTML, CSS and JavaScript.
+
+To get started, you need to [install
+Hugo](https://github.com/gohugoio/hugo/releases/latest) and create a new
+project:
+
+```shell
+hugo new site <site-name>
+cd <site-name>
+git init
+```
+
+If you want to view your site on a development server:
+
+```shell
+hugo server
+```
+
+Now at the URL <http://localhost:1313/>, you should see a *404: Page Not
+Found*. To fix this problem, we need to install a theme.
+
+### Choosing a theme
+
+To get an idea of which themes we can install, we can go to the [ "Themes"
+section](https://themes.gohugo.io/) of Hugo's website. We can create our own
+theme from scratch if we want, there are several tutorials online about that.
+
+For simplicity's sake, for this tutorial, I'll choose the [PaperMod
+theme](https://github.com/adityatelange/hugo-PaperMod/).
+
+To add a theme, you first need to download it as a Git submodule into the
+`themes/` directory:
+
+```shell
+git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/papermod
+```
+
+Then you need to specify the theme that Hugo should use in the configuration
+file:
+
+```shell
+echo "theme = 'papermod'" >> hugo.toml
+```
+
+If we restart the development server, we should see a page similar to this:
+
+![Blog homepage with the PaperMod theme](images/01-papermod.jpg "Our blog
+homepage with the PaperMod theme")
+
+Our site is finally starting to look a bit more colorful, but it's still too
+plain and generic for my taste.
+
+### Customizing the site
+
+To make the site less generic, you need to modify the configuration files. For
+example, we can change the first variables in `hugo.toml`:
+
+```toml
+baseURL = 'https://example.org/'
+languageCode = 'en-us'
+title = 'My New Hugo Site'
+theme = 'papermod'
+```
+
+To thoroughly configure the site, you need to consult the documentation for the
+chosen theme. [This is the documentation for the PaperMod
+theme](https://adityatelange.github.io/hugo-PaperMod/).
+
+Unfortunately, there is no common documentation for all themes, so you need to
+take some time and read through your theme's documentation.
+
+### Adding articles
+
+Now our blog looks nice, but at the moment, it's a bit empty. We can fix this
+by creating our first article:
+
+```shell
+hugo new content posts/<article-name>.md
+```
+
+With this command, Hugo will copy the `archetypes/default.md` file to the
+`contents/posts/` path, rename it, and substitute the variables:
+
+```toml
++++
+title = 'Article Name'
+date = 2024-04-22T00:00:00+02:00
+draft = true
++++
+```
+
+I would like to point out the `draft = true` variable in our article's
+preamble: when this is set to `true`, Hugo hides the article during
+compilation, so you can compile the entire site without worrying about
+displaying incomplete articles.
+
+However, you can still display drafts when running the dev server by passing
+the `--buildDrafts` argument to the `hugo server` command.
+
+Now you can start writing your post using the [Markdown
+language](https://commonmark.org/):
+
+![A test article](images/02-article.jpg "Here's a test article")
+
+Once we've finished writing our articles, we can compile our blog using the
+command:
+
+```shell
+hugo
+```
+
+The compiled output can be found in the `public/` directory.
+
+## Publishing the site with Cloudflare Pages
+
+Now that we have a statically compiled site, we can publish it on a platform
+like [Cloudflare Pages](https://pages.cloudflare.com/).
+
+There are many platforms that allow you to publish static pages, such as
+[GitHub Pages](https://pages.github.com/) or [Vercel](https://vercel.com/). I
+chose Cloudflare Pages simply for convenience, since I had previously
+registered the "nicolabelluti.me" domain with Cloudflare to use [Cloudflare
+Tunnel](https://www.cloudflare.com/products/tunnel/), which I'll discuss in a
+future article[^3].
+
+[^3]: Yes, I know that Cloudflare Tunnel is nothing more than a
+    [MITM](https://en.wikipedia.org/wiki/Man-in-the-middle_attack), and I'll
+    also discuss how to replace Cloudflare Tunnel with your own Wireguard VPN.
+
+To create a site with Cloudflare Pages, go to the [Cloudflare
+Dashboard](https://dash.cloudflare.com/) and navigate to `Workers & Pages`,
+then click `Pages`.
+
+Create a new project, give it a name, and save it without uploading any files.
+
+![This is where you enter the project name](images/03-pages-creation.jpg "This
+is where you enter the project name")
+
+If you go back to the `Workers & Pages` section in the sidebar, you should see
+the new project.
+
+If you want to add your own domain, you can do so in the `Custom domains`
+section of the project. Make sure to add both the base domain and the `www.`
+subdomain.
+
+Now we are ready to publish the site! To do this, go to the `Deployments`
+section and click `Upload assets`.
+
+![The "Upload assets" button](images/04-upload-assets.jpg "The \"Upload
+assets\" button. You can notice some small text under the button...")
+
+### Publishing the site using Wrangler
+
+Logging into the Cloudflare Dashboard and manually updating the site every time
+we need to change something can be a bit... sub-optimal.
+
+For this reason, we can use a handy tool to automatically upload all our files
+from the command line: it's called Wrangler CLI.
+
+We can install it via `npm` with:
+
+```shell
+npm install -g wrangler
+```
+
+To use it, we'll need an API key, so Wrangler CLI can update the site on our
+behalf.
+
+To create a key, go to the "[My Profile](https://dash.cloudflare.com/profile)"
+section of the Cloudflare Dashboard, then navigate to `API Tokens` > `Create
+Token`, and then `Create Custom Token` at the bottom of the page.
+
+The token should have the following parameters:
+
+* **Name**: Call it what you like; I'll call it "blog"
+* **Permissions**: `Account` > `Cloudflare Pages` > `Edit`
+* **Account Resources**: `Include` > *Your account's email*
+* **Client IP Address Filtering**: *optional*
+* **TTL**: *optional, but I **strongly** recommend setting it*
+
+![API Token Parameters](images/05-api-token.jpg "Here are all the parameters
+you should have set.")
+
+Click `Continue to summary` > `Create Token` and save the API token.
+
+{{< alert >}}
+**Save the token in a safe place, it will be shown only this once**
+{{< /alert >}}
+
+Finally, you need to copy the account ID by returning to the [Cloudflare
+Dashboard](https://dash.cloudflare.com/) and opening your domain. The account
+ID can be found on the right sidebar, under the "API" section.
+
+Now, with the API key and the account ID, we can run Wrangler with:
+
+```shell
+hugo  # You need to compile the site first
+
+export CLOUDFLARE_ACCOUNT_ID=<Your account ID>
+export CLOUDFLARE_API_TOKEN=<The API token>
+npx wrangler pages deploy 'public/' --project-name=<The project's name>
+```