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.

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

Build and Test

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.
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.

3.9 KiB Raw Blame History