Hugo è un popolare generatore di siti statici (SSG) open-source progettato per aiutare gli sviluppatori a costruire e gestire siti web in modo rapido ed efficiente. Può essere utilizzato per creare blog, portfolio e tutte le forme di siti personali che non richiedono dati dinamici.

Una volta creati i vostri siti con Hugo, vorrete sicuramente ospitarli online per poterli condividere con tutti coloro che devono accedervi. È qui che entra in gioco l’Hosting di Siti Statici di Kinsta!

Come funziona l’Hosting di Siti Statici di Kinsta

L’Hosting di Siti Statici di Kinsta è un servizio gratuito dedicato all’hosting di siti statici. Lo fa servendo file HTML, CSS e JavaScript precostituiti che non cambiano dinamicamente. Funziona collegando un repository ospitato su un provider Git (BitBucket, GitHub o GitLab) al vostro account Kinsta e distribuendo i file del vostro sito statico su internet.

L’Hosting di Siti Statici di Kinsta è in grado di creare automaticamente siti a partire da SSG costruiti su Node.js, mentre per altri come Hugo, scritto in linguaggio di programmazione Go (Golang), è necessario adottare un altro approccio.

Questo articolo spiega come ospitare gratuitamente il vostro sito Hugo su Kinsta con l’Hosting di Siti Statici di Kinsta!

Distribuire un sito Hugo sull’Hosting di Siti Statici di Kinsta

Ci sono tre modi per distribuire un sito Hugo sull’Hosting di Siti Statici di Kinsta:

  1. Costruendo il sito web utilizzando il metodo Continuous Integration/Continuous Deployment (CI/CD) e poi distribuirlo.
  2. Utilizzando la developer dependency hugo-bin.
  3. Servendo file statici costruiti localmente.

In questo articolo li analizzeremo tutti e tre.

Prerequisiti

Per seguire questo tutorial, è necessario avere:

  • Esperienza con Hugo e Git.
  • Un sito Hugo in esecuzione in locale.

Creare il sito con CircleCI e distribuirlo su Kinsta

Per il primo metodo, utilizziamo CircleCI come strumento CI/CD. Questo metodo prevede la creazione di un workflow CircleCI che esegue la build del sito Hugo in un nuovo branch chiamato deploy e poi configura Kinsta per distribuire i file statici da questo branch.

Vantaggi dell’uso di CI/CD

Con questo metodo potrete evitare di costruire localmente il sito prima di inviarlo al repository Git. Normalmente, Kinsta gestisce il processo di creazione del sito per gli SSG basati su Node.js, ma per altri SSG come Hugo, l’utilizzo di un workflow può aiutare a gestire automaticamente il processo di creazione del sito.

Inoltre, potete aggiungere altri job al vostro file di configurazione CI/CD, ad esempio per eseguire il linting e per testare il codice. In questo modo garantirete anche che il deployment venga aggiornato solo se la pipeline CI/CD viene completata con successo.

Passaggio 1: Creare il file di configurazione

Iniziamo creando una cartella .circleci nella directory principale del progetto Hugo. All’interno di questa cartella, creiamo un file config.yml per definire la configurazione del workflow.

Passaggio 2: Inserire il codice in un repository Git

Creiamo un repository Git utilizzando il nostro provider Git preferito e inviamo il codice al repository.

Passaggio 3: Creare un orphan branch

Successivamente, creiamo un orphan branch vuoto chiamato deploy, dove verranno inseriti i file statici per il deployment. Eseguiamo i seguenti comandi nel terminale del progetto:

git switch --orphan deploy
git commit --allow-empty -m "Initial commit on deploy branch"
git push -u origin deploy

Non aggiungete alcun file a questo branch; verrà popolato automaticamente dal workflow CircleCI con il contenuto della cartella public generata da Hugo.

Passaggio 4: Creare un account CircleCI

Visitate il sito web di CircleCI e create un account se non ne avete già uno. Potete registrarvi utilizzando il vostro provider Git preferito, il che renderà più facile l’accesso ai repository senza ulteriori configurazioni.

Passaggio 5: Configurare il repository

Dopo aver effettuato il login, accediamo alla dashboard CircleCI, clicchiamo su Project nella barra laterale di sinistra e selezioniamo il repository che vogliamo configurare. CircleCI rileverà automaticamente il file di configurazione.

Configurare un repository con CircleCI
Configurare un repository con CircleCI.

Clicchiamo sul pulsante Set Up Project per concedere a CircleCI l’accesso alla nostra base di codice ed eseguire i workflow in caso di modifiche al codice.

Passaggio 6: Definire la configurazione di CircleCI

Ora che abbiamo creato un file di configurazione di CircleCI, costruiamone il contenuto. Assicuriamoci di essere nel nostro branch predefinito (non nel branch deploy ) e iniziamo a definire la versione di CircleCI, che al momento è la 2.1:

version: 2.1

Passaggio 7: Definire gli executor

Poiché si tratta di un progetto Hugo, dovremo definire un executor per eseguire i job. Definiamo l’hugo-executor qui, in modo da non doverlo definire per ogni job. Questo executor utilizza un’immagine Docker (cibuilds/hugo:latest) per creare un ambiente coerente per la build del sito Hugo:

