From 7fe32f17155d3d1fd600a85898fc85d9a5f77997 Mon Sep 17 00:00:00 2001 From: michael1986 Date: Tue, 2 Dec 2025 12:45:56 +0100 Subject: [PATCH] Initial wiki content --- Home.md | 378 ------------------------------------------------- Quick-Start.md | 239 ------------------------------- 2 files changed, 617 deletions(-) diff --git a/Home.md b/Home.md index 0b79f88..e69de29 100644 --- a/Home.md +++ b/Home.md @@ -1,378 +0,0 @@ -# Diagram Viewer Wiki - -Welcome to the **Diagram Viewer** project documentation. - -This project provides a static web interface for viewing and managing network architecture diagrams generated with Python's `diagrams` library. - -## 📚 Contents - -- [Getting Started](#getting-started) -- [Development Guide](#development-guide) -- [Deployment Guide](#deployment-guide) -- [Architecture Overview](#architecture-overview) - ---- - -## Getting Started - -### Prerequisites - -- Python 3.8+ -- Graphviz -- Docker (for deployment) - -### Quick Start - -```bash -# Clone repository -git clone git@git.appmodel.nl:Tour/diagram.git -cd diagram - -# Create virtual environment -python -m venv .venv -source .venv/bin/activate # Windows: .venv\Scripts\activate - -# Install dependencies -pip install -r requirements.txt - -# Generate diagrams -python lan_architecture.py -python main.py -``` - ---- - -## Development Guide - -### Project Structure - -``` -diagram/ -├── Dockerfile # Multi-stage build for production -├── docker-compose.yml # Docker Compose configuration -├── requirements.txt # Python dependencies -├── lan_architecture.py # LAN architecture diagram generator -├── main.py # Main diagram generator -├── public/ -│ └── index.html # Live Mermaid diagram editor -└── wiki/ # Documentation (this wiki) -``` - -### Adding New Diagrams - -1. Create a new Python file (e.g., `network_diagram.py`) -2. Import required components from `diagrams` library -3. Define your architecture using context managers -4. Run the script to generate PNG output - -Example: -```python -from diagrams import Diagram, Cluster -from diagrams.onprem.network import Router -from diagrams.generic.device import Mobile - -with Diagram("My Network", show=False, filename="my_network"): - router = Router("Gateway") - device = Mobile("Phone") - device >> router -``` - -### Testing Locally - -```bash -# Generate diagrams -python lan_architecture.py - -# View output -ls -la *.png - -# Test with local web server -python -m http.server 8000 --directory public/ -# Open: http://localhost:8000 -``` - -### Available Icons - -The `diagrams` library provides icons from multiple providers: -- **OnPrem**: Network, compute, storage, etc. -- **Cloud**: AWS, Azure, GCP services -- **Generic**: Network devices, blank nodes -- **Custom**: Use your own images - -See: [Diagrams Documentation](https://diagrams.mingrammer.com/docs/nodes/overview) - ---- - -## Deployment Guide - -### Overview - -The project uses a fully automated Docker-based deployment pipeline: - -1. **Develop** on local machine -2. **Commit & Push** to Gitea -3. **Auto-Deploy** via post-receive hook -4. **Build** multi-stage Docker image -5. **Serve** via Traefik reverse proxy - -### Deployment Steps - -#### 1. Initial Setup - -```bash -# On server: Create app structure -apps-create diagram static-fe - -# This creates: -# - /opt/apps/diagram (git repository) -# - /home/tour/infra/diagram/docker-compose.yml -``` - -#### 2. Configure Gitea Hook - -In repository **Settings → Git Hooks → post-receive**: - -```bash -#!/usr/bin/env bash -/usr/local/bin/app-deploy diagram -``` - -#### 3. Deploy - -Simply push to Gitea: - -```bash -git push origin main -``` - -The server automatically: -- Pulls latest code -- Rebuilds Docker image -- Restarts container -- Updates live site at https://diagram.appmodel.nl - -### Manual Deployment - -If needed: - -```bash -# On server -app-deploy diagram - -# Or step-by-step -cd /opt/apps/diagram -git pull -cd /home/tour/infra/diagram -docker compose up -d --build diagram -``` - -### Monitoring - -```bash -# View deployment logs -tail -f /var/log/app-deploy-diagram.log - -# View container logs -cd /home/tour/infra/diagram -docker compose logs -f diagram - -# Check container status -docker compose ps -``` - ---- - -## Architecture Overview - -### Infrastructure - -``` -┌─────────────────────────────────────────────┐ -│ Production Architecture │ -├─────────────────────────────────────────────┤ -│ │ -│ ┌──────────────┐ │ -│ │ Gitea │ (Source of Truth) │ -│ │ Tour/diagram │ │ -│ └──────┬───────┘ │ -│ │ git push │ -│ ↓ │ -│ ┌──────────────┐ │ -│ │ Post-Receive │ (Auto-trigger) │ -│ │ Hook │ │ -│ └──────┬───────┘ │ -│ │ app-deploy diagram │ -│ ↓ │ -│ ┌──────────────────────┐ │ -│ │ /opt/apps/diagram/ │ │ -│ │ (Git Repository) │ │ -│ └──────┬───────────────┘ │ -│ │ git pull │ -│ ↓ │ -│ ┌──────────────────────┐ │ -│ │ Docker Build Process │ │ -│ │ ┌─────────────────┐ │ │ -│ │ │ Stage 1: Build │ │ │ -│ │ │ - Python │ │ │ -│ │ │ - Graphviz │ │ │ -│ │ │ - Generate PNGs │ │ │ -│ │ └─────────────────┘ │ │ -│ │ ┌─────────────────┐ │ │ -│ │ │ Stage 2: Serve │ │ │ -│ │ │ - Nginx │ │ │ -│ │ │ - Static files │ │ │ -│ │ └─────────────────┘ │ │ -│ └──────┬───────────────┘ │ -│ │ container starts │ -│ ↓ │ -│ ┌──────────────────────┐ │ -│ │ diagram-viewer │ │ -│ │ Container :80 │ │ -│ └──────┬───────────────┘ │ -│ │ traefik_net │ -│ ↓ │ -│ ┌──────────────────────┐ │ -│ │ Traefik │ │ -│ │ Reverse Proxy │ │ -│ │ + Let's Encrypt │ │ -│ └──────┬───────────────┘ │ -│ │ HTTPS │ -│ ↓ │ -│ diagram.appmodel.nl │ -│ │ -└─────────────────────────────────────────────┘ -``` - -### Network Topology - -The diagram viewer documents our home lab infrastructure: - -- **LAN 192.168.1.0/24**: Main network - - Core server (192.168.1.159): Traefik, Gitea, Dokku, Auction stack, MI50/Ollama - - DNS server (192.168.1.163): AdGuard, Artifactory, CI runner - - Home Assistant (192.168.1.193) - - Atlas worker (192.168.1.100) - - IoT devices - -- **Tether 192.168.137.0/24**: Isolated subnet - - Hermes worker (192.168.137.239) - - Plato worker (192.168.137.163) - -### Services - -| Service | URL | Description | -|---------|-----|-------------| -| Diagram Viewer | https://diagram.appmodel.nl | This application | -| Gitea | https://git.appmodel.nl | Git hosting | -| Auction Frontend | https://auction.appmodel.nl | Auction platform | -| Aupi API | https://aupi.appmodel.nl | Backend API | -| Dokku | https://dokku.lan | PaaS platform | - ---- - -## Additional Resources - -### Related Documentation - -- [DEPLOY_SERVER_SETUP.md](../DEPLOY_SERVER_SETUP.md) - Detailed deployment guide -- [DEPLOYMENT_GUIDE.md](../DEPLOYMENT_GUIDE.md) - General deployment pipeline -- [README.md](../README.md) - Project overview - -### External Links - -- [Diagrams Library](https://diagrams.mingrammer.com/) -- [Graphviz](https://graphviz.org/) -- [Mermaid.js](https://mermaid.js.org/) (used in live editor) -- [Traefik Documentation](https://doc.traefik.io/traefik/) -- [Docker Compose](https://docs.docker.com/compose/) - -### Contributing - -To contribute to this project: - -1. Create a feature branch -2. Make your changes -3. Test locally -4. Submit a pull request in Gitea -5. Wait for automatic deployment after merge - ---- - -## Troubleshooting - -### Common Issues - -#### Diagrams Not Generating - -**Problem**: Python script fails to generate PNG files - -**Solution**: -```bash -# Check Graphviz installation -dot -V - -# Reinstall if needed -# macOS: brew install graphviz -# Ubuntu: sudo apt-get install graphviz -# Windows: choco install graphviz - -# Verify Python dependencies -pip list | grep diagrams -pip install --upgrade diagrams -``` - -#### Container Build Fails - -**Problem**: Docker build fails during deployment - -**Solution**: -```bash -# Check deployment logs -tail -f /var/log/app-deploy-diagram.log - -# Rebuild manually with verbose output -cd /home/tour/infra/diagram -docker compose build --no-cache --progress=plain diagram -``` - -#### Site Not Accessible - -**Problem**: Container runs but site not reachable - -**Solution**: -1. Check DNS: `nslookup diagram.appmodel.nl` -2. Verify Traefik labels: `docker inspect diagram-viewer | grep traefik` -3. Check Traefik logs: `docker logs traefik` -4. Test container directly: `curl http://localhost:PORT` - -#### Changes Not Reflected - -**Problem**: Pushed changes but site unchanged - -**Solution**: -```bash -# Force rebuild on server -cd /home/tour/infra/diagram -docker compose down -docker compose up -d --build --force-recreate diagram - -# Clear browser cache -# Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (macOS) -``` - ---- - -## Contact & Support - -For issues, questions, or suggestions: - -1. Check this wiki -2. Review [DEPLOY_SERVER_SETUP.md](../DEPLOY_SERVER_SETUP.md) -3. Check container logs -4. Contact the infrastructure team - ---- - -**Last Updated**: 2025-12-02 -**Version**: 1.0.0 -**Maintainer**: Tour diff --git a/Quick-Start.md b/Quick-Start.md index 2478ebd..e69de29 100644 --- a/Quick-Start.md +++ b/Quick-Start.md @@ -1,239 +0,0 @@ -# Quick Start Guide - -Get up and running with the Diagram Viewer in minutes. - -## For Developers - -### 1. Clone Repository - -```bash -git clone git@git.appmodel.nl:Tour/diagram.git -cd diagram -``` - -### 2. Setup Environment - -```bash -# Create virtual environment -python -m venv .venv - -# Activate (choose your platform) -source .venv/bin/activate # macOS/Linux -.venv\Scripts\activate # Windows CMD -source .venv/Scripts/activate # Windows Git Bash -``` - -### 3. Install Dependencies - -```bash -pip install -r requirements.txt -``` - -### 4. Generate Diagrams - -```bash -# Generate LAN architecture diagram -python lan_architecture.py - -# Generate main diagram -python main.py - -# View generated files -ls -la *.png -``` - -### 5. Test Locally - -```bash -# Start local web server -python -m http.server 8000 --directory public/ - -# Open browser -# Navigate to: http://localhost:8000 -``` - -### 6. Make Changes & Deploy - -```bash -# Edit diagram code -vim lan_architecture.py - -# Commit changes -git add . -git commit -m "Update network diagram" - -# Push to deploy (auto-deploys to production) -git push origin main -``` - ---- - -## For Operators - -### View Live Site - -Simply navigate to: -``` -https://diagram.appmodel.nl -``` - -### Manual Deployment - -On the server: - -```bash -# Trigger deployment -app-deploy diagram - -# View logs -tail -f /var/log/app-deploy-diagram.log - -# Check status -cd /home/tour/infra/diagram -docker compose ps -``` - -### View Logs - -```bash -# Deployment logs -tail -f /var/log/app-deploy-diagram.log - -# Container logs -cd /home/tour/infra/diagram -docker compose logs -f diagram - -# Last 100 lines -docker compose logs --tail=100 diagram -``` - -### Restart Service - -```bash -cd /home/tour/infra/diagram - -# Restart container -docker compose restart diagram - -# Full restart (rebuild) -docker compose down -docker compose up -d --build diagram -``` - ---- - -## Common Tasks - -### Add New Diagram - -1. Create new Python file: -```python -# my_diagram.py -from diagrams import Diagram -from diagrams.onprem.network import Router - -with Diagram("My Network", show=False, filename="my_network"): - Router("Gateway") -``` - -2. Update Dockerfile if needed (add to RUN command): -```dockerfile -RUN python lan_architecture.py && \ - python main.py && \ - python my_diagram.py -``` - -3. Commit and push: -```bash -git add my_diagram.py Dockerfile -git commit -m "Add my network diagram" -git push -``` - -### Update Frontend - -1. Edit HTML: -```bash -vim public/index.html -``` - -2. Test locally: -```bash -python -m http.server 8000 --directory public/ -``` - -3. Deploy: -```bash -git add public/index.html -git commit -m "Update frontend" -git push -``` - -### Check Container Health - -```bash -# Container status -docker compose ps - -# Health check -docker inspect diagram-viewer | grep -A 10 Health - -# Test endpoint -curl -I https://diagram.appmodel.nl -``` - ---- - -## Troubleshooting - -### Build Fails - -```bash -# Check logs -tail -f /var/log/app-deploy-diagram.log - -# Rebuild with verbose output -cd /home/tour/infra/diagram -docker compose build --no-cache --progress=plain diagram -``` - -### Site Not Loading - -```bash -# Check container -docker compose ps - -# Check Traefik routing -docker logs traefik | grep diagram - -# Test DNS -nslookup diagram.appmodel.nl - -# Test directly -curl http://localhost:PORT -``` - -### Changes Not Visible - -```bash -# Force rebuild -cd /home/tour/infra/diagram -docker compose up -d --build --force-recreate diagram - -# Clear browser cache -# Ctrl+Shift+R (Windows/Linux) -# Cmd+Shift+R (macOS) -``` - ---- - -## Next Steps - -- Read the [Home](Home.md) page for comprehensive documentation -- Review [DEPLOY_SERVER_SETUP.md](../DEPLOY_SERVER_SETUP.md) for deployment details -- Check [Diagrams Library docs](https://diagrams.mingrammer.com/) for icon options -- Explore the [Mermaid editor](https://diagram.appmodel.nl) for live diagram editing - ---- - -**Need Help?** Check the [Troubleshooting](Home.md#troubleshooting) section or review deployment logs.