viewer/wiki/Home.md

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
• Development Guide
• Deployment Guide
• Architecture Overview

---

Getting Started

Prerequisites

• Python 3.8+
• Graphviz
• Docker (for deployment)

Quick Start

# Clone repository
git clone git@git.appmodel.nl:Tour/viewer.git
cd viewer

# 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

viewer/
├── 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:

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

# 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

---

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

# On server: Create app structure
apps-create viewer static-fe

# This creates:
# - /opt/apps/viewer (git repository)
# - /home/tour/infra/viewer/docker-compose.yml

2. Configure Gitea Hook

In repository Settings → Git Hooks → post-receive:

#!/usr/bin/env bash
/usr/local/bin/app-deploy viewer

3. Deploy

Simply push to Gitea:

git push origin main

The server automatically:

• Pulls latest code
• Rebuilds Docker image
• Restarts container
• Updates live site at https://viewer.appmodel.nl

Manual Deployment

If needed:

# On server
app-deploy viewer

# Or step-by-step
cd /opt/apps/viewer
git pull
cd /home/tour/infra/viewer
docker compose up -d --build viewer

Monitoring

# View deployment logs
tail -f /var/log/app-deploy-viewer.log

# View container logs
cd /home/tour/infra/viewer
docker compose logs -f viewer

# Check container status
docker compose ps

---

Architecture Overview

Infrastructure

┌─────────────────────────────────────────────┐
│           Production Architecture           │
├─────────────────────────────────────────────┤
│                                             │
│  ┌──────────────┐                          │
│  │   Gitea      │  (Source of Truth)        │
│  │ Tour/viewer │                          │
│  └──────┬───────┘                          │
│         │ git push                          │
│         ↓                                   │
│  ┌──────────────┐                          │
│  │ Post-Receive │  (Auto-trigger)           │
│  │     Hook     │                          │
│  └──────┬───────┘                          │
│         │ app-deploy viewer                │
│         ↓                                   │
│  ┌──────────────────────┐                  │
│  │  /opt/apps/viewer/  │                  │
│  │   (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                             │
│         ↓                                   │
│  viewer.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://viewer.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 - Detailed deployment guide
• DEPLOYMENT_GUIDE.md - General deployment pipeline
• README.md - Project overview

External Links

• Diagrams Library
• Graphviz
• Mermaid.js (used in live editor)
• Traefik Documentation
• Docker 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:

# 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:

# Check deployment logs
tail -f /var/log/app-deploy-viewer.log

# Rebuild manually with verbose output
cd /home/tour/infra/viewer
docker compose build --no-cache --progress=plain viewer

Site Not Accessible

Problem: Container runs but site not reachable

Solution:

1. Check DNS: nslookup viewer.appmodel.nl
2. Verify Traefik labels: docker inspect viewer-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:

# Force rebuild on server
cd /home/tour/infra/viewer
docker compose down
docker compose up -d --build --force-recreate viewer

# 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
3. Check container logs
4. Contact the infrastructure team

---

Last Updated: 2025-12-02 Version: 1.0.0 Maintainer: Tour