Merge pull request #153 from mayanayza/feat/readme-updates

Feat/readme updates
2025-12-10 08:24:08 -06:00 · 2025-11-18 10:06:43 -05:00
parent 03f3b7adc8 b0af6537d1
commit 7502576fc2
12 changed files with 1952 additions and 846 deletions
@@ -0,0 +1,227 @@
+# Architecture Overview
+
+Technical overview of NetVisor's system design, components, and technology stack.
+
+## Table of Contents
+
+- [Components](#components)
+- [Technology Stack](#technology-stack)
+- [Data Flow](#data-flow)
+- [Discovery Pipeline](#discovery-pipeline)
+- [Database Schema](#database-schema)
+- [Deployment Models](#deployment-models)
+
+## Components
+
+### Server
+
+**Purpose**: Central hub for data storage, API, and web UI serving
+
+**Responsibilities**:
+- Store network discovery data in PostgreSQL
+- Serve REST API for daemons and UI
+- Generate topology visualizations
+- Manage user authentication and sessions
+- Orchestrate scheduled discoveries
+- Handle organization and user management
+- Provide real-time updates via Server-Sent Events
+
+**Implementation**:
+- Language: Rust
+- Framework: Axum (async web framework)
+- Database: PostgreSQL 17 with sqlx
+- Authentication: tower-sessions + OIDC (openidconnect crate)
+- Frontend bundling: Integrated Svelte build in Docker image
+
+**Runs as**: Docker container (recommended) or standalone binary
+
+### Daemon
+
+**Purpose**: Distributed discovery agent that scans networks and reports findings
+
+**Responsibilities**:
+- Scan IPv4 addresses on configured subnets
+- Detect open TCP ports
+- Identify services via pattern matching
+- Connect to Docker socket for container discovery
+- Report host interfaces and capabilities
+- Send heartbeats to maintain connection
+- Execute scheduled discovery tasks
+
+**Implementation**:
+- Language: Rust
+- Network scanning: Custom async TCP scanner with tokio
+- Docker API: bollard crate for Docker socket communication
+- Service detection: Pattern matching engine with 150+ definitions
+- Configuration: JSON file + environment variables + CLI args
+
+**Runs as**: Docker container (Linux only) or standalone binary (all platforms)
+
+### UI
+
+**Purpose**: Web-based interface for viewing and managing network data
+
+**Responsibilities**:
+- Display interactive topology diagrams
+- Provide CRUD interfaces for all entities
+- Monitor discovery sessions in real-time
+- Manage users and organizations
+- Configure discovery schedules
+- Export topology visualizations
+
+**Implementation**:
+- Framework: Svelte 5 + SvelteKit
+- State management: Svelte stores with derived reactivity
+- Visualization: @xyflow/svelte for topology rendering
+- Forms: svelte-forms with custom validation
+- Styling: Tailwind CSS
+- Real-time: Native EventSource for SSE
+
+**Runs as**: Static files served by the server (bundled in Docker image)
+
+## Data Flows
+
+### Discovery Flow (Push)
+
+```
+1. User triggers discovery (manual or scheduled)
+   │
+   ▼
+2. Server creates discovery session
+   │
+   ▼
+3. Server sends discovery request to daemon via HTTP
+   │
+   ▼
+4. Daemon executes scan:
+   ├─ Network Scan: Scans IP range, detects ports/services
+   ├─ Docker Scan: Queries Docker socket for containers
+   └─ Self-Report: Reports own capabilities
+   │
+   ▼
+5. Daemon sends discovered entities to server (batched)
+   │
+   ▼
+6. Server processes and stores entities:
+   ├─ Creates/updates hosts
+   ├─ Creates/updates interfaces
+   ├─ Creates/updates services
+   ├─ Associates with subnets
+   └─ Logs discovery metadata
+   │
+   ▼
+7. Server broadcasts progress updates via SSE
+   │
+   ▼
+8. UI receives real-time updates and refreshes display
+   │
+   ▼
+9. Discovery completes, final status recorded
+```
+
+### Discovery Flow (Pull)
+
+```
+1. User triggers discovery (manual or scheduled)
+   │
+   ▼
+2. Server creates discovery session
+   │
+   ▼
+3. Daemon polls server for work, and retrieves the discovery session that was just created
+   │
+   ▼
+4 - 9: Same as Discovery Flow (Push)
+```
+
+## Discovery Pipeline
+
+### Network Scan Discovery
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    Initialization                         │
+│  1. Determine target subnets                              │
+│  2. Calculate total IP count                              │
+│  3. Establish concurrent scan limit                       │
+└───────────────────┬──────────────────────────────────────┘
+                    ▼
+┌──────────────────────────────────────────────────────────┐
+│                 Per-IP Scan (Parallel)                    │
+│  1. TCP port scan (common + custom ports)                │
+│  2. HTTP endpoint probing                                 │
+│  3. Collect responses and headers                         │
+└───────────────────┬──────────────────────────────────────┘
+                    ▼
+┌──────────────────────────────────────────────────────────┐
+│                Service Pattern Matching                   │
+│  1. Match port numbers                                    │
+│  2. Match HTTP endpoints                                  │
+│  3. Check headers and content                             │
+│  4. Apply MAC vendor patterns                             │
+│  5. Assign confidence score                               │
+└───────────────────┬──────────────────────────────────────┘
+                    ▼
+┌──────────────────────────────────────────────────────────┐
+│                   Host Assembly                           │
+│  1. Perform reverse DNS lookup                            │
+│  2. Determine hostname (DNS > service > IP)               │
+│  3. Group services by interface                           │
+│  4. Associate with subnet                                 │
+└───────────────────┬──────────────────────────────────────┘
+                    ▼
+┌──────────────────────────────────────────────────────────┐
+│                 Report to Server                          │
+│  1. Send discovered host + interfaces + services          │
+│  2. Server stores in database                             │
+│  3. Server broadcasts update via SSE                      │
+└──────────────────────────────────────────────────────────┘
+```
+
+### Docker Discovery
+
+```
+┌──────────────────────────────────────────────────────────┐
+│               Connect to Docker Socket                    │
+│  - Verify socket accessibility                            │
+│  - Authenticate (if required)                             │
+└───────────────────┬──────────────────────────────────────┘
+                    ▼
+┌──────────────────────────────────────────────────────────┐
+│              List Running Containers                      │
+│  - Get container IDs, names, labels                       │
+│  - Extract port mappings                                  │
+│  - Identify networks                                      │
+└───────────────────┬──────────────────────────────────────┘
+                    ▼
+┌──────────────────────────────────────────────────────────┐
+│          Inspect Docker Networks                          │
+│  - Enumerate bridge networks                              │
+│  - Map containers to network subnets                      │
+│  - Extract gateway IPs                                    │
+└───────────────────┬──────────────────────────────────────┘
+                    ▼
+┌──────────────────────────────────────────────────────────┐
+│            Match Services to Containers                   │
+│  - Use port mappings to identify services                 │
+│  - Check container labels for hints                       │
+│  - Apply same pattern matching as network scan            │
+└───────────────────┬──────────────────────────────────────┘
+                    ▼
+┌──────────────────────────────────────────────────────────┐
+│         Create Container-Host Relationships               │
+│  - Link containers to Docker host                         │
+│  - Set virtualization metadata                            │
+│  - Create subnet for Docker bridge                        │
+└───────────────────┬──────────────────────────────────────┘
+                    ▼
+┌──────────────────────────────────────────────────────────┐
+│                 Report to Server                          │
+│  - Send containers as hosts                               │
+│  - Send Docker subnets                                    │
+│  - Link to host via virtualization field                  │
+└──────────────────────────────────────────────────────────┘
+```
+---
+
+**For implementation details**, see the [source code](https://github.com/mayanayza/netvisor).
@@ -0,0 +1,352 @@
+# Configuration Reference
+
+Complete reference for configuring NetVisor server and daemon components.
+
+## Table of Contents
+
+- [Configuration Priority](#configuration-priority)
+- [Daemon Configuration](#daemon-configuration)
+- [Server Configuration](#server-configuration)
+- [UI Configuration](#ui-configuration)
+- [OIDC Setup](#oidc-setup)
+- [Session Security](#session-security)
+- [Environment Files](#environment-files)
+
+## Configuration Priority
+
+NetVisor uses the following priority order (highest to lowest):
+
+1. **Command-line arguments** (highest priority)
+2. **Environment variables**
+3. **Configuration file** (daemon only)
+4. **Default values** (lowest priority)
+
+Later sources override earlier ones. For example, an environment variable overrides the config file but is overridden by a command-line argument.
+
+## Daemon Configuration
+
+### Configuration Methods
+
+**Command-line arguments**:
+```bash
+netvisor-daemon --server-url http://192.168.1.100:60072 --api-key YOUR_KEY
+```
+
+**Environment variables**:
+```bash
+export NETVISOR_SERVER_URL=http://192.168.1.100:60072
+export NETVISOR_DAEMON_API_KEY=YOUR_KEY
+netvisor-daemon
+```
+
+**Docker environment**:
+```yaml
+environment:
+  - NETVISOR_SERVER_URL=http://192.168.1.100:60072
+  - NETVISOR_DAEMON_API_KEY=YOUR_KEY
+```
+
+**Configuration file**:
+
+The daemon automatically creates a config file at:
+- **Linux**: `~/.config/netvisor/daemon/config.json`
+- **macOS**: `~/Library/Application Support/com.netvisor.daemon/config.json`
+- **Windows**: `%APPDATA%\netvisor\daemon\config.json`
+
+The config file stores runtime state (daemon ID, host ID) alongside your settings. Command-line and environment variables take priority over the file.
+
+### Parameter Reference
+
+| Parameter | CLI Flag | Environment Variable | Config File Key | Default | Description |
+|-----------|----------|---------------------|-----------------|---------|-------------|
+| **Server URL** | `--server-url` | `NETVISOR_SERVER_URL` | `server_url` | `http://127.0.0.1:60072` | URL where the daemon can reach the server |
+| **API Key** | `--api-key` | `NETVISOR_DAEMON_API_KEY` | `daemon_api_key` | *Required* | Authentication key for daemon (generated via UI) |
+| **Mode** | `--mode` | `NETVISOR_MODE` | `docker_proxy` | Push | Whether server will push work to daemon or daemon should poll for work from server |
+| **Network ID** | `--network-id` | `NETVISOR_NETWORK_ID` | `network_id` | *Auto-assigned* | UUID of the network to scan |
+| **Daemon Port** | `--daemon-port` or `-p` | `NETVISOR_DAEMON_PORT` | `daemon_port` | `60073` | Port for daemon to listen on |
+| **Bind Address** | `--bind-address` | `NETVISOR_BIND_ADDRESS` | `bind_address` | `0.0.0.0` | IP address to bind daemon to |
+| **Daemon Name** | `--name` | `NETVISOR_NAME` | `name` | `netvisor-daemon` | Human-readable name for this daemon |
+| **Log Level** | `--log-level` | `NETVISOR_LOG_LEVEL` | `log_level` | `info` | Logging verbosity: `trace`, `debug`, `info`, `warn`, `error` |
+| **Heartbeat Interval** | `--heartbeat-interval` | `NETVISOR_HEARTBEAT_INTERVAL` | `heartbeat_interval` | `30` | Seconds between heartbeat updates / work requests (for daemons in pull mode) to server |
+| **Concurrent Scans** | `--concurrent-scans` | `NETVISOR_CONCURRENT_SCANS` | `concurrent_scans` | *Auto* | Maximum parallel host scans during discovery |
+| **Docker Proxy** | `--docker-proxy` | `NETVISOR_DOCKER_PROXY` | `docker_proxy` | *None* | Optional HTTP proxy for Docker API connections |
+
+### Concurrent Scans
+
+Controls how many hosts the daemon scans simultaneously during network discovery.
+
+**Default behavior**: Auto-detected based on system resources
+- Calculates based on available memory
+- Typical range: 10-20 for most systems
+- Adjusts to prevent memory exhaustion
+
+**When to set manually**:
+- System crashes during scans
+- Memory errors in logs
+- Very large networks (100+ hosts)
+- Resource-constrained devices (Raspberry Pi)
+
+**Recommended values**:
+- **Raspberry Pi 4 (4GB)**: 5-10
+- **Standard desktop**: 15-20
+- **Server**: 20-30+
+- **Low memory**: Start with 5, increase gradually
+
+**Setting**:
+```bash
+# CLI
+netvisor-daemon --concurrent-scans 10
+
+# Environment
+export NETVISOR_CONCURRENT_SCANS=10
+
+# Docker
+environment:
+  - NETVISOR_CONCURRENT_SCANS=10
+```
+
+**Symptoms of too high**:
+- Daemon crashes during scans
+- "CONCURRENT_SCANS too high for this system" error
+- Out of memory errors
+- System becomes unresponsive
+
+**Impact**:
+- Lower value = slower scans, more stable
+- Higher value = faster scans, more memory usage
+
+## Server Configuration
+
+### Configuration Methods
+
+**Environment variables in docker-compose**:
+```yaml
+environment:
+  - NETVISOR_SERVER_PORT=60072
+  - DATABASE_URL=postgresql://postgres:password@db:5432/netvisor
+```
+
+**Command-line** (for binary builds):
+```bash
+./netvisor-server --port 60072 --database-url postgresql://...
+```
+
+### Parameter Reference
+
+| Parameter | CLI Flag | Environment Variable | Default | Description |
+|-----------|----------|---------------------|---------|-------------|
+| **Server Public URL** | `--public-url` | `NETVISOR_SERVER_PUBLIC_URL` | `http://localhost:60072` | Public URL for webhooks, email links, etc |
+| **Server Port** | `--server-port` | `NETVISOR_SERVER_PORT` | `60072` | Port for server to listen on |
+| **Database URL** | `--database-url` | `NETVISOR_DATABASE_URL` | *Required* | PostgreSQL connection string |
+| **Log Level** | `--log-level` | `NETVISOR_LOG_LEVEL` | `info` | Logging verbosity: `trace`, `debug`, `info`, `warn`, `error` |
+| **Secure Cookies** | `--use-secure-session-cookies` | `NETVISOR_USE_SECURE_SESSION_COOKIES` | `false` | Enable HTTPS-only cookies |
+| **Integrated Daemon URL** | `--integrated-daemon-url` | `NETVISOR_INTEGRATED_DAEMON_URL` | `http://172.17.0.1:60073` | URL to reach daemon in default docker compose |
+| **Disable Registration** | `--disable-registration` | `NETVISOR_DISABLE_REGISTRATION` | `false` | Disable new user registration |
+| **OIDC Issuer URL** | `--oidc-issuer-url` | `NETVISOR_OIDC_ISSUER_URL` | - | OIDC provider's issuer URL (must end with `/`) |
+| **OIDC Client ID** | `--oidc-client-id` | `NETVISOR_OIDC_CLIENT_ID` | - | OAuth2 client ID from provider |
+| **OIDC Client Secret** | `--oidc-client-secret` | `NETVISOR_OIDC_CLIENT_SECRET` | - | OAuth2 client secret from provider |
+| **OIDC Provider Name** | `--oidc-provider-name` | `NETVISOR_OIDC_PROVIDER_NAME` | - | Display name shown in UI (e.g., "Authentik", "Keycloak") |
+| **OIDC Redirect URL** | `--oidc-redirect-url` | `NETVISOR_OIDC_REDIRECT_URL` | - | URL from OIDC provider for authentication redirect |
+| **SMTP Username** | `--smtp-username` | `NETVISOR_SMTP_USERNAME` | - | SMTP username for email features (password reset, notifications) |
+| **SMTP Password** | `--smtp-password` | `NETVISOR_SMTP_PASSWORD` | - | SMTP password for email authentication |
+| **SMTP Relay** | `--smtp-relay` | `NETVISOR_SMTP_RELAY` | - | SMTP server address (e.g., `smtp.gmail.com`) |
+| **SMTP Email** | `--smtp-email` | `NETVISOR_SMTP_EMAIL` | - | Sender email address for outgoing emails |
+
+### Integrated Daemon URL
+
+The integrated daemon runs in a separate container and needs to reach the server. The default assumes Docker's bridge network gateway is `172.17.0.1`.
+
+**Check your bridge gateway**:
+```bash
+docker network inspect bridge | grep Gateway
+```
+
+**If different**, update in docker-compose.yml:
+```yaml
+environment:
+  - NETVISOR_INTEGRATED_DAEMON_URL=http://YOUR_GATEWAY_IP:60073
+```
+
+### SMTP Configuration
+
+SMTP settings enable email-based features such as password reset.
+
+**All SMTP parameters are optional.** If not configured, email features will be disabled.
+
+**Configuration**:
+```yaml
+environment:
+  - NETVISOR_SMTP_RELAY=smtp.gmail.com:587
+  - NETVISOR_SMTP_USERNAME=your-email@gmail.com
+  - NETVISOR_SMTP_PASSWORD=your-app-password
+  - NETVISOR_SMTP_EMAIL=netvisor@yourdomain.com
+```
+
+## UI Configuration
+
+The UI automatically uses the hostname and port from your browser's address bar to reach the API.
+
+**No configuration needed** for standard deployments where UI and API are on the same domain.
+
+### Advanced: API on Different Domain
+
+If your API server is on a different hostname than where the UI is served (uncommon):
+
+Rebuild the Docker image with build arguments:
+
+```bash
+docker build \
+  --build-arg PUBLIC_SERVER_HOSTNAME=api.example.com \
+  --build-arg PUBLIC_SERVER_PORT=8080 \
+  -f backend/Dockerfile \
+  -t netvisor-server:custom \
+  .
+```
+
+Then use your custom image in docker-compose:
+
+```yaml
+netvisor-server:
+  image: netvisor-server:custom
+  # ... rest of config
+```
+
+## OIDC Setup
+
+NetVisor supports OpenID Connect (OIDC) for enterprise authentication with providers like Authentik, Keycloak, Auth0, Okta, and others.
+
+### Server Configuration
+
+Add these environment variables to your server configuration:
+
+```yaml
+environment:
+  # Required OIDC settings
+  - NETVISOR_OIDC_ISSUER_URL=https://your-provider.com/application/o/netvisor/
+  - NETVISOR_OIDC_CLIENT_ID=your-client-id
+  - NETVISOR_OIDC_CLIENT_SECRET=your-client-secret
+  - NETVISOR_OIDC_REDIRECT_URL=https://auth.example.com/callback
+  - NETVISOR_OIDC_PROVIDER_NAME=Authentik
+```
+
+### Parameter Details
+
+| Parameter | Environment Variable | Description |
+|-----------|---------------------|-------------|
+| **Issuer URL** | `NETVISOR_OIDC_ISSUER_URL` | Your OIDC provider's issuer URL (ends in `/`) |
+| **Client ID** | `NETVISOR_OIDC_CLIENT_ID` | OAuth2 client ID from your provider |
+| **Client Secret** | `NETVISOR_OIDC_CLIENT_SECRET` | OAuth2 client secret from your provider |
+| **Redirect URL** | `NETVISOR_OIDC_REDIRECT_URL` | URL provider redirects to after auth |
+| **Provider Name** | `NETVISOR_OIDC_PROVIDER_NAME` | Display name shown in UI (e.g., "Authentik", "Keycloak") |
+
+### Provider Configuration
+
+**Callback URL**: Configure this in your OIDC provider:
+```
+http://your-netvisor-domain:60072/api/auth/oidc/callback
+```
+
+Or with HTTPS:
+```
+https://your-netvisor-domain/api/auth/oidc/callback
+```
+
+**Required scopes**:
+- `openid` - OIDC standard
+- `email` - For user email address
+- `profile` - For user display name (optional)
+
+### Example: Authentik
+
+1. **Create Application** in Authentik:
+   - Name: NetVisor
+   - Provider: OAuth2/OpenID Provider
+
+2. **Configure Provider**:
+   - Redirect URI: `http://netvisor.local:60072/api/auth/oidc/callback`
+   - Scopes: `openid email profile`
+   - Client Type: Confidential
+   - Copy Client ID and Client Secret
+
+3. **Set NetVisor Environment Variables**:
+```yaml
+environment:
+  - NETVISOR_OIDC_ISSUER_URL=https://authentik.company.com/application/o/netvisor/
+  - NETVISOR_OIDC_CLIENT_ID=ABC123DEF456
+  - NETVISOR_OIDC_CLIENT_SECRET=xyz789uvw012
+  - NETVISOR_OIDC_REDIRECT_URL=https://auth.example.com/callback
+  - NETVISOR_OIDC_PROVIDER_NAME=Authentik
+```
+
+4. **Restart server** and test login
+
+## Session Security
+
+### Secure Cookies
+
+**Important**: Enable secure cookies when running NetVisor behind HTTPS.
+
+```yaml
+environment:
+  - NETVISOR_USE_SECURE_SESSION_COOKIES=true
+```
+
+**When to enable**:
+- Behind a reverse proxy with TLS (Nginx, Traefik, Caddy)
+- Using a domain with HTTPS
+- Production deployments
+
+**When to disable** (default):
+- Internal networks without HTTPS
+- Development environments
+- Accessing via IP address without TLS
+
+**Effect**:
+- `true`: Cookies marked as Secure, only sent over HTTPS
+- `false`: Cookies sent over HTTP and HTTPS
+
+## Environment Files
+
+For easier management, use `.env` files:
+
+**Create `.env`**:
+```bash
+# Database
+NETVISOR_DATABASE_URL=postgresql://postgres:password@db:5432/netvisor
+
+# Server
+NETVISOR_SERVER_PORT=60072
+NETVISOR_SERVER_PUBLIC_URL=http://your-domain.com:60072
+NETVISOR_LOG_LEVEL=info
+NETVISOR_USE_SECURE_SESSION_COOKIES=false
+
+# SMTP (optional - for password reset and notifications)
+NETVISOR_SMTP_RELAY=smtp.gmail.com:587
+NETVISOR_SMTP_USERNAME=your-email@gmail.com
+NETVISOR_SMTP_PASSWORD=your-app-password
+NETVISOR_SMTP_EMAIL=netvisor@yourdomain.com
+
+# OIDC (optional)
+NETVISOR_OIDC_ISSUER_URL=https://auth.example.com/
+NETVISOR_OIDC_CLIENT_ID=client_id
+NETVISOR_OIDC_CLIENT_SECRET=client_secret
+NETVISOR_OIDC_REDIRECT_URL=https://redirect.example.com/callback
+NETVISOR_OIDC_PROVIDER_NAME=Authentik
+
+# Daemon
+NETVISOR_INTEGRATED_DAEMON_URL=http://172.17.0.1:60073
+```
+
+**Reference in docker-compose.yml**:
+```yaml
+services:
+  netvisor-server:
+    image: mayanayza/netvisor-server:latest
+    env_file:
+      - .env
+    # ... rest of config
+```
+
+---
+
+**Next Steps**: See the [User Guide](USER_GUIDE.md) to learn how to use NetVisor's features.
@@ -0,0 +1,300 @@
+# Installation Guide
+
+This guide covers installing NetVisor on various platforms and deployment scenarios.
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Docker Installation (Recommended)](#docker-installation-recommended)
+- [Building from Source](#building-from-source)
+- [Platform-Specific Instructions](#platform-specific-instructions)
+- [Additional Daemons](#additional-daemons)
+- [Troubleshooting](#troubleshooting)
+- [Uninstalling](#uninstalling)
+
+## Requirements
+
+### Server Requirements
+
+**Docker Installation (Recommended)**
+- Docker Engine 20.10 or later
+- Docker Compose V2
+
+**Building from Source**
+- Rust 1.90 or later
+- Node.js 20 or later
+- PostgreSQL 17
+- 4GB RAM minimum
+- 20GB disk space
+
+### Daemon Requirements
+
+**Integrated Daemon** (included in default docker-compose):
+- Docker with host networking support
+- Runs on same host as server
+
+**Additional Daemons** (optional, for multi-VLAN scanning):
+- **Linux**: Docker with host networking OR standalone binary
+- **macOS**: Standalone binary only (Docker Desktop lacks host networking)
+- **Windows**: Standalone binary only (Docker Desktop lacks host networking)
+
+## Docker Installation (Recommended)
+
+This is the easiest way to get started with NetVisor.
+
+### 1. Download the Docker Compose File
+
+```bash
+curl -O https://raw.githubusercontent.com/mayanayza/netvisor/refs/heads/main/docker-compose.yml
+```
+
+### 2. Review Configuration
+
+The default `docker-compose.yml` includes:
+- NetVisor server on port 60072
+- PostgreSQL database
+- Integrated daemon for immediate network scanning
+
+**Important**: The integrated daemon assumes your Docker bridge network is `172.17.0.1`. If your Docker bridge uses a different address, edit the `NETVISOR_INTEGRATED_DAEMON_URL` environment variable in the compose file.
+
+### 3. Start NetVisor
+
+```bash
+docker compose up -d
+```
+
+### 4. Verify Installation
+
+Check that services are running:
+
+```bash
+docker compose ps
+```
+
+You should see:
+- `netvisor-server` - Running on port 60072
+- `netvisor-postgres` - PostgreSQL database
+- `netvisor-daemon` - Integrated daemon
+
+### 5. Access the UI
+
+Navigate to `http://<your-server-ip>:60072`
+
+You'll see the registration page on first load.
+
+## Building from Source
+
+Refer to [contributing](../contributing.md) for details on getting your dev environment set up to build from source.
+
+## Platform-Specific Instructions
+
+### Proxmox LXC Container
+
+You can use this [helper script](https://community-scripts.github.io/ProxmoxVE/scripts?id=netvisor) to create a NetVisor LXC on your Proxmox host.
+
+### Unraid
+
+NetVisor is available as an Unraid community app.
+
+**Common Issues:**
+
+If running NetVisor directly on a Proxmox host and encountering `could not create any Unix-domain sockets`, add this to both the PostgreSQL and NetVisor services in your docker-compose:
+
+```yaml
+security_opt:
+  - apparmor:unconfined
+```
+
+If running in an LXC, you may need to change `NETVISOR_INTEGRATED_DAEMON_URL` to `172.31.0.1`.
+
+See [issue #87](https://github.com/mayanayza/netvisor/issues/87) for more details.
+
+## Additional Daemons
+
+To scan multiple VLANs or remote networks, deploy additional daemons.
+
+### Creating a Daemon
+
+1. Navigate to **Manage > Daemons** in the NetVisor UI
+2. Click **"Create Daemon"**
+3. Select the target network
+4. Select Daemon mode
+5. Click **"Generate Key"** to create an API key
+6. Copy either the Docker Compose or binary installation command
+
+**Manual Installation:**
+
+Download the appropriate binary from the [releases page](https://github.com/mayanayza/netvisor/releases/latest):
+
+- Linux x86_64: `netvisor-daemon-linux-amd64`
+- Linux ARM64: `netvisor-daemon-linux-arm64`
+- macOS x86_64: `netvisor-daemon-darwin-amd64`
+- macOS ARM64: `netvisor-daemon-darwin-arm64`
+- Windows x86_64: `netvisor-daemon-windows-amd64.exe`
+
+Make it executable (Linux/macOS):
+
+```bash
+chmod +x netvisor-daemon
+sudo mv netvisor-daemon /usr/local/bin/
+```
+
+**Run the Daemon:**
+
+```bash
+netvisor-daemon \
+  --server-url http://YOUR_SERVER_URL \
+  --network-id YOUR_NETWORK_ID \
+  --daemon-api-key YOUR_API_KEY
+  --mode push
+```
+
+### Systemd Service (Linux)
+
+For automatic startup, the install script offers to set up a systemd service.
+
+**Manual systemd setup:**
+
+1. Download the service file:
+
+```bash
+curl -o netvisor-daemon.service https://raw.githubusercontent.com/mayanayza/netvisor/main/netvisor-daemon.service
+```
+
+2. Edit the service file with your configuration:
+
+```bash
+sudo nano netvisor-daemon.service
+```
+
+Update the `ExecStart` line with your parameters.
+
+3. Install and enable:
+
+```bash
+sudo mv netvisor-daemon.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable netvisor-daemon
+sudo systemctl start netvisor-daemon
+```
+
+4. Check status:
+
+```bash
+sudo systemctl status netvisor-daemon
+sudo journalctl -u netvisor-daemon -f
+```
+
+## Troubleshooting
+
+### Integrated Daemon Not Initializing
+
+**Symptoms**: Daemon shows in UI but doesn't start discovery
+
+**Diagnosis**:
+
+```bash
+# Check daemon logs
+docker logs netvisor-daemon
+
+# Check if daemon can reach server
+docker exec netvisor-daemon curl http://netvisor-server:60072/api/health
+```
+
+**Solutions**:
+
+1. **Verify bridge network**: Check your Docker bridge IP
+   ```bash
+   docker network inspect bridge | grep Gateway
+   ```
+   
+2. **Update compose file**: If gateway isn't `172.17.0.1`, update `NETVISOR_INTEGRATED_DAEMON_URL`
+
+3. **Check API key**: Ensure the integrated daemon has a valid API key in the database
+
+### Discovery Fails with "CONCURRENT_SCANS too high"
+
+**Symptoms**: Daemon crashes or runs out of memory during scans
+
+**Solution**: Reduce concurrent scans in daemon configuration:
+
+**Docker:**
+```yaml
+environment:
+  - NETVISOR_CONCURRENT_SCANS=10  # Reduce from default
+```
+
+**Binary:**
+```bash
+netvisor-daemon --concurrent-scans 10 ...
+```
+
+See [CONFIGURATION.md](CONFIGURATION.md#concurrent-scans) for recommended values.
+
+### Port Already in Use
+
+**Symptoms**: Server fails to start with "address already in use"
+
+**Solution**: Change the port mapping in docker-compose.yml:
+
+```yaml
+ports:
+  - "8080:60072"  # Change 60072 to any available port
+```
+
+### Permission Denied Errors (Linux)
+
+**Symptoms**: "Permission denied" when accessing Docker socket
+
+**Solution**: Add user to docker group:
+
+```bash
+sudo usermod -aG docker $USER
+newgrp docker
+```
+
+Log out and back in for changes to take effect.
+
+## Uninstalling
+
+### Docker Installation
+
+```bash
+# Stop and remove containers
+docker compose down
+
+# Remove volumes (deletes all data)
+docker compose down -v
+
+# Remove images
+docker rmi mayanayza/netvisor-server:latest
+docker rmi mayanayza/netvisor-daemon:latest
+```
+
+### Standalone Daemon
+
+**Linux/macOS:**
+
+```bash
+# Stop systemd service (if installed)
+sudo systemctl stop netvisor-daemon
+sudo systemctl disable netvisor-daemon
+sudo rm /etc/systemd/system/netvisor-daemon.service
+
+# Remove binary
+sudo rm /usr/local/bin/netvisor-daemon
+
+# Remove configuration
+rm -rf ~/.config/netvisor/  # Linux
+rm -rf ~/Library/Application\ Support/com.netvisor.daemon/  # macOS
+```
+
+**Windows:**
+
+1. Stop the daemon process
+2. Delete the executable
+3. Remove configuration from `%APPDATA%\netvisor\daemon\`
+
+---
+
+**Next Steps**: See the [User Guide](USER_GUIDE.md) to learn how to use NetVisor's features.
@@ -0,0 +1,968 @@
+# User Guide
+
+Complete guide to using NetVisor's features for network discovery, organization, and visualization.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Authentication](#authentication)
+- [Organizations](#organizations)
+- [Navigation](#navigation)
+- [Networks](#networks)
+- [Hosts](#hosts)
+- [Services](#services)
+- [Subnets](#subnets)
+- [Groups](#groups)
+- [Daemons](#daemons)
+- [API Keys](#api-keys)
+- [Discovery](#discovery)
+- [Topology Visualization](#topology-visualization)
+- [Multi-VLAN Setup](#multi-vlan-setup)
+- [FAQ](#faq)
+
+## Getting Started
+
+### First Time Setup
+
+1. **Access the UI** at `http://<your-server-ip>:60072`
+
+2. **Create your account**:
+   - Enter an email address
+   - Create a password
+   - Click **Register**
+   - Alternatively, use OIDC authentication (see [Authentication](#authentication))
+
+<p align="center">
+  <img src="../media/registration.png" width="400" alt="Registration Screen">
+</p>
+
+3. **Onboard**: 
+    - Select the name of your organization and network
+    - Decide whether NetVisor should create baseline data for your first network (recommended)
+
+4. **Automatic initialization**: After onboarding, NetVisor automatically:
+   - Starts the integrated daemon (if using default docker-compose with integrated daemon)
+   - Begins initial discovery
+   - Schedules daily discovery
+
+4. **Monitor discovery**: Switch to **Discover > Sessions** to watch the scan progress
+
+<p align="center">
+  <img src="../media/first_discovery.png" width="600" alt="First Discovery">
+</p>
+
+5. **View results**: Once complete (5-10+ minutes), navigate to **Topology** to see your network diagram
+
+## Authentication
+
+NetVisor supports two authentication methods:
+
+### Email & Password
+
+Standard authentication with email and password.
+
+**Updating credentials**: Go to **Account** in sidebar to change your email or password.
+
+### OIDC (OpenID Connect)
+
+NetVisor supports OIDC authentication for enterprise identity providers like Authentik, Keycloak, Auth0, Okta, and others.
+
+**Setup**: OIDC must be configured by the server administrator. See [CONFIGURATION.md](CONFIGURATION.md#oidc-setup) for setup instructions.
+
+**Linking OIDC**: If OIDC is enabled, you can link it to your existing account:
+1. Go to **Account Settings** (user icon in top right)
+2. Click **Link** under your OIDC provider
+3. Complete the authentication flow
+4. Your account is now linked
+
+**Unlinking**: You can unlink OIDC at any time, but you'll need to have a password set first.
+
+## Organizations
+
+Organizations are the top-level container for users and networks. Every user belongs to exactly one organization.
+
+### Organization Roles
+
+These permission levels control what users can do:
+
+**Owner**
+- Everything Admins can do
+- Manage organization settings
+- Invite Admins
+
+**Admin**
+- Everything Members can do
+- View other Admins
+- Invite Members
+- Remove Members
+
+**Member**
+- Everything Visualizers can do
+- Create and edit networks, hosts, services
+- Run discovery sessions
+- Manage daemons and API keys
+- View other members
+- Invite Visualizers
+- Remove Visualizers
+
+**Visualizer**
+- View topology diagrams
+
+### Managing Users
+
+**Inviting users**:
+1. Navigate to **Manage > Users**
+2. Click **"Invite User"**
+3. Select the permission level
+4. Click **"Generate Link"** to create an invite link
+5. Share the invite URL with the new user
+6. They'll register and automatically join your organization
+
+**Viewing users**:
+- See all organization members in **Manage > Users**
+- View each user's role, authentication method, and join date
+
+**Removing users** (Owner only):
+- Click the delete icon on a user card
+- You cannot delete yourself
+- You cannot delete the only Owner
+
+<p align="center">
+  <img src="../media/organization_users.png" width="800" alt="Organization Users">
+</p>
+
+### Organization Settings
+
+**Viewing organization** (Owner only):
+- Navigate to **Manage > Organization** to view organization name and plan information
+
+**Note**: Organizations are automatically created during registration and cannot be manually created or transferred.
+
+## Navigation
+
+The NetVisor UI is organized into three main sections:
+
+### Sidebar
+
+#### Topology
+
+Interactive network visualization showing hosts, services, subnets, and their connections.
+
+#### Discover
+
+**Sessions**
+- Monitor active discovery scans in real-time
+- View completed discovery history
+- See scan progress, duration, and results
+
+**Scheduled**
+- Create and manage scheduled discoveries
+- Configure automatic network scanning
+- Set custom cron schedules
+
+#### Manage
+
+**Networks** - Organize resources by network environment  
+**Hosts** - View and manage discovered devices  
+**Services** - Browse all detected services  
+**Subnets** - Configure network segments  
+**Groups** - Create logical service groupings  
+**Daemons** - Manage discovery agents  
+**API Keys** - Control daemon authentication  
+**Users** - Manage organization members  
+
+#### Settings
+
+**Organization** - View and edit organization settings (only Owners)
+**Account** - View and edit account settings
+
+## Networks
+
+Networks are the primary organizational unit in NetVisor. Each network represents a distinct environment with its own hosts, services, and topology.
+
+### What Networks Are For
+
+- Separating production, staging, and home environments
+- Organizing networks by physical location
+- Managing multi-tenant deployments
+- Grouping related infrastructure
+
+### Network Properties
+
+- **Name**: Display name for the network
+- **Description**: Optional notes about the network's purpose
+- **Daemons**: Which daemons scan this network
+- **Hosts**: Number of discovered hosts
+- **Services**: Number of detected services
+
+### Managing Networks
+
+**Creating a network**:
+1. Navigate to **Manage > Networks**
+2. Click **"Create Network"**
+3. Enter name and optional description
+4. Deploy a daemon to scan it
+
+**Switching networks**: Networks are selected via the topology options panel or when creating discoveries.
+
+**Deleting a network**: Click the delete icon on the network card. This removes all associated hosts, services, and topology data.
+
+<p align="center">
+  <img src="../media/networks_tab.png" width="800" alt="Networks Tab">
+</p>
+
+## Hosts
+
+Hosts represent physical or virtual devices on your network. They are automatically discovered during network scans.
+
+### Host Properties
+
+- **Name**: Hostname or custom name
+- **IP Addresses**: All network interfaces
+- **MAC Addresses**: Hardware addresses for each interface
+- **Interfaces**: Network connections and subnet membership
+- **Services**: Services running on the host
+- **Virtualization**: Container or VM relationships (if detected)
+
+### Managing Hosts
+
+**Viewing hosts**:
+- Navigate to **Manage > Hosts**
+- Filter by network, service type, or search
+- Click a host to see detailed information
+
+**Editing a host**:
+1. Click on a host card
+2. Modify properties in the detail panel
+3. Add/remove interfaces or services
+4. Save changes
+
+**Creating a host manually**:
+1. Click **"Create Host"**
+2. Provide name and at least one interface
+3. Add services as needed
+4. Save
+
+**Deleting a host**: Click the delete icon. This removes the host and all its interfaces and services.
+
+<p align="center">
+  <img src="../media/hosts_tab.png" width="800" alt="Hosts Tab">
+</p>
+
+### Consolidating Hosts
+
+When a device appears on multiple VLANs or through different discovery methods, it may be discovered as separate hosts. Use consolidation to merge them.
+
+**How to consolidate**:
+1. Select a host to keep (primary)
+2. Click **"Consolidate"**
+3. Select the duplicate host(s) to merge
+4. Review the consolidated result
+5. Confirm the merge
+
+The primary host will gain all interfaces, services, and properties from the merged hosts.
+
+### Host Virtualization
+
+If a host runs Proxmox or Docker, NetVisor tracks which VMs or containers run on it.
+
+**Virtualization managers detected**:
+- **Proxmox**: Links VMs and LXC containers to the Proxmox service running on the host
+- **Docker**: Links containers to the Docker service running on the host
+
+This relationship is displayed in the topology and host details.
+
+## Services
+
+Services represent applications or servers running on hosts. NetVisor automatically detects 50+ common services.
+
+### Service Properties
+
+- **Name**: Service display name
+- **Definition**: Service type (e.g., "Plex", "Home Assistant")
+- **Category**: Classification (Media, Infrastructure, Development, etc.)
+- **Host**: Which host runs this service
+- **Bindings**: Ports and interfaces the service listens on
+- **Confidence**: Detection confidence (System, High, Medium, Low)
+
+### Service Categories
+
+Services are organized into categories for filtering and organization:
+
+**Infrastructure**
+- NetworkCore, NetworkAccess, NetworkSecurity
+- DNS, VPN, ReverseProxy
+
+**Server Services**
+- Storage, Media, HomeAutomation, Virtualization
+- Backup, FileSharing
+
+**Applications**
+- Web, Database, Development, Dashboard
+- Monitoring, MessageQueue, Collaboration
+- IdentityAndAccess, Communication
+
+**Devices**
+- Workstation, Mobile, IoT, Printer
+
+**Other**
+- AdBlock, Custom, Unknown
+
+### Managing Services
+
+**Viewing services**:
+- Navigate to **Manage > Services**
+- Filter by category, host, or network
+- Click a service for details
+
+**Editing a service**:
+1. Click on a service card
+2. Modify name, bindings, or properties
+3. Save changes
+
+**Creating a service manually**:
+1. Navigate to a host's detail view
+2. Go to the **Services** tab
+3. Click **"Add Service"**
+4. Select service type and configure bindings
+5. Save
+
+**Deleting a service**: Click the delete icon on the service card.
+
+<p align="center">
+  <img src="../media/services_tab.png" width="800" alt="Services Tab">
+</p>
+
+## Subnets
+
+Subnets represent network segments and are used to organize hosts in the topology.
+
+### Subnet Properties
+
+- **CIDR**: Network address and mask (e.g., `192.168.1.0/24`)
+- **Name**: Custom name or defaults to CIDR
+- **Description**: Optional notes about the subnet's purpose
+- **Type**: Network classification (LAN, Docker Bridge, Internet, Remote, etc.)
+
+### Subnet Types
+
+NetVisor automatically detects subnet types during discovery:
+
+**Physical Networks**
+- **LAN**: Local area networks
+- **WiFi**: Wireless networks  
+- **IoT**: IoT device networks
+- **Guest**: Guest networks
+
+**Infrastructure**
+- **Gateway**: Gateway interfaces
+- **VPN Tunnel**: VPN connections
+- **DMZ**: Demilitarized zones
+- **Management**: Management networks
+
+**Virtual Networks**
+- **Docker Bridge**: Docker container networks
+
+**Special Types**
+- **Internet**: Organizational subnet for public services (uses 0.0.0.0/0)
+- **Remote**: Organizational subnet for remote hosts (uses 0.0.0.0/0)
+
+### Organizational Subnets
+
+Subnets with CIDR `0.0.0.0/0` don't represent real networks—they're organizational containers:
+
+**Internet Subnet**: For public services
+- Public DNS servers (1.1.1.1, 8.8.8.8)
+- Cloud services
+- External APIs
+
+**Remote Subnet**: For non-local hosts
+- Mobile devices
+- Remote offices connected via VPN
+- Hosts on friend's networks
+
+### Managing Subnets
+
+**Viewing subnets**:
+- Navigate to **Manage > Subnets**
+- See all subnets across networks
+- Filter by network or type
+
+**Editing a subnet**:
+1. Click on a subnet card
+2. Modify name, description, or type
+3. Save changes
+
+**Creating a subnet**:
+1. Click **"Create Subnet"**
+2. Enter CIDR and name
+3. Select type
+4. Save
+
+**Deleting a subnet**: Click the delete icon. Hosts on the subnet remain but lose subnet association.
+
+<p align="center">
+  <img src="../media/subnets_tab.png" width="800" alt="Subnets Tab">
+</p>
+
+## Groups
+
+Groups create logical connections between services and hosts for topology visualization.
+
+### Group Types
+
+**Hub and Spoke**
+- Central service with connections to multiple others
+- Example: API gateway connected to microservices
+- Example: Database accessed by multiple applications
+
+**Path**
+- Linear flow through services
+- Example: User → Reverse Proxy → Web App → Database
+- Example: Client → VPN → Internal Services
+
+### Group Properties
+
+- **Name**: Display name
+- **Type**: Hub and Spoke or Path
+- **Services**: Which services/hosts participate
+- **Color**: Visual styling in topology (optional)
+
+### What Groups Do
+
+Groups affect how your topology is displayed:
+- Add edges between services to show relationships
+- Create visual groupings
+- Help document application architectures
+- Organize complex network structures
+
+### Managing Groups
+
+**Creating a group**:
+1. Navigate to **Manage > Groups**
+2. Click **"Create Group"**
+3. Select type (Hub and Spoke or Path)
+4. Choose the central service (Hub and Spoke) or order services (Path)
+5. Add related services
+6. Save
+
+**Editing a group**:
+1. Click on a group card
+2. Modify services or reorder (Path groups)
+3. Save changes
+
+**Deleting a group**: Click the delete icon. This only removes the logical grouping—services and hosts remain.
+
+<p align="center">
+  <img src="../media/groups_tab.png" width="800" alt="Groups Tab">
+</p>
+
+### Use Cases
+
+**Web application stack**:
+```
+Hub: Database
+Spokes: Web Server, Background Workers, Admin Panel
+```
+
+**Reverse proxy flow**:
+```
+Path: Internet → Cloudflare → Traefik → Application
+```
+
+## Daemons
+
+Daemons are lightweight agents that perform network discovery.
+
+### Daemon Properties
+
+- **IP Address**: Where the daemon is reachable
+- **Port**: Daemon API port (default 60073)
+- **Network**: Which network this daemon scans
+- **Host**: The underlying host running the daemon
+- **Mode**: Whether the daemon will pull work (discovery sessions to run or cancel) from the server, or the server will push work to the daemon
+- **Created**: When the daemon was registered
+- **Last Seen**: Timestamp of last successful heartbeat
+
+### Daemon Capabilities
+
+Each daemon reports its capabilities:
+
+**Docker Socket Access**
+- **True**: Can discover Docker containers
+- **False**: Cannot access Docker socket
+
+**Interfaced Subnets**
+- Lists which subnets the daemon has network interfaces with
+- The daemon will scan these subnets by default during network discovery
+
+### Managing Daemons
+
+**Viewing daemons**:
+- Navigate to **Manage > Daemons**
+- See all daemons and their capabilities
+- Check last seen timestamps
+
+**Creating a daemon**:
+1. Click **"Create Daemon"**
+2. Select target network
+3. Click **"Generate Key"** to create API key
+4. Copy the Docker Compose or binary command
+5. Run it on your target host
+
+See [INSTALLATION.md](INSTALLATION.md#additional-daemons) for deployment instructions.
+
+**Deleting a daemon**: Click the delete icon. You'll also need to uninstall the daemon from the host it's running on.
+
+<p align="center">
+  <img src="../media/daemons_tab.png" width="800" alt="Daemons Tab">
+</p>
+
+**Important**: Deleting a daemon does NOT delete discovered data. Hosts, services, and topology remain until explicitly deleted.
+
+## API Keys
+
+API keys authenticate daemons to the server. Each daemon requires one API key.
+
+### API Key Properties
+
+- **Name**: Custom identifier for the key
+- **Network**: Which network this key grants access to
+- **Created**: When the key was generated
+- **Last Used**: Timestamp of last authentication
+- **Expires At**: Optional expiration date
+- **Enabled**: Whether the key is currently active
+
+### Managing API Keys
+
+**Viewing API keys**:
+- Navigate to **Manage > API Keys**
+- See all keys and their usage status
+
+**Creating an API key**:
+1. Go to **Manage > Daemons**
+2. Click **"Create Daemon"**
+3. Click **"Generate Key"**
+4. The key is automatically created and assigned to the network
+
+Alternatively:
+1. Go to **Manage > API Keys**
+2. Click **"Create API Key"**
+3. Select target network
+4. Set optional expiration
+5. Save and copy the key (it won't be shown again)
+
+**Disabling an API key**:
+1. Click on the key card
+2. Toggle **"Enabled"** to off
+3. Save
+
+Disabled keys cannot authenticate, but can be re-enabled later.
+
+**Deleting an API key**: Click the delete icon. Any daemons using this key will stop authenticating and stop working.
+
+<p align="center">
+  <img src="../media/api_keys_tab.png" width="800" alt="API Keys Tab">
+</p>
+
+### Security Best Practices
+
+- Create separate API keys for each daemon
+- Use expiration dates for temporary deployments
+- Disable unused keys rather than deleting them
+- Rotate keys periodically for production environments
+- Never share keys in public repositories or logs
+
+## Discovery
+
+Discovery is the process of scanning your network to find hosts and services.
+
+### Discovery Types
+
+**Self-Report**
+- Daemon reports its own capabilities
+- Identifies Docker socket access
+- Lists interfaced subnets
+- Runs automatically on daemon startup
+
+**Network Scan**
+- Scans IP addresses on configured subnets
+- Detects open ports
+- Identifies services via pattern matching
+- Performs reverse DNS lookups
+- Collects MAC addresses (for directly connected subnets)
+
+**Docker**
+- Connects to Docker socket on daemon's host
+- Discovers running containers
+- Maps container names and metadata
+- Detects containerized services
+- Identifies internal Docker networks
+
+### Run Types
+
+**AdHoc (On Demand)**
+- Manual execution only
+- Use for testing or one-time scans
+- Triggered from **Discover > Sessions**
+
+**Scheduled (Automatic)**
+- Runs on a cron schedule
+- Default: Hourly (`0 0 */1 * * *`)
+- Can be customized to any cron expression
+- Enable/disable without deleting
+
+### Creating a Discovery
+
+1. Navigate to **Discover > Scheduled**
+2. Click **"Create Discovery"**
+3. **Details**:
+   - Enter a name (e.g., "Daily Network Scan")
+   - Select the daemon to execute the discovery
+4. **Type**:
+   - Choose discovery type (Network, Docker, or Self-Report)
+   - For Network: Select subnets to scan. You can add subnets that the daemon doesn't have a direct interface with, and it will try to reach IP addresses on that subnet as well.
+   - For Docker/Self-Report: Automatically uses daemon's host
+5. **Schedule** (optional):
+   - Choose AdHoc or Scheduled
+   - For Scheduled: Set cron schedule or use preset intervals
+6. Save
+
+### Running a Discovery
+
+**Manual execution**:
+1. Navigate to **Discover > Sessions**
+2. Find your discovery in the scheduled list
+3. Click the **"Run"** button
+4. Monitor progress in real-time
+
+**Scheduled execution**:
+- Scheduled discoveries run automatically at their configured time
+- View the "Last Run" timestamp in the scheduled discoveries list
+
+### Monitoring Discovery
+
+**Real-time progress**:
+- Navigate to **Discover > Sessions**
+- Active scans show live progress updates
+- See scanned count vs. discovered count
+- Watch as hosts and services are found
+
+**Discovery history**:
+- Completed discoveries appear in the history list
+- View duration, start/end times, and results
+- Filter by daemon or network
+
+<p align="center">
+  <img src="../media/discovery_sessions.png" width="800" alt="Discovery Sessions">
+</p>
+
+### Discovery Duration
+
+For benchmarking, 1x /24 subnet (256 IP addresses) takes 5-10 minutes to scan in full.
+
+Factors affecting speed:
+- Number of IP addresses to scan
+- Subnet mask size (smaller masks = more IPs)
+- Concurrent scans setting (default: 15)
+- Network response times
+
+### Host Naming
+
+When discovering hosts, NetVisor determines names using this priority:
+
+1. Hostname from reverse DNS, if available
+2. If **BestService** is set - will use the first named service identified on the host. If **IP** is set, will use the host's IP address
+3. If option 2 didn't produce a name, will use the remaining fallback (ie **IP** if **BestService** was set)
+
+Configure this per-discovery in the discovery type settings.
+
+## Topology Visualization
+
+The topology view generates an interactive diagram of your network structure.
+
+<p align="center">
+  <img src="../media/topology_full.png" width="800" alt="Discovery Sessions">
+</p>
+
+### Visual Elements
+
+**Subnet Containers**
+- Large rectangles grouping hosts by network segment
+- Shows subnet name and CIDR
+- Can be resized manually
+
+**Host Nodes**
+- Represent network interfaces
+- Show services bound to that interface
+- Display IP addresses and hostnames
+
+**Service Nodes**
+- Icons representing detected services
+- Show service name and ports
+- Color-coded by category
+
+**Edges**
+- Lines connecting related nodes
+- Different types:
+  - Host interfaces
+  - Group relationships
+  - Docker container links
+  - Gateway connections
+
+**Left Zone**
+- Optional section within each subnet
+- Can display infrastructure services separately
+- Customizable title and service categories
+
+### Customization Options
+
+Access the options panel via the button on the right side of the topology view:
+
+<p align="center">
+  <img src="../media/topology_options_overview.png" width="800" alt="Topology Options">
+</p>
+
+**General Options**
+
+*Network Selection*
+- Choose which networks to include in the diagram
+- Multi-select to overlay multiple networks
+- Useful for comparing environments
+
+*Service Category Filters*
+- Hide specific categories (Media, Development, etc.)
+- Reduces clutter for large networks
+- Categories remain in data, just hidden from view
+
+**Visual Options**
+
+*Don't Fade Edges*
+- Show all edges at full opacity
+- Default behavior fades unselected edges
+- Enable for clearer edge visibility
+
+*Hide Resize Handles*
+- Remove subnet resize handles from corners
+- Cleaner screenshot appearance
+- Re-enable to adjust subnet sizes
+
+**Docker Options**
+
+*Group Docker Bridges*
+- Display all containers on a host in one subnet grouping
+- Off: Each Docker bridge gets its own subnet container
+- On: All Docker containers grouped under one subnet per host
+
+<p align="center">
+  <img src="../media/topology_docker_grouping.png" width="700" alt="Docker Grouping Comparison">
+</p>
+
+*Hide VM Provider on Containers*
+- Don't indicate the VM provider for containerized services
+- Useful when virtualization hierarchy is obvious
+- Reduces visual noise
+
+**Left Zone Options**
+
+*Custom Title*
+- Change the "Infrastructure" label to your preference
+- Examples: "Core Services", "Network", "Foundation"
+- Applied to all subnets
+
+*Service Categories*
+- Select which categories appear in the left zone
+- Default: DNS and ReverseProxy
+- Common choices: Add VPN, Monitoring
+
+*Show Gateway in Left Zone*
+- Display gateway services in the left zone
+- Off: Gateways appear in the main subnet area
+- On: Gateways separated in left zone
+
+**Hide Options**
+
+*Hide Ports*
+- Don't show port numbers next to services
+- Cleaner appearance
+- Re-enable to see listening ports
+
+*Service Categories*
+- Select categories to completely hide from topology
+- More aggressive than filtering
+- Use to remove entire classes of services
+
+*Edge Types*
+- Hide specific connection types
+- Options: Interface, Gateway, Group, Container
+- Simplifies complex topologies
+
+### Manual Adjustments
+
+**Node Positioning**
+- Click and drag any node to reposition
+- Reset by refreshing the topology
+
+**Subnet Sizing**
+- Drag subnet corners to resize
+- Useful for fitting many hosts
+
+### Exporting
+
+Export your topology as a PNG image:
+
+1. Customize your topology as desired
+2. Click the **Export** button in the topology header
+3. PNG file downloads automatically with timestamp
+4. Image includes all current customizations
+
+Use cases:
+- Documentation
+- Presentations
+- Sharing with team members
+- Progress tracking
+
+## Multi-VLAN Setup
+
+To map networks across multiple VLANs, deploy additional daemons or select additional subnets in **Discovery > Scheduled**.
+
+### Why Multiple Daemons?
+
+Adding subnets to a scan works, but the daemon isn't guaranteed to be able to reach those subnets depending on your network firewall and other configurations, and it won't be able to get MAC Addresses or Hostnames from DNS.
+
+For isolated VLANs:
+- Deploy one daemon per VLAN
+- Each daemon scans its local network segment
+- Server merges data into unified topology
+
+### Deployment Strategy
+
+**Option 1: Daemon per VLAN (Recommended)**
+
+1. Identify your VLANs:
+   - Production (192.168.1.0/24)
+   - IoT (192.168.2.0/24)
+   - Guest (192.168.3.0/24)
+
+2. Deploy a daemon on each network:
+   - Place a host on each VLAN (or use a router/firewall with access)
+   - Install daemon following [INSTALLATION.md](INSTALLATION.md#additional-daemons)
+   - Configure with appropriate network ID
+
+3. Run discoveries:
+   - Each daemon scans its local VLAN
+   - Server consolidates results automatically
+
+**Option 2: Configure Subnets Daemon Can Reach**
+
+If your daemon can route to multiple VLANs (e.g., it's on a management network):
+
+1. Create subnets for each VLAN in **Manage > Subnets**
+2. Create a Network Scan discovery in **Discover > Scheduled**
+3. Select all reachable subnets
+4. Run the discovery
+
+**Note**: Without direct interface, the daemon cannot collect MAC addresses or hostnames via DHCP.
+
+### Handling Duplicate Hosts
+
+Devices appearing on multiple VLANs may be discovered as separate hosts. Use the [Consolidate Hosts](#consolidating-hosts) feature to merge them:
+
+1. Identify the duplicate hosts (same device, different IPs)
+2. Select the primary host to keep
+3. Click **"Consolidate"**
+4. Select the duplicate(s) to merge
+5. Confirm
+
+The primary host will have interfaces on all VLANs.
+
+## FAQ
+
+### Is IPv6 supported?
+
+Not currently. IPv6 support is planned for future releases:
+
+**Planned features**:
+- Collecting and displaying IPv6 addresses during discovery
+- Manual entry of IPv6 addresses when editing hosts
+- IPv6 connectivity testing for known hosts
+
+**Not planned**:
+- Full IPv6 subnet scanning (would take too long for /64 networks)
+
+If you need IPv6 support sooner, [open an issue](https://github.com/mayanayza/netvisor/issues/new) describing your use case.
+
+### What services can NetVisor discover?
+
+50+ services including:
+
+**Media Servers**: Plex, Jellyfin, Emby, Tautulli  
+**Home Automation**: Home Assistant, HomeKit, Philips Hue Bridge  
+**Virtualization**: Proxmox, Docker, Kubernetes, Portainer  
+**Network**: Pi-hole, AdGuard, Unifi Controller, pfSense, OPNsense  
+**Storage**: Synology DSM, QNAP, TrueNAS, Nextcloud, Samba  
+**Monitoring**: Grafana, Prometheus, Uptime Kuma, Netdata  
+**Proxies**: Nginx Proxy Manager, Traefik, Caddy, Cloudflared  
+**Databases**: PostgreSQL, MySQL, MongoDB, Redis  
+**Development**: GitLab, Gitea, Jenkins, Ansible AWX
+
+Complete list: [service definitions directory](https://github.com/mayanayza/netvisor/tree/main/backend/src/server/services/definitions)
+
+**Service not detected?**
+- Report it: [Service detection issue](https://github.com/mayanayza/netvisor/issues/new?template=service-detection-issue.md)
+- Request it: [Missing service](https://github.com/mayanayza/netvisor/issues/new?template=missing-service-detection.md)
+- Contribute: [Service definition guide](contributing.md#adding-service-definitions)
+
+### How do I contribute?
+
+We welcome contributions! See [contributing.md](contributing.md) for:
+- Adding service definitions (great first contribution!)
+- Reporting bugs
+- Requesting features
+- Submitting pull requests
+
+Join our [Discord community](https://discord.gg/b7ffQr8AcZ) for help and discussions.
+
+Update `NETVISOR_INTEGRATED_DAEMON_URL` to match if using the integrated daemon.
+
+See [CONFIGURATION.md](CONFIGURATION.md) for more options.
+
+### How do I backup my data?
+
+NetVisor stores all data in PostgreSQL. To backup:
+
+**Docker setup**:
+```bash
+# Backup
+docker exec netvisor-db pg_dump -U postgres netvisor > netvisor_backup.sql
+
+# Restore
+docker exec -i netvisor-db psql -U postgres netvisor < netvisor_backup.sql
+```
+
+**Manual setup**: Use standard PostgreSQL backup tools (pg_dump, pg_restore).
+
+### How do I reset my password?
+
+Currently, password resets must be done directly in the database:
+
+1. Generate a new password hash using bcrypt
+2. Update the `users` table with the new hash
+3. Or, ask another Owner to delete and re-invite you
+
+Self-service password reset is planned for a future release.
+
+### Why is my topology empty after discovery?
+
+Check these common issues:
+
+1. **Discovery failed**: View **Discover > Sessions** for errors
+2. **Wrong network selected**: Check topology options panel for network filter
+3. **All services hidden**: Check if service category filters are too aggressive
+4. **No hosts found**: Verify daemon can reach the network
+
+See [INSTALLATION.md](INSTALLATION.md#troubleshooting) for more troubleshooting steps.
+
+---
+
+**Need help?** Join our [Discord](https://discord.gg/b7ffQr8AcZ) or [open an issue](https://github.com/mayanayza/netvisor/issues/new).