executors:
  hugo-executor:
    docker:
      - image: cibuilds/hugo:latest

Passaggio 8: Definire i job

Definiamo quindi due job: build e push build. Questi job specificano i passaggi da eseguire in ciascuno di essi:

jobs:
  build:
    executor: hugo-executor

  push build:
    executor: hugo-executor

Build Job:

Questo job è responsabile della build del sito Hugo e della memorizzazione temporanea dei file statici generati nell’area di lavoro, in modo che possano essere accessibili per un successivo utilizzo nel job push build.

build:
  executor: hugo-executor
  steps:
    - checkout

    - run:
        name: Update theme
        command: git submodule update --init --recursive

    - run:
        name: Build Hugo site
        command: hugo --destination=workspace/public

    # Persist the 'build' directory to the workspace
    - persist_to_workspace:
        root: workspace
        paths:
          - public

Il job di cui sopra specifica che utilizza l’executor hugo-executor definito in precedenza. Quindi esegue quattro passaggi principali:

  • checkout: questo passaggio controlla il codice sorgente del progetto dal repository GitHub.
  • Update theme: questo passaggio inizializza e aggiorna i sottomoduli Git (se presenti) per garantire che il tema Hugo sia aggiornato. Questo è utile se il sito Hugo utilizza i Gitmodules per fare riferimento al tema utilizzato invece di eseguire il push di grandi file di temi già disponibili su GitHub.
  • Build Hugo site: questo passaggio crea il sito Hugo e specifica la cartella di destinazione come workspace/public.
  • persist_to_workspace: questo passaggio consente di persistere la cartella public (output della build di Hugo) nell’area di lavoro per utilizzarla successivamente in push build.

Push Build Job:

Il job push build è responsabile del push del sito costruito in un orphan branch (deploy) nel repository GitHub. In questo modo, il codice rimane sul branch predefinito e il branch deploy ospita solo i file statici del sito.

push build:
  executor: hugo-executor
  steps:
    - attach_workspace:
        at: workspace

    - run:
        name: Push build folder to GitHub
        command: |
          # Configure Git identity (replace <GitHubUsername> with your actual username)
          git config --global user.name "<GitHubUsername>"
          git config --global user.email "<GitHubUsername>@users.noreply.github.com"

          # Clone the repository (replace <your-repo-name> with your actual repository URL)
          git clone --branch deploy --depth 1 https://<GitHubUsername>:${GITHUB_TOKEN}@github.com/<GitHubUsername>/<your-repo-name>.git deployment

          # Copy the 'public' directory to the deployment folder
          cp -R workspace/public deployment

          # Navigate to the deployment folder
          cd deployment

          # Commit and push changes
          git add .
          git commit -m "Auto generated from ${CIRCLE_SHA1}"
          git push

Il job di cui sopra esegue le seguenti operazioni:

  • attach_workspace: questo passaggio collega lo spazio di lavoro in cui il job build ha persistito la directory public.
  • Push build folder to GitHub: questo passaggio esegue diverse operazioni Git:
    • Configura l’identità Git con il vostro nome utente e la vostra email GitHub.
    • Clona il vostro repository GitHub in una cartella denominata deployment sul computer del runner CircleCI.
    • Copia il contenuto della cartella workspace/public (il sito Hugo compilato) nella cartella deployment.
    • Cambia la directory di lavoro in deployment.
    • Apporta le modifiche con un messaggio che indica che si tratta di un commit generato automaticamente da CircleCI.
    • Invia le modifiche a un nuovo branch del repository GitHub.

Assicuratevi di sostituire <GitHubUsername> e <your-repo-name> con il vostro nome utente GitHub e il nome del repository. Inoltre, assicuratevi di creare un token di accesso a GitHub in modo che CircleCI possa accedere al vostro account GitHub.

Definire gli ambiti per il token di accesso GitHub
Definire gli ambiti per il token di accesso GitHub.

Quindi, aggiungete il token come variabile d’ambiente denominata GITHUB_TOKEN nelle impostazioni del progetto CircleCI.

Passaggio 9: Definire il workflow

Una volta impostati i job, la fase successiva prevede la configurazione del workflow. Continuando la configurazione di CircleCI, creaiamo un workflow che attivi il job build quando ci sono modifiche al codice nel branch main e che richieda che il job build sia completato con successo prima di eseguire push build:

workflows:
  version: 2
  build-and-deploy:
    jobs:
      - build:
          filters:
            branches:
              only:
                - main
      - push build:
          requires:
            - build

Passaggio 10: Commit e Push

Una volta configurato il workflow, eseguiamo il commit e il push delle modifiche sul repository Git. CircleCI rileva automaticamente la presenza del file di configurazione e attiva i workflow definiti in caso di modifiche al codice.

Dettagli della pipeline di CircleCI
Dettagli della pipeline di CircleCI.

Se controllate il repository GitHub, vedrete che il branch deploy ha già la cartella public, che contiene i file statici.

Potete verificare la configurazione completa di CircleCI in questo repository di esempio.

