# 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)**: 
    ```bash
    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**: 
    ```bash
    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.

```bash
# 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](https://github.com/gohugoio/hugo/releases).

    ```bash
    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**:
    ```bash
    git clone https://git.wompmacho.com/wompmacho/hugo-framework.git my-wiki
    cd my-wiki
    ```
2.  **Pull Submodules** (The Blowfish theme):
    ```bash
    git submodule update --init --recursive
    ```
3.  **Install Node Dependencies**:
    ```bash
    npm install
    ```
4.  **Establish Symlinks** (Point to your content repo):
    ```bash
    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/