hugo-framework/README.md

Project: Self-Hosted CI/CD and Static Hosting (Blowfish)

This project manages a centralized self-hosted environment using Gitea for version control and automation, Caddy as a lightweight web server, and Nginx Proxy Manager for SSL termination. The system relies on a shared host volume to move static files from the Gitea Runner to the web server directory.

🏗️ Architecture Split

To allow for seamless Dev vs. Prod workflows, the architecture is split into two repositories:

1. Framework (/srv/dev/hugo/wiki): This repository (hugo-framework). Contains the Hugo engine, themes (Blowfish), layouts, and configuration.
2. Content (/srv/docs/public): A separate repository (docs-public). Contains only the Markdown files and static assets.

Local Dev "Live Link": In this hugo-framework repository, content/ and static/ are symbolic links pointing to /srv/docs/public. This allows for real-time local previews of your notes when running hugo server.

🚀 CI/CD Pipeline

Deployment is fully automated through Gitea Actions.

1. Trigger: Push a commit to the main branch of the docs-public repository.
2. Runner Execution: The Gitea Runner mounts the hugo-framework directory and executes the build steps.
3. Sync: The Runner uses a volume mount (/srv/caddy/sites:/deploy) to copy the generated public/ folder directly to the host's web server directory.

---

💻 Local Development

1. Work in the Docs folder: Edit your markdown files in /srv/docs/public/.
2. Asset Management: Place any files for download (PDFs, images) in the /srv/docs/public/static/ directory.
3. Preview changes (Code-Server):

   cd /srv/dev/hugo/wiki
   alias hugo-rebuild='rm -rf public/ && hugo server --bind 0.0.0.0 --appendPort=false --baseURL="/" --ignoreCache'
   hugo-rebuild
   

4. Deploy:

   cd /srv/docs/public
   git add .
   git commit -m "Your note update"
   git push origin main
   

---

🛠️ Hugo Fresh Installation Notes

To rebuild this environment—especially for a project like Blowfish—you need more than just the binary; you need the extended capabilities for CSS processing.

Prerequisites

• Hugo (Extended Version): Required for SCSS/PostCSS processing.
• Node.js & npm: Required for managing the theme's dependencies.
• npx: Comes with npm; used to run build-time tools for Blowfish.

# Install nvm script and updating bashrc
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

1. Installation (The "Extended" Way)

• Linux/Ubuntu: Use the .deb package from the Hugo GitHub releases.

  wget https://github.com/gohugoio/hugo/releases/download/v0.140.0/hugo_extended_0.140.0_linux-amd64.deb
  sudo dpkg -i hugo_extended_0.140.0_linux-amd64.deb
  

• Verify: Ensure you have the extended version: hugo version (it should explicitly say +extended).

2. Initialize the Framework

If you are cloning this hugo-framework repository fresh:

1. Clone the Repo:

   git clone https://git.wompmacho.com/wompmacho/hugo-framework.git my-wiki
   cd my-wiki
   

2. Pull Submodules (The Blowfish theme):

   git submodule update --init --recursive
   

3. Install Node Dependencies:

   npm install
   

4. Establish Symlinks (Point to your content repo):

   rm -rf content static
   ln -s /path/to/docs-public/content ./content
   ln -s /path/to/docs-public/static ./static
   

3. Critical Blowfish Configuration Note

To prevent common theme breakage during a fresh setup, you must initialize the configuration files correctly:

• Copy the config directory from themes/blowfish/config/_default/ to your project's config/ directory.
• Ensure your hugo.toml (or config.toml) correctly references the Blowfish theme.
• If the site is blank, run npx postcss or ensure your package.json has the correct scripts to compile SCSS, as Hugo cannot process Blowfish's advanced CSS/JS requirements without these tools.

For full theme documentation, visit: https://blowfish.page/docs/