Hugo Blog mit Paper Theme auf Coolify deployen

Schritt-für-Schritt-Anleitung zum Erstellen eines Hugo-Blogs mit dem Paper Theme und Deployment auf Coolify.

Voraussetzungen

• Hugo (extended Version) installiert
• Go installiert (wird fuer Hugo Modules benoetigt)
• Git installiert
• GitHub CLI installiert und eingeloggt (gh auth login)
• Ein laufender Coolify-Server mit verbundenem GitHub-Account

1. Hugo-Projekt erstellen

mkdir mein-blog && cd mein-blog
hugo new site . --force
git init

2. Hugo Modules initialisieren

Wichtig: Hugo Modules statt Git Submodules verwenden. Submodules funktionieren nicht zuverlaessig in Docker-Builds.

hugo mod init github.com/DEIN-USERNAME/mein-blog

3. Konfiguration (hugo.toml)

Ersetze den Inhalt von hugo.toml mit:

baseURL = "https://deine-domain.example.com/"
title = "Mein Blog"
author = "Dein Name"
copyright = "Dein Name"
languageCode = "de"
DefaultContentLanguage = "de"
enableInlineShortcodes = true
ignoreErrors = ["error-remote-getjson"]

[module]
  [[module.imports]]
    path = "github.com/nanxiaobei/hugo-paper"

[pagination]
  pagerSize = 5

[params]
  color = 'linen'
  github = 'dein-github-username'
  avatar = ''
  name = 'Dein Name'
  bio = 'Deine Bio'

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

[menu]
  [[menu.main]]
    identifier = "about"
    name = "About"
    url = "/about/"
    weight = 10

[taxonomies]
  category = "categories"
  tag = "tags"
  series = "series"

Wichtig: Die baseURL muss auf die URL zeigen, unter der dein Blog erreichbar sein wird (die Coolify-Domain). Wenn du die URL noch nicht kennst, kannst du sie spaeter aendern.

Verfuegbare Theme-Farben

Ueber [params] color koennen folgende Farben gesetzt werden: linen, wheat, gray, light

4. Theme-Abhaengigkeiten laden

hugo mod get
hugo mod tidy

5. Inhalte erstellen

Startseite

# content/_index.md

+++
author = "Dein Name"
+++

About-Seite

# content/about.md

+++
title = "About"
description = "Ueber mich"
date = "2026-01-01"
author = "Dein Name"
+++

Hier steht dein About-Text.

Erster Blogbeitrag

# content/post/mein-erster-beitrag.md

+++
title = "Mein erster Beitrag"
date = "2026-01-01"
description = "Beschreibung des Beitrags"
tags = ["hugo", "blog"]
categories = ["allgemein"]
author = "Dein Name"
+++

Der Text vor dem `<!--more-->` wird als Vorschau angezeigt.

<!--more-->

## Ueberschrift

Der restliche Inhalt des Beitrags.

6. Lokal testen

hugo server -D

Oeffne http://localhost:1313/ im Browser. Das Theme sollte vollstaendig geladen sein.

7. Dockerfile erstellen

Erstelle eine Dockerfile im Projektroot:

FROM hugomods/hugo:exts as builder
COPY . /src
WORKDIR /src
RUN hugo mod get && hugo --gc --minify

FROM caddy:alpine
COPY --from=builder /src/public /usr/share/caddy

Was passiert hier:

1. hugomods/hugo:exts ist ein Docker-Image mit Hugo + Go (benoetigt fuer Hugo Modules)
2. hugo mod get laedt das Paper Theme automatisch herunter
3. hugo --gc --minify baut die statische Seite
4. caddy:alpine serviert die fertige Seite aus /usr/share/caddy

8. .gitignore erstellen

resources/
.hugo_build.lock
.claude/

Hinweis: public/ wird hier bewusst NICHT ignoriert, damit du den Build auch lokal testen kannst.

9. Auf GitHub pushen

git add -A
git commit -m "Initial commit: Hugo blog with Paper theme"
gh repo create mein-blog --public --source=. --remote=origin --push

10. In Coolify einrichten

1. Neues Projekt in Coolify anlegen
2. Neue Ressource hinzufuegen > Application
3. GitHub als Source waehlen und dein Repository auswaehlen
4. Folgende Einstellungen konfigurieren:

Einstellung	Wert
Build Pack	Dockerfile
Port	80
Branch	main

5. Deploy klicken

11. baseURL anpassen

Nachdem Coolify die Domain/URL zugewiesen hat, aendere die baseURL in hugo.toml:

baseURL = "https://deine-coolify-domain.example.com/"

Dann erneut pushen:

git add hugo.toml
git commit -m "Update baseURL"
git push

Coolify deployed automatisch bei jedem Push (wenn Auto-Deploy aktiviert ist).

Weitere Beitraege hinzufuegen

1. Neue .md-Datei in content/post/ erstellen
2. Frontmatter mit title, date, tags etc. hinzufuegen
3. Committen und pushen

git add content/post/neuer-beitrag.md
git commit -m "Neuer Beitrag: Titel"
git push

Haeufige Fehler

Theme wird nicht geladen / Seite ohne Styling

• Falsche baseURL: Die baseURL in hugo.toml muss exakt mit der Coolify-URL uebereinstimmen
• Git Submodules statt Hugo Modules: Submodules werden im Docker-Build nicht korrekt geklont. Immer Hugo Modules ([module] in hugo.toml + go.mod) verwenden

Nixpacks erkennt das Projekt nicht

Nixpacks kann Hugo-Projekte nicht automatisch erkennen. Deshalb wird ein Dockerfile verwendet. Build Pack in Coolify auf Dockerfile stellen.

Build schlaegt fehl

Sicherstellen, dass go.mod und go.sum im Repository vorhanden und committed sind:

hugo mod tidy
git add go.mod go.sum
git commit -m "Update go modules"
git push