updates to wiki for architecture changes
This commit is contained in:
123
README.md
123
README.md
@@ -1,102 +1,41 @@
|
|||||||
# Project: Self-Hosted CI/CD and Static Hosting (Blowfish)
|
# Project: Hugo Documentation Framework (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.
|
This repository manages the **Hugo build environment** (config, themes, and layouts) for both the Public and Private Wikis.
|
||||||
|
|
||||||
## 🏗️ Architecture Split
|
## 🏗️ Architecture
|
||||||
|
|
||||||
To allow for seamless Dev vs. Prod workflows, the architecture is split into two repositories:
|
To allow for seamless Dev vs. Prod workflows, the architecture is split into three repositories:
|
||||||
|
|
||||||
1. **Framework (`/srv/dev/hugo/wiki`)**: This repository (`hugo-framework`). Contains the Hugo engine, themes (Blowfish), layouts, and configuration.
|
1. **Framework (`/srv/dev/hugo/wiki`)**: This repository (`hugo-framework`). Contains the Hugo engine, themes (Blowfish), and the **default configuration**.
|
||||||
2. **Content (`/srv/docs/public`)**: A separate repository (`docs-public`). Contains only the Markdown files and static assets.
|
2. **Public Content (`/srv/docs/public`)**: A separate repository (`docs-public`).
|
||||||
|
3. **Private Content (`/srv/docs/private`)**: A separate repository (`docs-private`).
|
||||||
|
|
||||||
**Local Dev "Live Link":**
|
**Dynamic Configuration Merging:**
|
||||||
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`.
|
The Framework defines the base styling in `config/_default/params.toml`.
|
||||||
|
However, the Content repositories can dynamically override:
|
||||||
|
* **Menus**: By providing a `config/_default/menus.en.toml` file.
|
||||||
|
* **Theme Settings (Edit Links)**: Injected via Environment Variables (`HUGO_PARAMS_ARTICLE_EDITURL`) during the CI/CD pipeline to avoid destroying the framework's default arrays.
|
||||||
|
|
||||||
|
## 💻 Local Development ("Live Link")
|
||||||
|
|
||||||
|
To write documentation with real-time previews, you use symbolic links on your host machine:
|
||||||
|
|
||||||
|
1. **Establish Symlinks**:
|
||||||
|
```bash
|
||||||
|
cd /srv/dev/hugo/wiki
|
||||||
|
rm -rf content static
|
||||||
|
ln -s /srv/docs/public content
|
||||||
|
ln -s /srv/docs/public/static static
|
||||||
|
```
|
||||||
|
2. **Preview Changes**:
|
||||||
|
```bash
|
||||||
|
hugo server --bind 0.0.0.0 --appendPort=false --baseURL="/"
|
||||||
|
```
|
||||||
|
|
||||||
## 🚀 CI/CD Pipeline
|
## 🚀 CI/CD Pipeline
|
||||||
|
|
||||||
Deployment is fully automated through Gitea Actions.
|
Deployment is fully automated through Gitea Actions stored in the **Content repositories** (e.g., `docs-public/.gitea/workflows/deploy.yaml`).
|
||||||
|
|
||||||
1. **Trigger:** Push a commit to the `main` branch of the `docs-public` repository.
|
During a build, the Runner dynamically clones this Framework via HTTPS, injects the Markdown files from the triggering repository, applies the `editURL` overrides, builds the site, and deploys directly into the Nginx web server volume (`/srv/caddy/sites`).
|
||||||
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.
|
|
||||||
|
|
||||||
---
|
*(Note: The volume name `/srv/caddy` is a legacy name; the servers actually running are lightweight `nginx:alpine` containers defined in `gitea/docker-compose.yaml`)*.
|
||||||
|
|
||||||
## 💻 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/
|
|
||||||
Reference in New Issue
Block a user