From aa02ea67aa00d0b46b6bb5b43fdb0857f5352078 Mon Sep 17 00:00:00 2001 From: michael1986 Date: Tue, 2 Dec 2025 13:12:29 +0100 Subject: [PATCH] wiki --- Home.md | 0 Quick-Start.md | 0 WIKI_INTEGRATION.md | 361 -------------------------------------------- build-pipeline.md | 31 ---- readme-pipe.md | 141 ----------------- test.md | 40 ----- 6 files changed, 573 deletions(-) delete mode 100644 Home.md delete mode 100644 Quick-Start.md delete mode 100644 WIKI_INTEGRATION.md delete mode 100644 build-pipeline.md delete mode 100644 readme-pipe.md delete mode 100644 test.md diff --git a/Home.md b/Home.md deleted file mode 100644 index e69de29..0000000 diff --git a/Quick-Start.md b/Quick-Start.md deleted file mode 100644 index e69de29..0000000 diff --git a/WIKI_INTEGRATION.md b/WIKI_INTEGRATION.md deleted file mode 100644 index 9f66c15..0000000 --- a/WIKI_INTEGRATION.md +++ /dev/null @@ -1,361 +0,0 @@ -# Gitea Wiki Integration Guide - -This guide explains how to integrate the local `wiki/` folder with Gitea's wiki system. - -## How Gitea Wikis Work - -Gitea stores wiki pages in a **separate Git repository** with the naming pattern: -``` -.wiki.git -``` - -For the `viewer` repository: -- Main repo: `git@git.appmodel.nl:Tour/viewer.git` -- Wiki repo: `git@git.appmodel.nl:Tour/viewer.wiki.git` - -Wiki pages are **markdown files** (`.md`) stored in the root of the wiki repository. - -## Integration Options - -### Option 1: Push Local Wiki to Gitea (Recommended) - -This approach replaces the current Gitea wiki with your local content. - -```bash -# 1. Clone the Gitea wiki repository -git clone git@git.appmodel.nl:Tour/viewer.wiki.git viewer-wiki - -# 2. Copy your wiki files to the wiki repository -cd viewer-wiki -cp ../viewer/wiki/*.md . - -# 3. Commit and push -git add . -git commit -m "Initialize wiki with documentation" -git push origin master - -# 4. View on Gitea -# Navigate to: https://git.appmodel.nl/Tour/diagram/wiki -``` - -### Option 2: Use Git Submodule (Bidirectional Sync) - -Keep the wiki as a submodule in the main repository for easy synchronization. - -```bash -# In the main diagram repository -cd /c/vibe/diagram - -# Remove local wiki folder -rm -rf wiki/ - -# Add Gitea wiki as submodule -git submodule add git@git.appmodel.nl:Tour/viewer.wiki.git wiki - -# Copy your documentation -cp ../temp-wiki-backup/*.md wiki/ - -# Commit to wiki submodule -cd wiki -git add . -git commit -m "Add documentation" -git push origin master - -# Update main repository -cd .. -git add wiki -git commit -m "Add wiki as submodule" -git push origin main -``` - -Now changes can be made either: -- **In Gitea UI**: Edit wiki pages directly -- **Locally**: Edit in `wiki/` folder, commit, and push - -To sync changes from Gitea: -```bash -cd wiki -git pull origin master -cd .. -git add wiki -git commit -m "Update wiki submodule" -git push -``` - -### Option 3: Git Subtree (Advanced) - -Similar to submodule but integrates the wiki history into the main repository. - -```bash -# Add wiki as subtree -git subtree add --prefix=wiki git@git.appmodel.nl:Tour/diagram.wiki.git master --squash - -# Push changes to wiki -git subtree push --prefix=wiki git@git.appmodel.nl:Tour/diagram.wiki.git master - -# Pull changes from wiki -git subtree pull --prefix=wiki git@git.appmodel.nl:Tour/diagram.wiki.git master --squash -``` - -### Option 4: Automated Sync Script - -Create a script to automatically sync wiki changes. - -Create `sync-wiki.sh`: -```bash -#!/bin/bash -# sync-wiki.sh - Sync local wiki with Gitea - -WIKI_REPO="git@git.appmodel.nl:Tour/diagram.wiki.git" -WIKI_DIR="wiki" -TEMP_WIKI="/tmp/gitea-wiki-$$" - -# Clone Gitea wiki -git clone "$WIKI_REPO" "$TEMP_WIKI" - -# Copy local changes to temp wiki -cp -r "$WIKI_DIR"/*.md "$TEMP_WIKI/" - -# Commit and push -cd "$TEMP_WIKI" -git add . -if git diff-staged --quiet; then - echo "No changes to sync" -else - git commit -m "Sync wiki from main repository" - git push origin master - echo "Wiki synced successfully" -fi - -# Cleanup -cd - -rm -rf "$TEMP_WIKI" -``` - -Usage: -```bash -chmod +x sync-wiki.sh -./sync-wiki.sh -``` - -## Recommended Workflow - -For your deployment pipeline, I recommend **Option 1** with a manual push: - -### Step-by-Step Setup - -1. **Create wiki repository on Gitea** (if not exists): - - Go to: https://git.appmodel.nl/Tour/diagram - - Click "Wiki" tab - - Create first page (triggers wiki repo creation) - -2. **Push local wiki content**: -```bash -# Clone wiki repository -cd /c/vibe -git clone git@git.appmodel.nl:Tour/diagram.wiki.git - -# Copy your wiki files -cd diagram.wiki -cp ../diagram/wiki/*.md . - -# Verify files -ls -la - -# Commit and push -git add . -git commit -m "Initialize wiki documentation - -Added: -- Home.md: Main documentation page -- Quick-Start.md: Quick start guide -" -git push origin master -``` - -3. **Verify on Gitea**: - - Navigate to: https://git.appmodel.nl/Tour/diagram/wiki - - You should see your wiki pages - -4. **Keep local wiki in main repo** (optional): - - Keep `wiki/` folder in main repo as "source of truth" - - When updating wiki, manually sync to Gitea wiki repo - - Or set up automated sync via CI/CD - -## Wiki Page Naming - -Gitea wikis follow these conventions: - -| Filename | URL | Purpose | -|----------|-----|---------| -| `Home.md` | `/wiki/` or `/wiki/Home` | Main wiki page | -| `Quick-Start.md` | `/wiki/Quick-Start` | Quick start guide | -| `API-Reference.md` | `/wiki/API-Reference` | API documentation | - -**Rules**: -- Use PascalCase or kebab-case for multi-word pages -- Spaces in filenames become hyphens in URLs -- First page is always `Home.md` - -## Linking Between Pages - -In your markdown files: - -```markdown - -[Quick Start Guide](Quick-Start) - - -[Get Started](Quick-Start) - - -[View Code](../) - - -[Dockerfile](../src/master/Dockerfile) - - -[Diagrams Library](https://diagrams.mingrammer.com/) -``` - -## Automation with Post-Receive Hook - -To automatically sync wiki on deployment, add to Gitea post-receive hook: - -```bash -#!/usr/bin/env bash - -# Deploy main app -/usr/local/bin/app-deploy diagram - -# Sync wiki (if wiki/ folder exists in repo) -if [ -d "/opt/apps/diagram/wiki" ]; then - cd /tmp - git clone git@git.appmodel.nl:Tour/diagram.wiki.git gitea-wiki-$$ - cp /opt/apps/diagram/wiki/*.md /tmp/gitea-wiki-$$/ - cd /tmp/gitea-wiki-$$ - git add . - if ! git diff --staged --quiet; then - git commit -m "Auto-sync from main repository" - git push origin master - fi - cd /tmp - rm -rf /tmp/gitea-wiki-$$ -fi -``` - -## Current Setup Instructions - -Based on your current setup, here's what to do: - -```bash -# 1. Navigate to your diagram project -cd /c/vibe/diagram - -# 2. Clone the wiki repository (for viewer, adjust as needed) -cd .. -git clone git@git.appmodel.nl:Tour/diagram.wiki.git - -# 3. Copy wiki files -cp diagram/wiki/*.md diagram.wiki/ - -# 4. Push to Gitea -cd diagram.wiki -git add . -git commit -m "Initialize wiki with deployment documentation" -git push origin master - -# 5. Verify -# Open: https://git.appmodel.nl/Tour/diagram/wiki -``` - -## Maintaining Both Wikis - -If you want to keep both local and Gitea wikis in sync: - -### Manual Sync (Simple) -```bash -# After editing local wiki files -cd /c/vibe/diagram/wiki -cp *.md /c/vibe/diagram.wiki/ -cd /c/vibe/diagram.wiki -git add . -git commit -m "Update documentation" -git push -``` - -### Automated Sync (Add to package.json or Makefile) -```json -{ - "scripts": { - "sync-wiki": "cp wiki/*.md ../diagram.wiki/ && cd ../diagram.wiki && git add . && git commit -m 'Sync wiki' && git push" - } -} -``` - -Or create a `Makefile`: -```makefile -.PHONY: sync-wiki - -sync-wiki: - @echo "Syncing wiki to Gitea..." - @cp wiki/*.md ../diagram.wiki/ - @cd ../diagram.wiki && git add . && git commit -m "Sync wiki from main repo" && git push - @echo "Wiki synced successfully!" -``` - -Usage: `make sync-wiki` - -## Best Practices - -1. **Single Source of Truth**: Choose one location (local or Gitea) as authoritative -2. **Version Control**: Keep wiki changes in Git history -3. **Review Process**: Use pull requests for significant documentation changes -4. **Link Checking**: Regularly verify internal links work -5. **Consistent Formatting**: Use markdown linting tools -6. **Table of Contents**: Keep `Home.md` as navigation hub - -## Troubleshooting - -### Wiki Repository Doesn't Exist - -Create the wiki first in Gitea UI: -1. Go to repository: https://git.appmodel.nl/Tour/diagram -2. Click "Wiki" tab -3. Click "Create New Page" -4. Create a dummy page (will be overwritten) -5. Now you can clone `diagram.wiki.git` - -### Permission Denied - -Ensure your SSH key is added to Gitea: -```bash -ssh -T git@git.appmodel.nl -``` - -### Merge Conflicts - -If both local and Gitea wiki are edited: -```bash -cd diagram.wiki -git pull origin master -# Resolve conflicts manually -git add . -git commit -m "Merge local and remote changes" -git push -``` - -## Summary - -**Recommended approach for your setup**: - -1. Keep `wiki/` in main repository for version control -2. Manually push to Gitea wiki repository when documentation is ready -3. Optionally add automated sync in post-receive hook -4. Edit wiki locally, sync to Gitea for visibility - -This gives you the best of both worlds: -- ✅ Documentation versioned with code -- ✅ Visible wiki in Gitea UI -- ✅ Easy to maintain and update -- ✅ Works with existing deployment pipeline diff --git a/build-pipeline.md b/build-pipeline.md deleted file mode 100644 index ff2408d..0000000 --- a/build-pipeline.md +++ /dev/null @@ -1,31 +0,0 @@ -# Appmodel Home Lab – Build & Deploy Pipeline - -Dit document beschrijft hoe een nieuwe applicatie in het home lab wordt aangemaakt en hoe de build- & deploy-pipeline werkt. - -## Overzicht - -- **Broncode**: Gitea (`https://git.appmodel.nl`) -- **Build & runtime**: Docker containers op netwerk `traefik_net` -- **Routing & TLS**: Traefik (`https://traefik.appmodel.nl`) -- **Automatische deploy**: Gitea `post-receive` hooks → `app-deploy ` - -## Pipeline in één diagram - -```mermaid -flowchart LR - Dev[💻 Dev machine\nVS Code / Git] -->|git push| Gitea[📚 Gitea\nTour/] - - subgraph Server[🏠 Home lab server\n192.168.1.159] - Gitea --> Hook[🔔 post-receive hook\n/app-deploy ] - - Hook --> Deploy[⚙️ app-deploy \n/git pull + docker compose up -d --build ] - - subgraph Docker[🐳 Docker / traefik_net] - AppC[🧱 App container\n.appmodel.nl] - Traefik[🚦 Traefik\nReverse Proxy] - end - end - - Deploy --> AppC - Traefik --> AppC - Client[🌐 Browser / API client] -->|https://.appmodel.nl| Traefik diff --git a/readme-pipe.md b/readme-pipe.md deleted file mode 100644 index 51bff8c..0000000 --- a/readme-pipe.md +++ /dev/null @@ -1,141 +0,0 @@ -1. Nieuwe app aanmaken -1.1 Gitea repo - -Log in op Gitea: https://git.appmodel.nl - -Maak een nieuwe repo aan, bijvoorbeeld: - -Owner: Tour - -Name: viewer - -1.2 Skeleton genereren op de server - -Op de server: - -apps-create viewer static-fe - - -Dit doet: - -/opt/apps/viewer klaarzetten (proberen te clonen uit git@git.appmodel.nl:Tour/viewer.git) - -een multi-stage Dockerfile voor een Node-based static frontend aanmaken - -~/infra/viewer/docker-compose.yml aanmaken met: - -service viewer - -koppeling aan traefik_net - -Traefik route: https://viewer.appmodel.nl - -2. Develop & build - -Op je dev machine: - -git clone git@git.appmodel.nl:Tour/viewer.git -cd viewer -# bouw je app zoals normaal -npm install -npm run build # output in dist/ -git add . -git commit -m "First version" -git push - - -De Dockerfile verwacht een dist/ map met static files. - -3. Deploy pipeline -3.1 app-deploy - -Op de server verzorgt app-deploy de generieke deploy: - -app-deploy viewer - - -Doet: - -cd /opt/apps/viewer - -git pull --ff-only - -cd /home/tour/infra/viewer - -docker compose up -d --build viewer - -Logs komen in: - -/var/log/app-deploy-viewer.log - -3.2 Automatisch deployen via Gitea hook - -In Gitea (repo Tour/viewer): - -Ga naar Instellingen → Git Hooks - -Kies post-receive - -Gebruik: - -#!/usr/bin/env bash -/usr/local/bin/app-deploy viewer - - -Vanaf nu: - -Elke git push naar Tour/viewer triggert automatisch een deploy. - -4. Traefik & DNS - -Traefik draait in de traefik stack op dezelfde server en beheert: - -git.appmodel.nl - -auction.appmodel.nl - -aupi.appmodel.nl - -… (nieuwe apps via labels) - -Nieuwe app viewer krijgt via apps-create al de juiste labels: - -labels: - - "traefik.enable=true" - - "traefik.http.routers.viewer.rule=Host(`viewer.appmodel.nl`)" - - "traefik.http.routers.viewer.entrypoints=websecure" - - "traefik.http.routers.viewer.tls=true" - - "traefik.http.routers.viewer.tls.certresolver=letsencrypt" - - "traefik.http.services.viewer.loadbalancer.server.port=80" - - -Je moet alleen in DNS nog een record maken: - -viewer.appmodel.nl → publieke IP van de server - -Traefik + Let’s Encrypt regelen het certificaat automatisch. - -5. Nieuwe app types (toekomst) - -Het apps-create script ondersteunt nu: - -static-fe – Node build → Nginx → static frontend - -Later kun je extra types toevoegen, bijvoorbeeld: - -api-py – Python (Flask/FastAPI) API - -worker-py – background worker / crawler - -Door per type een eigen Dockerfile-sjabloon en standaard docker-compose.yml te genereren, wordt een nieuw project neerzetten: - -apps-create stats api-py -apps-create crawler worker-py - - -en blijft de pipeline (app-deploy ) identiek. - -Je kunt nu: - -apps-create viewer static-fe -app-deploy viewer \ No newline at end of file diff --git a/test.md b/test.md deleted file mode 100644 index da50673..0000000 --- a/test.md +++ /dev/null @@ -1,40 +0,0 @@ -┌─────────────────────────────────────────────────────────────────────┐ -│ 🌐 Internet / Cloud │ -└────────────────┬────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────────┐ -│ 🛜 Router (hub.lan) - 192.168.1.1 │ -│ Gateway & DHCP │ -└────────────────┬────────────────────────────────────────────────────┘ - │ - ┌────────────┴────────────┬──────────────┬──────────────┐ - ▼ ▼ ▼ ▼ -┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ -│ LAN │ │ LAN │ │ LAN │ │ LAN │ -│ 192.168.│ │ Infra & │ │ Home │ │ IoT & │ -│ 1.x │ │ DNS │ │ Assist │ │ Workers │ -│ │ │ │ │ │ │ │ -│ │ │ │ │ │ │ │ -│ ┌────┐ │ │ ┌────┐ │ │ ┌────┐ │ │ ┌────┐ │ -│ │Core│ │ │ │DNS │ │ │ │ HA │ │ │ │Atlas│ │ -│ │ Srv│ │ │ │Host│ │ │ │Host│ │ │ │ │ │ -│ └┬───┘ │ │ └┬───┘ │ │ └┬───┘ │ │ └┬───┘ │ -│ │ │ │ │ │ │ │ │ │ │ │ -│ ┌─▼──┐ │ │ ┌─▼──┐ │ │ ┌─▼──┐ │ │ │ │ -│ │Dock│ │ │ │AdGr│ │ │ │Hass│ │ │ │ │ -│ │er │ │ │ │d │ │ │ │ │ │ │ │ │ -│ └────┘ │ │ └────┘ │ │ └────┘ │ │ │ │ -│ │ │ │ │ │ │ │ -└──────────┘ └──────────┘ └──────────┘ └──────────┘ - │ - │ ┌─────────────────────────────────────────────────────┐ - └──►│ Tether Subnet 192.168.137.x │ - │ ┌──────────┐ ┌──────────┐ │ - │ │ Hermes │ │ Plato │ │ - │ │ Worker │ │ Worker │ │ - │ └──────────┘ └──────────┘ │ - └─────────────────────────────────────────────────────┘ - - Developer Laptops - (Windows/WSL) \ No newline at end of file