monoadmin/the-other-dude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update documentation for v9.7.2 — setup CLI, navigation, UI scale

Browse Source 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jason Staack
2026-03-21 16:19:21 -05:00
parent 958571c26a
commit ddb4ce2512
5 changed files with 81 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
README.md
View File

@@ -1,6 +1,6 @@
# The Other Dude
**Self-hosted MikroTik fleet management for MSPs.**
**Self-hosted MikroTik fleet management.**
> **Warning**
> This software is in active development and testing. It is **not yet ready for production use**. APIs, database schemas, and features may change without notice. Use at your own risk.
@@ -81,6 +81,16 @@ The setup wizard handles everything interactively:
- Docker image builds
- Stack startup and health checks
For CI/CD or headless servers, pass `--non-interactive` with the required flags:
```bash
python3 setup.py --non-interactive \
--postgres-password 'MyP@ss!' \
--domain tod.example.com \
--admin-email admin@example.com \
--no-telemetry --yes
```
On first launch, the web UI walks you through enrolling your Secret Key, adding your
first organization, and onboarding your first device.
@@ -111,6 +121,6 @@ For support: [support@theotherdude.net](mailto:support@theotherdude.net) — sup
## The Name
"The Other Dude" -- because every MSP needs one. When the network is down at 2 AM
"The Other Dude" -- because every network team needs one. When the network is down at 2 AM
and someone has to fix it, TOD is the other dude on the job. The Big Lebowski inspired,
the rug really ties the room together.

2
docs/CONFIGURATION.md
View File

@@ -9,7 +9,7 @@ TOD uses Pydantic Settings for configuration. All values can be set via environm
| Variable | Default | Description |
|----------|---------|-------------|
| `APP_NAME` | `TOD - The Other Dude` | Application display name |
| `APP_VERSION` | `9.7.0` | Semantic version string (see VERSION file at project root) |
| `APP_VERSION` | `9.7.2` | Semantic version string (see VERSION file at project root) |
| `ENVIRONMENT` | `dev` | Runtime environment: `dev`, `staging`, or `production` |
| `DEBUG` | `false` | Enable debug mode |
| `CORS_ORIGINS` | `http://localhost:3000,http://localhost:5173,http://localhost:8080` | Comma-separated list of allowed CORS origins |

26
docs/DEPLOYMENT.md
View File

