# 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)

    ```bash
    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:
```bash
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](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 Site

- Run these commands in your project root:

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

---