viewer/wiki/Quick-Start.md

Quick Start Guide

Get up and running with the Diagram Viewer in minutes.

For Developers

1. Clone Repository

git clone git@git.appmodel.nl:Tour/viewer.git
cd viewer

2. Setup Environment

# 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

pip install -r requirements.txt

4. Generate Diagrams

# Generate LAN architecture diagram
python lan_architecture.py

# Generate main diagram
python main.py

# View generated files
ls -la *.png

5. Test Locally

# Start local web server
python -m http.server 8000 --directory public/

# Open browser
# Navigate to: http://localhost:8000

6. Make Changes & Deploy

# 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://viewer.appmodel.nl

Manual Deployment

On the server:

# Trigger deployment
app-deploy viewer

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

# Check status
cd /home/tour/infra/viewer
docker compose ps

View Logs

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

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

# Last 100 lines
docker compose logs --tail=100 viewer

Restart Service

cd /home/tour/infra/viewer

# Restart container
docker compose restart viewer

# Full restart (rebuild)
docker compose down
docker compose up -d --build viewer

---

Common Tasks

Add New Diagram

1. Create new Python file:

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

RUN python lan_architecture.py && \
    python main.py && \
    python my_diagram.py

3. Commit and push:

git add my_diagram.py Dockerfile
git commit -m "Add my network diagram"
git push

Update Frontend

1. Edit HTML:

vim public/index.html

2. Test locally:

python -m http.server 8000 --directory public/

3. Deploy:

git add public/index.html
git commit -m "Update frontend"
git push

Check Container Health

# Container status
docker compose ps

# Health check
docker inspect viewer | grep -A 10 Health

# Test endpoint
curl -I https://viewer.appmodel.nl

---

Troubleshooting

Build Fails

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

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

Site Not Loading

# Check container
docker compose ps

# Check Traefik routing
docker logs traefik | grep viewer

# Test DNS
nslookup viewer.appmodel.nl

# Test directly
curl http://localhost:PORT

Changes Not Visible

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

# Clear browser cache
# Ctrl+Shift+R (Windows/Linux)
# Cmd+Shift+R (macOS)

---

Next Steps

• Read the Home page for comprehensive documentation
• Review DEPLOY_SERVER_SETUP.md for deployment details
• Check Diagrams Library docs for icon options
• Explore the Mermaid editor for live diagram editing

---

Need Help? Check the Troubleshooting section or review deployment logs.