Tour/viewer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

wiki

michael1986
2025-12-02 13:12:29 +01:00
parent 1fb4513f3d
commit 4b2c9095e7
3 changed files with 533 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

361
WIKI_INTEGRATION.md Normal file

@@ -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

31
build-pipeline.md Normal file

@@ -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

141
readme-pipe.md Normal file

@@ -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