@@ -25,6 +25,32 @@ TOD (The Other Dude) is a containerized fleet management platform for RouterOS d
## Quick Start
### Automated Setup (Recommended)
The setup wizard handles all configuration interactively:
```bash
git clone https://github.com/staack/the-other-dude.git tod
cd tod
python3 setup.py
```
For CI/CD pipelines or headless servers, the wizard supports non-interactive mode:
```bash
python3 setup.py --non-interactive \
--postgres-password 'MyP@ss!' \
--domain tod.example.com \
--admin-email admin@example.com \
--no-telemetry --yes
```
Available flags: `--non-interactive`, `--postgres-password`, `--admin-email`, `--admin-password`, `--domain`, `--smtp-host`, `--smtp-port`, `--smtp-user`, `--smtp-password`, `--smtp-from`, `--smtp-tls`, `--no-smtp-tls`, `--proxy caddy|nginx|apache|haproxy|traefik|skip`, `--telemetry`, `--no-telemetry`, `--yes`/`-y`. The wizard also handles EOFError gracefully when stdin is not a TTY.
### Manual Setup
If you prefer manual configuration, follow the steps below.
### 1. Clone and Configure
```bash

16
docs/README.md
View File

@@ -2,7 +2,7 @@
**Fleet management platform for MikroTik RouterOS.**
Monitor routers, detect configuration drift, manage backups, and safely push configuration changes across hundreds of devices. Built for MSPs (Managed Service Providers) and network engineers managing MikroTik fleets.
Monitor routers, detect configuration drift, manage backups, and safely push configuration changes across hundreds of devices. Built for network engineers and service providers managing MikroTik fleets.
The Other Dude is a self-hosted, multi-tenant platform (one installation serves multiple organizations, each with fully isolated data) that gives you centralized visibility, configuration management, real-time monitoring, and zero-knowledge security across your entire MikroTik fleet -- from a single pane of glass.
@@ -68,7 +68,7 @@ The Other Dude is a self-hosted, multi-tenant platform (one installation serves
- **API Keys** -- Generate API keys (prefixed `mktp_`) for automation and integrations. Keys are shown only once at creation.
- **Firmware Management** -- Track RouterOS versions across your fleet, plan upgrades, and push firmware updates.
- **Maintenance Windows** -- Schedule maintenance periods with automatic alert suppression.
- **Setup Wizard** -- Guided 3-step onboarding for first-time deployment.
- **Setup Wizard** -- Guided 3-step onboarding for first-time deployment. Supports `--non-interactive` mode for headless and CI/CD environments.
### UX
@@ -156,6 +156,18 @@ python3 setup.py
The setup wizard configures your database, generates encryption keys, initializes the secret management service (OpenBao), sets up your reverse proxy, builds the Docker images, and starts everything. No manual `.env` editing required.
For CI/CD pipelines or headless servers, the wizard supports non-interactive mode:
```bash
python3 setup.py --non-interactive \
--postgres-password 'MyP@ss!' \
--domain tod.example.com \
--admin-email admin@example.com \
--no-telemetry --yes
```
Available flags: `--non-interactive`, `--postgres-password`, `--admin-email`, `--admin-password`, `--domain`, `--smtp-host`, `--smtp-port`, `--smtp-user`, `--smtp-password`, `--smtp-from`, `--smtp-tls`, `--no-smtp-tls`, `--proxy caddy|nginx|apache|haproxy|traefik|skip`, `--telemetry`, `--no-telemetry`, `--yes`/`-y`. The wizard also handles EOFError gracefully when stdin is not a TTY.
Three environment profiles are available:
| Environment | Frontend | API | Notes |

62
docs/USER-GUIDE.md
View File

@@ -1,6 +1,6 @@
# TOD - The Other Dude: User Guide
Managed Service Provider (MSP) fleet management platform for MikroTik RouterOS devices.
Fleet management platform for MikroTik RouterOS devices.
---
@@ -28,51 +28,43 @@ You can always add more organizations and devices later from the sidebar.
## Navigation
TOD uses a collapsible sidebar with four sections. Press `[` to toggle the sidebar between expanded (240px) and collapsed (48px) views. On mobile, the sidebar opens as an overlay.
TOD uses a collapsible sidebar organized into task-based sections. Press `[` to toggle the sidebar between expanded (240px) and collapsed (48px) views. On mobile, the sidebar opens as an overlay.
### Fleet
The sidebar footer contains the theme toggle (dark/light), connection status indicator, logout button, and UI scale selector. For super_admin users, the tenant selector is in the sidebar header.
### Operate
| Item | Description |
|------|-------------|
| **Dashboard** | Overview of your fleet with device status cards, active alerts, metrics sparklines, and "APs Needing Attention" wireless health card. The landing page after login. |
| **Overview** | Overview of your fleet with device status cards, active alerts, metrics sparklines, and "APs Needing Attention" wireless health card. The landing page after login. |
| **Devices** | Fleet table with search, sort, and filter. Click any device row to open its detail page. |
| **Sites** | Tower and site management -- organize devices by physical location with sectors, health monitoring, wireless links, and site-scoped alerts. |
| **Wireless Links** | Fleet-wide view of all discovered AP-to-CPE wireless connections with signal, CCQ, TX/RX rates, and link state. |
| **Alerts** | Live alert feed with filtering by severity (info, warning, critical) and acknowledgment actions. |
| **Wireless** | Fleet-wide view of all discovered AP-to-CPE wireless connections with signal, CCQ, TX/RX rates, and link state. |
| **Map** | Geographic fleet map with status-colored markers and automatic clustering. Devices with coordinates appear on the map; clusters reflect aggregate health (green = all online, red = all offline, amber = mixed). |
### Manage
### Act
| Item | Description |
|------|-------------|
| **Config Editor** | Browse and edit RouterOS configuration paths in real-time. Select a device from the header dropdown. |
| **Batch Config** | Apply configuration changes across multiple devices simultaneously using templates. |
| **Bulk Commands** | Execute RouterOS CLI commands across selected devices in bulk. |
| **Config** | Browse and edit RouterOS configuration paths in real-time. Select a device from the header dropdown. |
| **Templates** | Create and manage reusable configuration templates. |
| **Firmware** | Check for RouterOS updates and schedule firmware upgrades across your fleet. |
| **Maintenance** | Schedule maintenance windows to suppress alerts during planned work. |
| **VPN** | WireGuard VPN tunnel management -- create, deploy, and monitor tunnels between devices. |
| **Commands** | Execute RouterOS CLI commands across selected devices in bulk. |
### Low-Frequency (bottom of sidebar)
| Item | Description |
|------|-------------|
| **Organizations** | Create and manage tenants for multi-tenant operation. Each tenant's data is fully isolated -- users in one organization cannot see another's devices or data. |
| **Certificates** | Internal Certificate Authority management -- generate, deploy, and rotate TLS certificates for your devices. |
### Monitor
| Item | Description |
|------|-------------|
| **Topology** | Interactive network map showing device connections and shared subnets, with automatic layout for readability. |
| **Alerts** | Live alert feed with filtering by severity (info, warning, critical) and acknowledgment actions. |
| **VPN** | WireGuard VPN tunnel management -- create, deploy, and monitor tunnels between devices. |
| **Alert Rules** | Define threshold-based alert rules on device metrics with configurable severity and notification channels. |
| **Audit Trail** | Immutable, append-only log of all operations -- configuration changes, logins, user management, and admin actions. |
| **Transparency** | KMS access event dashboard showing encryption key usage across your organization (admin only). |
| **Maintenance** | Schedule maintenance windows to suppress alerts during planned work. |
| **Settings** | System configuration and profile settings. |
| **Audit Log** | Immutable, append-only log of all operations -- configuration changes, logins, user management, and admin actions. |
| **Reports** | Generate and export PDF reports: fleet summary, device health, compliance, and SLA. |
### Admin
| Item | Description |
|------|-------------|
| **Users** | User management with role-based access control (RBAC). Assign roles: super_admin, admin, operator, viewer. |
| **Organizations** | Create and manage tenants for multi-tenant MSP operation. Each tenant's data is fully isolated — users in one organization cannot see another's devices or data. |
| **API Keys** | Generate and manage programmatic access tokens (prefixed `mktp_`) with operator-level permissions. |
| **Settings** | System configuration, theme toggle (dark/light), and profile settings. |
| **About** | Platform version, feature summary, and project information. |
---
## Keyboard Shortcuts
@@ -227,15 +219,17 @@ Device credentials (RouterOS username/password) are encrypted at rest and only d
---
## Theme
## Theme & UI Scale
TOD supports dark and light modes:
- **Dark mode** (default) uses the Midnight Slate palette.
- **Light mode** provides a clean, high-contrast alternative.
- Toggle in **Settings** or let the portal follow your system preference.
- Toggle using the theme button in the **sidebar footer**, or let the portal follow your system preference.
- The command palette and all UI components adapt to the active theme.
A **UI scale selector** is available in the sidebar footer with three options: 100%, 110%, and 125%. This adjusts the base font size and layout density across the entire interface. Your preference is saved per browser.
---
## Tower & Site Management
@@ -244,7 +238,7 @@ Sites represent physical locations in your network -- towers, rooftops, equipmen
### Creating a Site
1. Navigate to **Fleet > Sites** in the sidebar.
1. Navigate to **Sites** in the sidebar.
2. Click **New Site**.
3. Fill in the site details:
- **Name** (required) -- a descriptive label for the location (e.g., "North Ridge Tower").
@@ -315,7 +309,7 @@ Link states transition automatically based on poll results and missed-poll count
There are two ways to view wireless links:
- **Fleet-wide**: Navigate to **Fleet > Wireless Links** in the sidebar. This shows all discovered links across your organization, filterable by state (active, degraded, down, stale).
- **Fleet-wide**: Navigate to **Wireless** in the sidebar. This shows all discovered links across your organization, filterable by state (active, degraded, down, stale).
- **Per-site**: Open a site detail page and switch to the **Links** tab. This shows only the links associated with devices assigned to that site.
Both views group links by AP device. Each CPE row shows signal strength (dBm), CCQ percentage, TX/RX data rates, link state, and time since last seen.
@@ -361,7 +355,7 @@ Alert events appear in the site's Alerts tab with timestamps, severity, the trig
The fleet map provides a geographic view of all devices that have coordinates assigned (either directly on the device or inherited from their site).
- Navigate to **Fleet > Map** in the sidebar.
- Navigate to **Map** in the sidebar.
- Devices appear as color-coded markers: **green** for online, **red** for offline.
- When devices are geographically close, they automatically cluster into numbered circles. Cluster color reflects aggregate health: green if all devices in the cluster are online, red if all are offline, and amber if mixed.
- Click a cluster to zoom in and see individual markers. Click a device marker to see its status summary and link to its detail page.