wompmacho
1dcb72cf51
All checks were successful
Deploy to Caddy / build-and-deploy (push) Successful in 20s
106 lines
3.9 KiB
Markdown
106 lines
3.9 KiB
Markdown
# Project: Self-Hosted CI/CD and Static Hosting
|
|
|
|
[TOC]
|
|
|
|
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.
|
|
|
|
## Architecture Overview
|
|
|
|
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.
|
|
|
|
--- |