103 lines
4.2 KiB
Markdown
103 lines
4.2 KiB
Markdown
# 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/
|