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)
• 🔑 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
• 🔔 Auto-scan alerts (in-app toasts, optional browser notifications, webhook)
• 📤 Export/import JSON and scheduled server backups
• 📱 PWA install support
• 🏭 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 with the pre-built image published on GitHub Container Registry — no local build needed.

Goal	Command
Pull the latest image and run (foreground logs)	docker compose pull && docker compose up
Same, detached (background)	docker compose pull && 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 pull && docker compose up

Developers: to build the image from source instead, run docker build -t ghcr.io/balnaimi/shabakati:latest . (or podman build), then docker compose up.

---

🚀 Production Deployment (Docker)

# 1. Clone the repository
git clone https://github.com/balnaimi/Shabakati.git
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. Pull the pre-built image and run:
docker compose pull
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 pull
docker compose up -d

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	Toasts in the UI; 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"
}

---

💻 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.28.0
• Vite 7.2.7 (Build tool)

Backend

• Express 4.22.1
• SQLite (better-sqlite3 12.6.0)
• bcrypt 6.0.0 (Password hashing)
• jsonwebtoken 9.0.3 (Authentication)
• winston 3.19.0 (Logging)
• ping 1.0.0 (Host checking)
• validator 13.15.26 (Data validation)

Requirements

• Node.js 24 LTS or later

---

📄 License

See LICENSE file for details.