wiki

WIKI_INTEGRATION.md

@@ -0,0 +1,361 @@
+# 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:
+```
+<repository>.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
+<!-- Link to another wiki page -->
+[Quick Start Guide](Quick-Start)
+
+<!-- Link with custom text -->
+[Get Started](Quick-Start)
+
+<!-- Link to main repository -->
+[View Code](../)
+
+<!-- Link to specific file -->
+[Dockerfile](../src/master/Dockerfile)
+
+<!-- External link -->
+[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

build-pipeline.md

@@ -0,0 +1,31 @@
+# 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 <app>`
+
+## Pipeline in één diagram
+
+```mermaid
+flowchart LR
+  Dev[💻 Dev machine\nVS Code / Git] -->|git push| Gitea[📚 Gitea\nTour/<app>]
+
+  subgraph Server[🏠 Home lab server\n192.168.1.159]
+    Gitea --> Hook[🔔 post-receive hook\n/app-deploy <app>]
+
+    Hook --> Deploy[⚙️ app-deploy <app>\n/git pull + docker compose up -d --build <app>]
+
+    subgraph Docker[🐳 Docker / traefik_net]
+      AppC[🧱 App container\n<app>.appmodel.nl]
+      Traefik[🚦 Traefik\nReverse Proxy]
+    end
+  end
+
+  Deploy --> AppC
+  Traefik --> AppC
+  Client[🌐 Browser / API client] -->|https://<app>.appmodel.nl| Traefik

readme-pipe.md

@@ -0,0 +1,141 @@
+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 <app>
+
+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 <naam>) identiek.
+
+Je kunt nu:
+
+apps-create viewer static-fe
+app-deploy viewer