From 1fb4513f3d2241f93ce6db07bee66d331fc1241b Mon Sep 17 00:00:00 2001 From: michael1986 Date: Tue, 2 Dec 2025 12:54:43 +0100 Subject: [PATCH] wiki --- DEPLOYMENT_GUIDE.md | 192 ++++++++++++++++ DEPLOY_SERVER_SETUP.md | 502 +++++++++++++++++++++++++++++++++++++++++ Home.md | 379 ++++++++++++++++++++++++++++++- Quick-Start.md | 239 ++++++++++++++++++++ 4 files changed, 1311 insertions(+), 1 deletion(-) create mode 100644 DEPLOYMENT_GUIDE.md create mode 100644 DEPLOY_SERVER_SETUP.md diff --git a/DEPLOYMENT_GUIDE.md b/DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000..5284e2b --- /dev/null +++ b/DEPLOYMENT_GUIDE.md @@ -0,0 +1,192 @@ +# Deployment Guide - App Pipeline + +Complete guide for deploying applications using the custom deployment pipeline with Gitea, Docker, and Traefik. + +## 1. Create New Application + +### 1.1 Gitea Repository + +1. Log in to Gitea: https://git.appmodel.nl +2. Create a new repository: + - **Owner**: Tour + - **Name**: `viewer` (or your app name) + +### 1.2 Generate Skeleton on Server + +On the server, run: + +```bash +apps-create viewer static-fe +``` + +This command: +- Sets up `/opt/apps/viewer` (attempts to clone from `git@git.appmodel.nl:Tour/viewer.git`) +- Generates a multi-stage Dockerfile for a Node-based static frontend +- Creates `~/infra/viewer/docker-compose.yml` with: + - Service `viewer` + - Connection to `traefik_net` + - Traefik route: `https://viewer.appmodel.nl` + +## 2. Development & Build + +On your development machine: + +```bash +# Clone the repository +git clone git@git.appmodel.nl:Tour/viewer.git +cd viewer + +# Build your app as usual +npm install +npm run build # output goes to dist/ + +# Commit and push +git add . +git commit -m "First version" +git push +``` + +**Note**: The Dockerfile expects a `dist/` directory containing static files. + +## 3. Deployment Pipeline + +### 3.1 Manual Deploy with `app-deploy` + +On the server, use the generic deploy command: + +```bash +app-deploy viewer +``` + +This command performs: +1. `cd /opt/apps/viewer` +2. `git pull --ff-only` +3. `cd /home/tour/infra/viewer` +4. `docker compose up -d --build viewer` + +Logs are saved to: `/var/log/app-deploy-viewer.log` + +### 3.2 Automatic Deployment via Gitea Hook + +Set up automatic deployment on every push: + +1. In Gitea, go to repository `Tour/viewer` +2. Navigate to **Settings → Git Hooks** +3. Select **post-receive** +4. Add the following script: + +```bash +#!/usr/bin/env bash +/usr/local/bin/app-deploy viewer +``` + +**Result**: Every `git push` to `Tour/viewer` automatically triggers a deployment. + +## 4. Traefik & DNS Configuration + +### Traefik Setup + +Traefik runs in the traefik stack on the same server and manages: +- `git.appmodel.nl` +- `auction.appmodel.nl` +- `aupi.appmodel.nl` +- ... (new apps via labels) + +### Auto-Generated Labels + +The `apps-create` command automatically adds the correct Traefik labels: + +```yaml +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" +``` + +### DNS Configuration + +Add a DNS record pointing to your server's public IP: + +``` +viewer.appmodel.nl → +``` + +Traefik + Let's Encrypt will automatically handle SSL certificate generation. + +## 5. Future Application Types + +The `apps-create` script currently supports: + +- **`static-fe`** – Node build → Nginx → static frontend + +### Planned Types + +Future app types can be added: + +```bash +# Python API +apps-create stats api-py + +# Background worker/crawler +apps-create crawler worker-py +``` + +Each type will have: +- Custom Dockerfile template +- Standard `docker-compose.yml` configuration +- Same deployment pipeline: `app-deploy ` + +## Quick Reference + +### Create and Deploy New App + +```bash +# On server: create skeleton +apps-create viewer static-fe + +# On dev machine: develop and push +git clone git@git.appmodel.nl:Tour/viewer.git +cd viewer +npm install +npm run build +git add . +git commit -m "Initial commit" +git push + +# On server: deploy (or auto-deploys via hook) +app-deploy viewer +``` + +### Existing Infrastructure + +| Service | URL | Description | +|---------|-----|-------------| +| Gitea | https://git.appmodel.nl | Git repository hosting | +| Auction | https://auction.appmodel.nl | Auction frontend | +| Aupi API | https://aupi.appmodel.nl | Auction backend API | +| Traefik | - | Reverse proxy & SSL | + +### Log Locations + +- Deployment logs: `/var/log/app-deploy-.log` +- Docker logs: `docker compose logs -f ` + +### Useful Commands + +```bash +# View deployment logs +tail -f /var/log/app-deploy-viewer.log + +# View container logs +cd ~/infra/viewer +docker compose logs -f viewer + +# Restart service +docker compose restart viewer + +# Rebuild without cache +docker compose up -d --build --no-cache viewer +``` diff --git a/DEPLOY_SERVER_SETUP.md b/DEPLOY_SERVER_SETUP.md new file mode 100644 index 0000000..cac90f3 --- /dev/null +++ b/DEPLOY_SERVER_SETUP.md @@ -0,0 +1,502 @@ +# Deploy Server Setup - Docker Build Pipeline + +Complete guide for setting up and using the Docker-based deployment pipeline on the build server. + +## Architecture Overview + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Deployment Flow │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Dev Machine Gitea Server │ +│ ┌──────────┐ ┌──────┐ ┌─────────┐ │ +│ │ git │ │ Repo │ │ /opt/ │ │ +│ │ commit ├─────push────▶│Tour/ ├──hook────▶ │ apps/ │ │ +│ │ push │ │ │ │ / │ │ +│ └──────────┘ └──────┘ └────┬────┘ │ +│ │ │ +│ git pull │ +│ │ │ +│ ┌───────────▼────────┐ │ +│ │ app-deploy │ │ +│ │ (as user: git) │ │ +│ └───────────┬────────┘ │ +│ │ │ +│ docker compose up -d │ +│ --build │ +│ │ │ +│ ┌───────────▼────────┐ │ +│ │ ~/infra// │ │ +│ │ docker-compose.yml │ │ +│ └───────────┬────────┘ │ +│ │ │ +│ rebuild │ +│ │ │ +│ ┌───────────▼────────┐ │ +│ │ 🐳 Container │ │ +│ │ :latest │ │ +│ └───────────┬────────┘ │ +│ │ │ +│ traefik_net │ +│ │ │ +│ ┌───────────▼────────┐ │ +│ │ 🚦 Traefik │ │ +│ │ Reverse Proxy │ │ +│ └───────────┬────────┘ │ +│ │ │ +│ https://.appmodel.nl│ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +## Build Pipeline Workflow + +### Key Principles + +1. **Source of Truth**: Gitea repository `Tour/` is the authoritative source +2. **Build Server**: Server is only for building and deployment, not development +3. **Automated Deployment**: Git push triggers automatic rebuild and deployment +4. **Isolation**: Each app runs in its own Docker container +5. **Shared Networking**: All apps connect via `traefik_net` for reverse proxy + +### Pipeline Steps + +#### 1. Git Push (Developer) +```bash +git push origin main +``` + +#### 2. Post-Receive Hook (Gitea) +Located in: **Settings → Git Hooks → post-receive** + +```bash +#!/usr/bin/env bash +/usr/local/bin/app-deploy diagram +``` + +#### 3. App Deploy Script (Server) +Runs as Linux user `git`: + +```bash +app-deploy diagram +``` + +This script performs: +1. `cd /opt/apps/diagram` +2. `git pull --ff-only` from `git@git.appmodel.nl:Tour/diagram.git` +3. `cd /home/tour/infra/diagram` +4. `docker compose up -d --build diagram` + +#### 4. Docker Build (Server) +Multi-stage build process: +- **Stage 1**: Build diagrams using Python + Graphviz +- **Stage 2**: Serve with Nginx + +#### 5. Traefik Routing (Server) +Traefik automatically detects the container via labels and publishes: +``` +https://diagram.appmodel.nl +``` + +#### 6. DNS Resolution (AdGuard) +AdGuard resolves `diagram.appmodel.nl` → Build server IP + +Result: Both internal and external clients use the same URL. + +## Server Directory Structure + +``` +/opt/apps/ +└── diagram/ # Git repository (pulled from Gitea) + ├── Dockerfile + ├── docker-compose.yml + ├── requirements.txt + ├── lan_architecture.py + ├── main.py + └── public/ + └── index.html + +/home/tour/infra/ +└── diagram/ + ├── docker-compose.yml # Docker Compose config (may differ from repo) + └── logs/ # Nginx logs (optional) + +/var/log/ +└── app-deploy-diagram.log # Deployment logs +``` + +## Setup Instructions + +### 1. Create Repository in Gitea + +1. Navigate to: https://git.appmodel.nl +2. Create new repository: + - **Owner**: `Tour` + - **Name**: `diagram` + - **Visibility**: Private + +### 2. Initialize Local Repository + +```bash +# On dev machine +git clone git@git.appmodel.nl:Tour/diagram.git +cd diagram + +# Add project files +git add Dockerfile docker-compose.yml requirements.txt *.py public/ +git commit -m "Initial commit: diagram viewer" +git push origin main +``` + +### 3. Setup Server Directories + +```bash +# On server as appropriate user +sudo -u git mkdir -p /opt/apps/diagram +sudo -u git git clone git@git.appmodel.nl:Tour/diagram.git /opt/apps/diagram + +mkdir -p /home/tour/infra/diagram +cp /opt/apps/diagram/docker-compose.yml /home/tour/infra/diagram/ +``` + +### 4. Configure Gitea Post-Receive Hook + +1. Go to: https://git.appmodel.nl/Tour/diagram +2. Navigate to: **Settings → Git Hooks** +3. Select: **post-receive** +4. Add script: + +```bash +#!/usr/bin/env bash +/usr/local/bin/app-deploy diagram +``` + +5. Save and test + +### 5. Configure DNS + +Add DNS record in AdGuard: +``` +diagram.appmodel.nl → +``` + +### 6. Test Deployment + +```bash +# Manual test on server +app-deploy diagram + +# Verify container is running +cd /home/tour/infra/diagram +docker compose ps + +# Check logs +docker compose logs -f diagram + +# Test endpoint +curl -I https://diagram.appmodel.nl +``` + +## Docker Configuration + +### Dockerfile Explained + +```dockerfile +# Stage 1: Build diagrams +FROM python:3.11-slim AS builder +RUN apt-get update && apt-get install -y graphviz +WORKDIR /app +COPY requirements.txt . +RUN pip install -r requirements.txt +COPY *.py . +RUN python lan_architecture.py && python main.py + +# Stage 2: Serve with Nginx +FROM nginx:alpine +COPY --from=builder /app/*.png /usr/share/nginx/html/ +COPY public/ /usr/share/nginx/html/ +EXPOSE 80 +CMD ["nginx", "-g", "daemon off;"] +``` + +**Benefits**: +- Small final image (only Nginx + static files) +- Build tools not included in production image +- Automatic diagram generation on build + +### docker-compose.yml Configuration + +```yaml +version: '3.8' + +services: + diagram: + build: + context: . + dockerfile: Dockerfile + container_name: diagram-viewer + restart: unless-stopped + networks: + - traefik_net + labels: + - "traefik.enable=true" + - "traefik.http.routers.diagram.rule=Host(`diagram.appmodel.nl`)" + - "traefik.http.routers.diagram.entrypoints=websecure" + - "traefik.http.routers.diagram.tls=true" + - "traefik.http.routers.diagram.tls.certresolver=letsencrypt" + - "traefik.http.services.diagram.loadbalancer.server.port=80" + +networks: + traefik_net: + external: true +``` + +**Key Points**: +- Connects to external `traefik_net` network +- Traefik labels configure automatic HTTPS with Let's Encrypt +- Container restarts automatically unless stopped manually + +## Development Workflow + +### Local Development + +```bash +# Edit files locally +vim lan_architecture.py +vim public/index.html + +# Test locally (optional) +python -m venv .venv +source .venv/bin/activate # or .venv\Scripts\activate on Windows +pip install -r requirements.txt +python lan_architecture.py + +# Commit and push +git add . +git commit -m "Update diagram architecture" +git push +``` + +### Automatic Deployment + +After `git push`, the server automatically: +1. Receives post-receive hook trigger +2. Pulls latest code +3. Rebuilds Docker image +4. Restarts container +5. Updates live site + +**Timeline**: Usually completes in 30-60 seconds. + +### Manual Deployment + +If needed, manually trigger deployment: + +```bash +# On server +app-deploy diagram + +# Or manually +cd /opt/apps/diagram +git pull +cd /home/tour/infra/diagram +docker compose up -d --build diagram +``` + +## Monitoring & Troubleshooting + +### 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 + +# Nginx access logs (if volume mounted) +tail -f /home/tour/infra/diagram/logs/access.log +``` + +### Check Container Status + +```bash +cd /home/tour/infra/diagram + +# List running containers +docker compose ps + +# Inspect container +docker compose exec diagram sh + +# Test nginx config +docker compose exec diagram nginx -t +``` + +### Debug Build Issues + +```bash +# Rebuild without cache +docker compose build --no-cache diagram + +# View build output +docker compose up --build diagram + +# Check image layers +docker image history diagram-viewer +``` + +### Common Issues + +#### 1. Build Fails - Missing Dependencies + +**Symptom**: Build fails at pip install step + +**Solution**: Verify `requirements.txt` is correct +```bash +cd /opt/apps/diagram +cat requirements.txt +``` + +#### 2. Nginx 404 Error + +**Symptom**: Container runs but shows 404 + +**Solution**: Check if files were copied correctly +```bash +docker compose exec diagram ls -la /usr/share/nginx/html/ +``` + +#### 3. Traefik Not Routing + +**Symptom**: Container runs but domain not accessible + +**Solution**: +- Verify container is on `traefik_net`: `docker network inspect traefik_net` +- Check Traefik labels: `docker inspect diagram-viewer | grep traefik` +- Verify DNS: `nslookup diagram.appmodel.nl` + +#### 4. Git Pull Fails + +**Symptom**: app-deploy fails at git pull + +**Solution**: +- Check SSH keys for git user: `sudo -u git ssh -T git@git.appmodel.nl` +- Verify remote: `cd /opt/apps/diagram && git remote -v` + +## Security Considerations + +### User Permissions + +- **git user**: Owns `/opt/apps/*` directories, runs app-deploy +- **tour user**: Owns `/home/tour/infra/*`, runs Docker Compose +- Principle: Separate concerns between git operations and container management + +### Network Isolation + +- Containers only exposed via Traefik +- No direct port exposure to host +- `traefik_net` provides isolation between services + +### Secrets Management + +For apps requiring secrets: + +```yaml +# In docker-compose.yml +services: + diagram: + environment: + - SECRET_KEY=${SECRET_KEY} + env_file: + - .env # Not committed to git +``` + +Create `.env` file on server: +```bash +echo "SECRET_KEY=your-secret-here" > /home/tour/infra/diagram/.env +chmod 600 /home/tour/infra/diagram/.env +``` + +## Scaling & Future Improvements + +### Multi-Container Apps + +For apps with multiple services: + +```yaml +services: + frontend: + build: ./frontend + labels: + - "traefik.enable=true" + - "traefik.http.routers.app-fe.rule=Host(`app.appmodel.nl`)" + + backend: + build: ./backend + labels: + - "traefik.enable=true" + - "traefik.http.routers.app-be.rule=Host(`api.app.appmodel.nl`)" + + database: + image: postgres:15 + volumes: + - pgdata:/var/lib/postgresql/data + +volumes: + pgdata: +``` + +### CI/CD Integration + +Consider adding: +- Automated tests before deployment +- Rollback mechanism +- Blue-green deployments +- Health checks before switching traffic + +### Monitoring + +Add monitoring stack: +- Prometheus for metrics +- Grafana for dashboards +- Loki for log aggregation +- Alertmanager for notifications + +## Quick Reference + +### Key Paths + +| Path | Purpose | +|------|---------| +| `/opt/apps//` | Git repository checkout | +| `/home/tour/infra//` | Docker Compose directory | +| `/var/log/app-deploy-.log` | Deployment logs | + +### Key Commands + +| Command | Purpose | +|---------|---------| +| `app-deploy ` | Deploy/redeploy application | +| `docker compose ps` | List running containers | +| `docker compose logs -f ` | Follow container logs | +| `docker compose restart ` | Restart service | +| `docker compose build --no-cache` | Force rebuild | + +### URLs + +| Service | URL | +|---------|-----| +| Gitea | https://git.appmodel.nl | +| Diagram Viewer | https://diagram.appmodel.nl | +| Traefik Dashboard | https://traefik.appmodel.nl/dashboard/ | + +## Support + +For issues or questions: +1. Check deployment logs: `/var/log/app-deploy-.log` +2. Check container logs: `docker compose logs -f` +3. Review Gitea webhook history in repository settings +4. Test manual deployment: `app-deploy ` diff --git a/Home.md b/Home.md index 1eb345d..82e0cf6 100644 --- a/Home.md +++ b/Home.md @@ -1 +1,378 @@ -Welkom op de wiki. \ No newline at end of file +# 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 \ No newline at end of file diff --git a/Quick-Start.md b/Quick-Start.md index e69de29..9e24dae 100644 --- a/Quick-Start.md +++ b/Quick-Start.md @@ -0,0 +1,239 @@ +# 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. \ No newline at end of file