diff --git a/WIKI_INTEGRATION.md b/WIKI_INTEGRATION.md new file mode 100644 index 0000000..9f66c15 --- /dev/null +++ b/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: +``` +.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 new file mode 100644 index 0000000..ff2408d --- /dev/null +++ b/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 ` + +## 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 new file mode 100644 index 0000000..51bff8c --- /dev/null +++ b/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 + +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