#Network Dashboard

For Arabic version, see README_AR.md

A modern dashboard for managing and monitoring devices on your network with SQLite database.

##Features

• Network and device management
• Automatic and manual network scanning to discover devices
• Visual statistics display
• Complete tag management
• SQLite database
• Multi-language support (Arabic/English) with easy switching
• Dark/Light mode
• Favorites and groups management (create, edit, delete, reorder)
• Authentication system (Admin and Visitor), plus read-only API tokens for integrations
• Password change (Admin and Visitor)
• Detailed network view with device grouping
• Comprehensive statistics (online/offline devices)
• Modern and responsive user interface
• Global search across hosts and networks
• Uptime dashboard with per-host history
• Device change history (IP / MAC / name / vendor moves) and alerts when an IP is taken over by another device
• Live updates over Server-Sent Events — open pages refresh themselves after a scan
• Auto-scan alerts (in-app toasts, optional browser notifications, webhook)
• Export/import JSON and scheduled server backups
• Installable app (web manifest + service worker with an offline app shell)
• MAC vendor (OUI) lookup and device classification on scan

---

Available Pages

-Setup Page - Initial password setup on first run -Login Page - User authentication -Networks List - View and manage all networks -Network View - Detailed view of a specific network with device grouping -Hosts List - View all devices across all networks -Favorites - Manage favorite devices and groups -Tags Management - Create and manage tags -Change Admin Password - Change administrator password -Change Visitor Password - Change visitor password -Settings - Version, changelog, notifications, export/import, webhook (admin)

---

Trying and running the app (Docker Compose)

The easiest way to try the app is Docker Compose, which builds the image from source automatically — no separate build step needed.

Goal	Command
Build and run (foreground logs)	docker compose up
Same, detached (background)	docker compose up -d
Stop containers	docker compose down
Stop and wipe app data (DB volume), then clean restart	docker compose down -v then docker compose up

Developers: to build the image manually instead, run docker build -t shabakati:latest . (or podman build), then docker compose up.

---

Production Deployment (Docker)

#1. Clone the repository
git clone <your-repository-url>
cd shabakati

#2. Copy .env.example to .env
cp .env.example .env

#3. Edit .env file and update the following values:
# ALLOWED_ORIGINS=http://your-ip:3001 or http://your-domain:3001
# BASE_URL=http://your-ip:3001 or http://your-domain:3001
# Example: ALLOWED_ORIGINS=http://192.168.1.100:3001
# Example: BASE_URL=http://192.168.1.100:3001

#4. Save the file

#5. Build and run:
docker compose up -d

The application will be available at: http://your-ip:3001 or http://your-domain:3001

First run: initial setup is protected by a one-time setup token. View it in the server logs with docker compose logs app, or pre-set it with SETUP_TOKEN in .env (openssl rand -hex 24). Enter it on the setup page along with the two passwords.

###Upgrade without losing data

docker compose down
docker compose up -d --build

Do not use docker compose down -v unless you intend to wipe the database volume.

Check the running version in the app: Settings (user menu) or GET /api/health { "version": "…" }.

---

Operations (production)

Feature	How to configure
JWT signing	Required in production: JWT_SECRET in .env (openssl rand -base64 48)
Webhook alerts	Admin Settings Webhook URL, or WEBHOOK_URL in .env (env wins)
Scheduled backup	BACKUP_INTERVAL_HOURS=24 (0 = off), BACKUP_RETENTION_COUNT=7, optional BACKUP_DIR
Manual backup	Admin Settings Export / “Backup now”
Uptime tracking	Automatic on scan; view Uptime in the nav bar
Auto-scan notifications	Pushed to open pages over SSE the moment a scan finds changes; optional browser notifications in Settings
Reverse proxy	Set TRUST_PROXY=1 when behind nginx/Traefik

Webhook payload example (event: auto_scan_alert):

{
 "event": "auto_scan_alert",
 "networkId": 1,
 "networkName": "LAN",
 "newDevicesCount": 2,
 "disconnectedCount": 1,
 "timestamp": "2026-05-21T12:00:00.000Z"
}

---

Read-only API tokens

Admin Settings → Read-only API tokens issues tokens for scripts, dashboards or Home Assistant. The value is shown once; only its hash is stored, and a token can only ever read data — any write still requires an admin session.

# either header works
curl -H "Authorization: Bearer shk_…" http://your-ip:3001/api/hosts
curl -H "X-API-Key: shk_…"             http://your-ip:3001/api/hosts

Revoke a token at any time from the same panel; it stops working immediately.

---

Development Mode

#1. Install Node.js 24 LTS (if not already installed)

#2. Install dependencies
(cd web && npm install)
(cd server && npm install)

#3. Navigate to scripts folder and run the script
cd scripts
./dev.sh

After running, the application will be available at: -Frontend: http://localhost:5173 -API: http://localhost:3001/api

---

Reset Database

cd server
node resetDatabase.js

---

Add Admin User

To add a new admin user:

cd server
node addAdmin.js [username] [password]

Or using environment variable:

cd server
ADMIN_PASSWORD=yourpassword node addAdmin.js [username]

Example:

cd server
node addAdmin.js admin mypassword123

---

Dependencies

###Frontend -React 18.3.1 -React DOM 18.3.1 -React Router DOM 6.30.4 -Vite 7.3.5 (Build tool) -Recharts 3.10.1 (Charts)

###Backend -Express 4.22.2 -SQLite (better-sqlite3 12.11.1) -bcrypt 6.0.0 (Password hashing) -jsonwebtoken 9.0.3 (Authentication) -winston 3.19.0 (Logging) -ping 1.0.0 (Host checking)

###Requirements -Node.js 24 LTS or later

---

License

See LICENSE file for details.