Using my Gitea to the next level · Home Lab Explorers

Using my Gitea to the next level

Automatically uploading Gitea documentation to a Virtualmin webserver via workflow (Gitea Actions) using tokens.

A very simple website, but fine for documentation.(automation thats key here)The website is still in progress... It is a first draft using vs-code

add on post:https://www.skool.com/homelabexplorers/complete-guide-gitea-setup-proxmox-gitops-backup-restore?p=30d3ab26

mkdocs website:https://www.mkdocs.org/getting-started/

Bonus: How to set this up! (Quick Roadmap)

1. Local Project & Directory StructureTo use MkDocs Material, your project folder on your local management PC must be structured exactly like this:proxmox-homelab/ # Your main project root

├── 📂 .gitea/ # Gitea configuration folder

│ └── 📂 workflows/

│ └── 📄 deploy.yml # The Gitea Actions automation script

├── 📂 docs/ # ALL your Markdown documentation files go here

│ ├── 📄 index.md # Your website homepage (Required!)

│ ├── 📄 hardware.md # servers specs

│ ├── 📄 netwerk.md # QNAP switch, router & VLAN matrix

│ ├── 📄 dns.md # Technitium & Keepalived config

│ └── 📄 opslag.md # TrueNAS SCALE & PBS backend

├── 📄 .gitignore # Tells Git which files to ignore

└── 📄 mkdocs.yml # The main MkDocs theme & menu configuration

The Configuration File (mkdocs.yml)This file defines your website layout and menus. Create this in your root folder:yamlsite_name: "Spruitmans Homelab Wiki"

site_description: "Central documentation for Proxmox and TrueNAS."

site_author: "thats me"

theme:

name: material

palette:

scheme: slate

primary: teal

accent: teal

features:

- navigation.tabs

nav:

Home: index.md

Hardware: hardware.md

Network & VLANs: netwerk.md

DNS Cluster: dns.md

Storage & Media: opslag.md

2. Gitea Security Configuration (Secrets)To prevent putting your plain-text passwords inside the public code, save your Virtualmin password inside Gitea's secure vault:

Open your browser and go to your Gitea repository.Navigate to Settings ➔ Secrets ➔ Actions.Click Create Secret and add the following variable:Name: FTP_PASSWORDValue: [Your Virtualmin web user password

3. The Gitea Actions Workflow (.gitea/workflows/deploy.yml)This automation script tells your TrueNAS-hosted Gitea Runner exactly how to build the HTML files and upload them to Virtualmin via secure SFTP.

Create this file exactly at .gitea/workflows/deploy.yml:yamlname: Build and Deploy to Virtualmin via SFTP

on:

push:

branches:

- main

jobs:

build-and-deploy:

runs-on: ubuntu-latest

steps:

# Step 1: Clone the Markdown code from Gitea into the Runner

- name: Checkout Code from Git

uses: actions/checkout@v3

# Step 2: Set up a secure Python environment

- name: Install Python

uses: actions/setup-python@v4

with:

python-version: '3.11'

# Step 3: Install the MkDocs Material theme engine

- name: Install MkDocs Material

run: |

pip install --no-cache-dir mkdocs-material

# Step 4: Compile the Markdown files into static HTML (creates a 'site' folder)

- name: Build HTML Website

run: |

mkdocs build

# Step 5: Install LFTP deployment utility

- name: Install lftp for file transfer

run: |

sudo apt-get update -y && sudo apt-get install -y lftp

# Step 6: Securely upload everything into Virtualmin's public_html directory

- name: Upload website files via SFTP

run: |

lftp -e "set sftp:auto-confirm yes; mirror -R site/ public_html/; quit" \

-u homelab,${{ secrets.FTP_PASSWORD }} sftp://ip address webserver

4. How to Publish and Update via PowerShellWhenever you add a new .md file or make a small text adjustment, follow these three commands on your local PC to push it live:powershell# 1. Track all local changes and new files

git add .

# 2. Package your changes with a clear description

git commit -m "Update: Added new documentation pages"

# 3. Securely upload the files to your Gitea server

git push origin main

What happens automatically next?Gitea receives your text files.The runner App on your instantly wakes up.The runner builds the website and pushes the HTML files to your Virtualmin Ubuntu Server (ip address webserver).Within 30 seconds, your updates are live and viewable globally at https://example.com

0 comments

Using my Gitea to the next level