Passaggio 11: Distribuzione dei file statici su Kinsta

Il deploy su Kinsta avviene in pochi secondi, soprattutto ora che i file statici sono già stati creati. Seguite questi passaggi per distribuire gratuitamente il vostro sito Hugo con l’Hosting di Siti Statici:

  1. Accedete o create un account per visualizzare la dashboard MyKinsta.
  2. Autorizzate Kinsta con il vostro provider Git.
  3. Cliccate su Siti statici nella barra laterale di sinistra e poi su Aggiungi sito.
  4. Selezionate il repository e il branch da cui volete distribuire il sito (il branch deploy ).
  5. Assegnate un nome unico al vostro sito e cliccate su Continua.
  6. Lasciate vuoti i campi Comando di build e Versione node e specificate la directory di pubblicazione come public.
  7. Infine, cliccate su Crea sito.

E il gioco è fatto! In pochi secondi avrete un sito distribuito. Viene fornito un link per accedere alla versione distribuita del sito. Se lo desiderate, potrete aggiungere il vostro dominio personalizzato e il vostro certificato SSL.

Usare Hugo-bin per creare e distribuire un sito Hugo su Kinsta

Il pacchetto Hugo-bin è un wrapper binario per Hugo. Permette di costruire e distribuire il vostro progetto Hugo con comandi Node.js. Questo metodo non richiede uno strumento CI/CD per costruire il sito prima di distribuirlo sull’Hosting di Siti Statici di Kinsta.

Per utilizzare il pacchetto Hugo-bin nel progetto Hugo:

  1. Inizializzate Node.js nella root del progetto eseguendo il comando npm init -y.
  2. Quindi, installate Hugo-bin come developer dependency nel progetto eseguendo questo comando:
npm i -D hugo-bin
  1. Aggiungete i seguenti comandi di script al file package.json:
"scripts": {
    "build": "hugo",
    "create": "hugo new",
    "serve": "hugo server"
  }

In questo modo, Kinsta sarà in grado di eseguire la build e servire il vostro sito Hugo senza il bisogno di costruire i vostri file prima di distribuirli.

Una volta fatto tutto, inviate il codice al repository Git. Seguite questi passaggi per distribuire il sito statico su Kinsta:

  1. Accedete o crea un account per visualizzare la dashboard MyKinsta.
  2. Autorizzate Kinsta con il vostro provider Git.
  3. Cliccate su Siti statici nella barra laterale di sinistra e poi su Aggiungi sito.
  4. Selezionate il repository e il branch da cui desiderate effettuare il deploy.
  5. Assegnate un nome unico al sito.
  6. Aggiungete le impostazioni di build nel seguente formato:
    • Comando di build: npm run build
    • Versione Node: 18.16.0
    • Directory di pubblicazione: public
  1. Infine, cliccate su Crea sito.

E il gioco è fatto! Ora avete un sito distribuito in pochi secondi.

Servire i file statici solo su Kinsta

Infine, un altro metodo per distribuire il vostro sito Hugo su Kinsta consiste nel creare il sito in locale e poi distribuirlo su Kinsta. Questo processo genera una cartella public nella root del progetto. Tuttavia, lo svantaggio principale di questo metodo è che dovrete creare il sito localmente prima di ogni push, il che può richiedere molto tempo e può essere meno conveniente rispetto ad altri metodi che automatizzano il processo di creazione del sito.

Per impostazione predefinita, la cartella public è esclusa dal vostro repository Git grazie alla sua inclusione nel file .gitignore. Per includerla nel repository e distribuire il sito su Kinsta:

  1. Rimuovete la cartella public dal file .gitignore.
  2. Seguite i passaggi di distribuzione spiegati sopra.
  3. Distribuite il repository su Kinsta, assicurandovi che i campi Comando di build e Version Node rimangano vuoti, poiché il sito è già stato costruito.
  4. Specificate la directory di pubblicazione come public.

In alternativa, potete scegliere di inviare solo i file statici al vostro repository GitHub. In questo caso, non è necessario inizializzare un repository Git nella cartella principale del progetto. Dovete solo eseguire git init all’interno della cartella public. Questo vi permette di mantenere il controllo di versione dei file statici separato dal resto del progetto.

In questo scenario, quando si esegue il push dei file separatamente senza inserirli in una cartella public, al momento del deploy su Kinsta è necessario specificare la directory di pubblicazione come .. Questa notazione rappresenta la cartella principale e Kinsta servirà i file di conseguenza.

Riepilogo

In questo articolo abbiamo illustrato tre metodi efficaci per distribuire gratuitamente il vostro sito Hugo sulla piattaforma di Hosting di Siti Statici di Kinsta. Potete scegliere il metodo che meglio si adatta alle vostre esigenze specifiche. Inoltre, per maggiori informazioni sulla creazione di un sito statico veloce con Hugo, leggete la nostra guida completa.

Joel Olawanle Kinsta

Joel è uno Frontend developer che lavora in Kinsta come redattore tecnico. È un insegnante appassionato che ama l'open source e ha scritto oltre 200 articoli tecnici principalmente su JavaScript e i suoi framework.