Project: Self-Hosted CI/CD and Static Hosting

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.

Components:

• Gitea: Manages code repositories and triggers automated builds via Gitea Actions.
• Gitea Runner: Executes build tasks inside Docker containers with mapped volumes to the host.
• Caddy: Acts as the internal static file server.
• Nginx Proxy Manager: The "Front Door" that handles SSL certificates and proxies traffic to Caddy.
• Hugo: for static site generation.

Deployment Process

Deployment is fully automated through Gitea Actions.

1. Trigger: Push a commit to the main branch.
2. Runner Execution: The Gitea Runner detects the push, spawns a Hugo build container, 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.
4. Serving: Caddy detects the file updates in /srv/caddy/sites/wiki/ and serves the content immediately.

Build and Test

1. Local Test Build:

   Running hugo in dev environment (code-server)

   alias hugo-rebuild='rm -rf public/ && hugo server --appendPort=false --baseURL="/" --ignoreCache'
   

   This generates the public/ directory. Verify the build by opening public/index.html in your browser.

2. Asset Management:

   Place any files for download (PDFs, images) in the /static directory in your repo. Hugo will copy them directly to the root of the built site.

Maintenance

• Logs: Monitor runner logs if deployments fail to update:

docker logs gitea_runner

Hugo fresh Installation notes

Prerequisites

• Hugo (Extended Version): Ensure you have the extended version installed, as Blowfish requires it for SCSS/PostCSS processing.

• Node.js & npm: Required for managing the theme's dependencies (PostCSS, Autoprefixer, etc.).

• npx: Comes with npm; used to run the build-time tools for Blowfish.

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

To install Hugo fresh—especially for a project like Blowfish—you need more than just the binary; you need the extended capabilities for CSS processing.

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 Site

• Run these commands in your project root:

  hugo new site my-wiki
  cd my-wiki
  git init
  

• Add the theme as a submodule:

  git submodule add https://github.com/nunocoracao/blowfish.git themes/blowfish
  

• Install theme dependencies:

  npm install # (run this in the root of your Hugo project)
  

Critical Configuration Initialization

To prevent common theme breakage, 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.

---