378 lines
11 KiB
Markdown
378 lines
11 KiB
Markdown
# 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/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:
|
|
```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 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**:
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
/usr/local/bin/app-deploy viewer
|
|
```
|
|
|
|
#### 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://viewer.appmodel.nl
|
|
|
|
### Manual Deployment
|
|
|
|
If needed:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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](../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-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**:
|
|
```bash
|
|
# 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](../DEPLOY_SERVER_SETUP.md)
|
|
3. Check container logs
|
|
4. Contact the infrastructure team
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-12-02
|
|
**Version**: 1.0.0
|
|
**Maintainer**: Tour |