README.md aktualisiert
This commit is contained in:
Jörg Lohrer
parent
ffc3a67d6a
commit
bc7ca4f22f
191
README.md
191
README.md
|
|
@ -1,2 +1,189 @@
|
|||
# dings
|
||||
aha
|
||||
---
|
||||
title: Deployment von Hugo auf Codeberg Pages via Woodpecker CI
|
||||
author: Jörg Lohrer
|
||||
description: Mit Codeberg-Pages eine eigene Webseite hosten
|
||||
image: https://i.imgur.com/8CCHQZf.png
|
||||
tags: Hugo, Codeberg, Woodpecker, CI
|
||||
lang: de
|
||||
dir: ltr
|
||||
licence: CC-BY
|
||||
|
||||
---
|
||||
# Deployment von Hugo auf Codeberg Pages via Woodpecker CI
|
||||
|
||||
|
||||
## Anleitung zur Erstellung einer Hugo-Website auf Codeberg Pages
|
||||
Diese Anleitung zeigt Dir Schritt für Schritt, wie Du eine Hugo-Website auf Codeberg Pages erstellen kannst.
|
||||
|
||||
### Voraussetzungen:
|
||||
- Du brauchst ein [Codeberg](https://codeberg.org/)-Konto.
|
||||
- Du solltest bereit sein zu teilen
|
||||
- Du brauchst [Zugang zur WoodpeckerCI](https://codeberg.org/Codeberg-e.V./requests) bei Codeberg.
|
||||
|
||||
### Schritte
|
||||
|
||||
#### 1.  ***Forke das Template Repository***
|
||||
* Klicke auf den Fork-Button auf der Template-Seite:
|
||||
https://joerglohrer.codeberg.page/hugo-codeberg-pages-template
|
||||
Dadurch wird eine Kopie des Repositorys in deinem eigenen Codeberg-Konto erstellt.
|
||||
|
||||
#### 2. ***Ändere die `hugo.toml`-Datei***
|
||||
Öffne die `hugo.toml`-Datei i ***main***-Branch deines Repositorys.
|
||||
Ändere die erste Zeile in folgendem Format:
|
||||
`baseURL = 'https://UserName.codeberg.page/RepoName`
|
||||
Ersetze `UserName` durch Deinen Codeberg-Benutzernamen und `RepoName` durch den gewünschten Namen deiner Website gleichlautend mit dem Namen des Repository.
|
||||
|
||||
#### 3. Generiere einen Zugriffstoken:
|
||||
Melden Dich bei Deinem Codeberg-Konto an und navigiere zu Einstellungen > Anwendungen: https://codeberg.org/user/settings/applications.
|
||||
Klicke auf die Schaltfläche "Neue Anwendung erstellen".
|
||||
Geb Deiner Anwendung einen Namen, z. B. "Hugo-Website". Aktiviere die Option "Lesen und Schreiben" unter "repository". Klicke auf die Schaltfläche "Token generieren". Kopiere den generierten Zugriffstoken.
|
||||
|
||||
#### 4. Füge das Repository zu einer neuen Pipeline hinzu
|
||||
|
||||
Melde Dich bei CI/CD: https://ci.codeberg.org/ an. Klicke auf die Schaltfläche "+ Repository hinzufügen". Wähle dein Repository aus der Liste aus und klicke auf "Aktivieren".
|
||||
Wähle die Einstellungen zur gerade erstellten Pipeline aus. Klicke auf "Allgemein" und gib bei Pipeline-Pfad `.woodpecker.yml`ein. Speiche die Einstellung füge zwei Geheimnisse hinzu:
|
||||
- Name: `codeberg_token` - Wert: der in Schritt 3. generierte erstellten Zugriffstoken
|
||||
- Name: `mail` - Wert: Deine Mailadresse
|
||||
#### 5. Erstelle Markdown-Dateien
|
||||
Navigiere im Repository zu Verzeichnis `/content`. Erstelle hier beliebige Markdown-Dateien (`*.md`). Diese Dateien werden beim Pushen in das Repository automatisch durch zu einer statischen Webseite im  ***pages***-Branch verarbeitet
|
||||
|
||||
#### Fertig!
|
||||
Deine aktualisierte Seite ist unter: `https://UserName.codeberg.page/RepoName` erreichbar. Sie wird automatisch aktualisiert, wenn Du Änderungen an den (Markdown-)Dateien im  ***main***-Branch vornimmst.
|
||||
|
||||
#### Noch ein paar Hinweise
|
||||
- Hugo-Dokumentation https://gohugo.io/documentation/
|
||||
- Codeberg Pages-Dokumentation https://docs.codeberg.org/codeberg-pages/
|
||||
- Codeberg's CI Dokumentation https://docs.codeberg.org/ci/
|
||||
- Woodpecker Beispiele (auch die verwendete `.woodpecker.yaml` für Hugo): https://codeberg.org/Codeberg-CI/examples)
|
||||
|
||||
#### Tipps:
|
||||
- ***Design:*** Passe die Vorlagendateien im Verzeichnis themes an, um deiner Website einen individuellen Look zu geben.
|
||||
- ***Features:*** Nutze Hugo-Module, um deine Website zu erweitern.
|
||||
- ***Eigene Domain:*** Verknüpfe deine Website mit einem eigenen Domainnamen.
|
||||
|
||||
---
|
||||
|
||||
## Wie das hier alles erstellt wurde
|
||||
|
||||
https://toheine.net/posts/2023/website-deployment/
|
||||
https://discourse.gohugo.io/t/is-it-possible-to-use-hugo-in-codeberg-page-repositories/31012/3
|
||||
### [Neues Repository auf Codeberg erstellen](https://codeberg.org/repo/create)
|
||||
Lizenz: Apache-2.0, Repository initalisieren Standardbranch main, Rpository zu einem Template machen
|
||||
### Repo klonen
|
||||
https://docs.codeberg.org/getting-started/first-repository/#option-a%3A-clone-the-newly-created%2C-empty-repository
|
||||
```git clone https://codeberg.org/joerglohrer/hugo-codeberg-pages-template.git
|
||||
cd hugo-codeberg-pages-template
|
||||
```
|
||||
### Branch `pages` erstellen
|
||||
```
|
||||
git switch --orphan pages
|
||||
```
|
||||
|
||||
- `git switch`: Dieser Befehl wird verwendet, um zwischen verschiedenen Git-Branches zu wechseln.
|
||||
- `--orphan`: Diese Option erzeugt einen neuen Branch, der keine Eltern-Commits hat. Er ist sozusagen völlig losgelöst von der bisherigen Commit-Historie des Repositorys.
|
||||
- `pages`: Das ist der Name des neuen Branches, der erstellt wird.
|
||||
|
||||
```
|
||||
git rm --cached -r .
|
||||
```
|
||||
- `git rm`: Der Befehl zum Entfernen von Dateien aus der Git-Verfolgung. Die Dateien werden nicht aus deinem Arbeitsverzeichnis gelöscht.
|
||||
- `--cached`: Diese Flagge weist Git an, die Dateien nur aus dem Staging-Bereich zu entfernen, nicht aus deinem lokalen Dateisystem.
|
||||
- `-r`: Diese Flagge aktiviert die rekursive Entfernung, d.h. sie zielt auf Dateien in allen Unterverzeichnissen ab.
|
||||
- `.` : Der Punkt kennzeichnet "alles im aktuellen Verzeichnis und darunter".
|
||||
|
||||
```
|
||||
nano neu.md
|
||||
git add neu.md
|
||||
git commit -m "neu"
|
||||
git push --set-upstream origin pages
|
||||
```
|
||||
|
||||
### Hugo installieren
|
||||
hugo new site hugo-codeberg-pages-template --force
|
||||
|
||||
|
||||
|
||||
### Vorbereitung für die Pipeline
|
||||
#### [Access Token erstellen](https://docs.codeberg.org/advanced/access-token/)
|
||||
|
||||
Unter https://codeberg.org/user/settings/applications
|
||||
|
||||
Im Beispiel wird der Token-Name "hugopagetoken" generiert bei dem in den Berechtigungen unter "repository" Lesen und Schreiben ausgewählt ist.
|
||||
Soblad man auf “Token generieren” klickt, erscheint der Token mit einem Hinweis, diesen jetzt zu kopieren, da er später nicht mehr angezeigt wird.
|
||||
|
||||
#### Geheimnisse eintragen
|
||||
Auf https://ci.codeberg.org/repos das Repo hinzufügen für das die Pipeline gestartet werden soll und dort die Geheimnisse eintragen:
|
||||
|
||||
Im Beispiel wird ein Geheimnis mit dem Namen `codeberg_token` mit generierte `hugopagetoken` mit dem Wert `883029f2a627c7b5fa181f24b9205a775add1ff1` eingesetzt und dann noch das Geheimnis `mail` mit der Mailadresse des dazu passenden Codeberg-Users als Wert gespeichert.
|
||||
|
||||
Die Geheimnisse werden zur Laufzeit als Umgebungsvariablen an einzelne Pipelineschritte übergeben.
|
||||
|
||||
|
||||
Unter Allgemein
|
||||
|
||||
`.woodpecker.yml` angeben und die Vorlage verwenden aus folgendem Pipeline Beispiel
|
||||
|
||||
|
||||
|
||||
### Codeberg Pages
|
||||
https://docs.codeberg.org/codeberg-pages/
|
||||
Example Pipeline
|
||||
https://codeberg.org/Codeberg-CI/examples/src/branch/main/Hugo
|
||||
```shell=ssh
|
||||
# hugo.yml
|
||||
#
|
||||
# Nimmt ein Repository mit Hugo-Quellcode, generiert die statische Website und veröffentlicht das Ergebnis auf Codeberg Pages
|
||||
#
|
||||
# Benötigt ein Codeberg-Zugangs-Token (codeberg_token) als secret in der Woodpecker-Konfiguration
|
||||
# Verwendet auch ein anderes secret (mail) mit E-Mail-Adresse für die Git-Konfiguration
|
||||
#
|
||||
# .domains-Datei im Repository wird in den Ausgabezweig kopiert, damit benutzerdefinierte Domains funktionieren
|
||||
#
|
||||
# Die Variable HUGO_OUTPUT muss auf den in Hugo konfigurierten Ausgabeordner gesetzt werden.
|
||||
|
||||
|
||||
# Ausschluss, dass die page-pipeline auf den "pages" Zweig angewendet wird
|
||||
when:
|
||||
branch:
|
||||
exclude: pages
|
||||
event: [push, pull_request]
|
||||
|
||||
# Rekursives Klonen wird verwendet, um die als Git-Submodule angegebenen Themes vollständig zu klonen
|
||||
clone:
|
||||
git:
|
||||
image: woodpeckerci/plugin-git
|
||||
settings:
|
||||
recursive: true
|
||||
|
||||
steps:
|
||||
# Build hugo static files
|
||||
build:
|
||||
image: klakegg/hugo
|
||||
commands:
|
||||
- hugo --minify
|
||||
when:
|
||||
event: [pull_request, push]
|
||||
|
||||
publish:
|
||||
image: bitnami/git
|
||||
# Must be set in Woodpecker configuration
|
||||
secrets: [mail, codeberg_token]
|
||||
environment:
|
||||
- HUGO_OUTPUT=public
|
||||
commands:
|
||||
# Git configuration
|
||||
- git config --global user.email $MAIL
|
||||
- git config --global user.name "Woodpecker CI"
|
||||
- git clone -b pages https://$CODEBERG_TOKEN@codeberg.org/$CI_REPO.git $CI_REPO_NAME
|
||||
# Copy build step output to repository folder
|
||||
- cp -ar $HUGO_OUTPUT/. $CI_REPO_NAME/
|
||||
# Needed for custom domains
|
||||
- cp .domains $CI_REPO_NAME || true # Ignore if it doesn't exist
|
||||
# Commit and push all static files with pipeline started timestamp
|
||||
- cd $CI_REPO_NAME
|
||||
- git add .
|
||||
- git commit -m "Woodpecker CI ${CI_COMMIT_SHA}"
|
||||
- git push
|
||||
when:
|
||||
event: push
|
||||
```
|
||||
Loading…
Reference in a new issue