diff --git a/README.es.md b/README.es.md index ea93729..38ca7f5 100644 --- a/README.es.md +++ b/README.es.md @@ -1,4 +1,12 @@ -# Stupid Simple Network Inventory +
+ + + +# Stupid Simple Network Inventory + +**Aplicación web autoalojada para inventario de red y visualización de topología lógica** + +[English](README.md) · [Français](README.fr.md) ![Python](https://img.shields.io/badge/Python-3.11-3776AB?logo=python&logoColor=white) ![FastAPI](https://img.shields.io/badge/FastAPI-009688?logo=fastapi&logoColor=white) @@ -7,22 +15,26 @@ ![Nginx](https://img.shields.io/badge/Nginx-009639?logo=nginx&logoColor=white) ![Docker](https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=white) -Aplicación web autoalojada para inventario manual de red y visualización de topología de red lógica. +
+ +--- ![Vista de Topología](img/tpology.png) -## Características +--- -- **Inventario manual** — añade y gestiona dispositivos (18 tipos) con IPs, VLANs, descripciones y enlaces web opcionales -- **Vista de topología** — disposición en tarjetas por red (LAN / VLAN 802.1Q), con secciones WAN y puerta de enlace -- **Ping ICMP** — comprueba la accesibilidad de todos los hosts conocidos con un clic -- **Descubrimiento automático** — ping sweep + consulta PTR DNS en una subred para importar nuevos hosts -- **Autenticación** — inicio de sesión JWT con cambio de contraseña obligatorio en el primer uso -- **Modo oscuro** — alternancia entre tema claro y oscuro -- **Logos de fabricantes** — detección y visualización automáticas de logos de editores/fabricantes (Proxmox, Cisco, Synology, Docker, y más de 30 más) -- **i18n** — francés, inglés, español +## ✨ Características -## Stack +- 🗂️ **Inventario manual** — añade y gestiona dispositivos (18 tipos) con IPs, VLANs, descripciones y enlaces web opcionales +- 🗺️ **Vista de topología** — disposición en tarjetas por red (LAN / VLAN 802.1Q), con secciones WAN y puerta de enlace +- 📡 **Ping ICMP** — comprueba la accesibilidad de todos los hosts conocidos con un clic +- 🔍 **Descubrimiento automático** — ping sweep + consulta PTR DNS en una subred para importar nuevos hosts +- 🏷️ **Logos de fabricantes** — detección y visualización automáticas de logos de editores/fabricantes (Proxmox, Cisco, Synology, Docker, y más de 30 más) +- 🔐 **Autenticación** — inicio de sesión JWT con cambio de contraseña obligatorio en el primer uso +- 🌙 **Modo oscuro** — alternancia entre tema claro y oscuro +- 🌍 **i18n** — francés, inglés, español + +## 🛠️ Stack | Capa | Tecnología | |------|-----------| @@ -33,7 +45,7 @@ Aplicación web autoalojada para inventario manual de red y visualización de to --- -## Inicio rápido +## 🚀 Inicio rápido ```bash # 1. Clonar y entrar en el proyecto @@ -64,7 +76,7 @@ docker compose --env-file .env up --build -d --- -## Configuración +## ⚙️ Configuración Toda la configuración se realiza mediante variables de entorno. Ver `.env.example` para la lista completa con descripciones. @@ -76,8 +88,6 @@ Toda la configuración se realiza mediante variables de entorno. Ver `.env.examp | `BIND_ADDRESS` | `0.0.0.0` | Dirección IP de escucha. Definir en la interfaz frente al reverse proxy. | | `DOCKER_UID` / `DOCKER_GID` | `1000` | UID/GID para el proceso backend. Debe coincidir con el usuario propietario de `./db_data/`. | -### Usar .env con Docker Compose - ```bash cp .env.example .env # Editar .env — definir como mínimo DOCKER_UID, DOCKER_GID, INITIAL_ADMIN_PASSWORD @@ -86,7 +96,7 @@ docker compose --env-file .env up --build -d --- -## Seguridad +## 🔒 Seguridad ### Gestión de secretos @@ -120,8 +130,6 @@ Luego descomentar los bloques `secrets:` en `docker-compose.yml` (ver los coment docker compose up -d ``` ---- - ### Rotación de clave Para rotar el secreto JWT (invalida todas las sesiones activas): @@ -142,7 +150,6 @@ docker compose start backend Esta aplicación no termina TLS. Para uso en producción, colócala detrás de un reverse proxy que gestione HTTPS: ```nginx -# Ejemplo de reverse proxy nginx (externo, en el host o en un contenedor dedicado) server { listen 443 ssl; server_name inventory.example.com; @@ -172,8 +179,6 @@ services: ### Endurecimiento de contenedores -Los contenedores se ejecutan con privilegios reducidos: - | Medida | Backend | Frontend | |--------|---------|----------| | Usuario no-root | `DOCKER_UID:DOCKER_GID` (usuario host) | `nginx` (UID 101) | @@ -186,7 +191,7 @@ Los contenedores se ejecutan con privilegios reducidos: --- -## Persistencia de datos +## 💾 Persistencia de datos Todos los datos se almacenan en `./db_data/`: @@ -201,7 +206,7 @@ Todos los datos se almacenan en `./db_data/`: --- -## Desarrollo +## 🧑‍💻 Desarrollo ### Tests del backend @@ -227,6 +232,6 @@ npm run dev # Servidor dev Vite en :5173, proxifica /api/ hacia :8000 --- -## Arquitectura +## 🏗️ Arquitectura Ver [`docs/architecture.md`](docs/architecture.md) para el flujo de solicitudes detallado, la configuración Docker y el modelo de autenticación. diff --git a/README.fr.md b/README.fr.md index 54af534..6b27d2d 100644 --- a/README.fr.md +++ b/README.fr.md @@ -1,4 +1,12 @@ -# Stupid Simple Network Inventory +
+ + + +# Stupid Simple Network Inventory + +**Application web auto-hébergée pour l'inventaire réseau et la visualisation de topologie logique** + +[English](README.md) · [Español](README.es.md) ![Python](https://img.shields.io/badge/Python-3.11-3776AB?logo=python&logoColor=white) ![FastAPI](https://img.shields.io/badge/FastAPI-009688?logo=fastapi&logoColor=white) @@ -7,22 +15,26 @@ ![Nginx](https://img.shields.io/badge/Nginx-009639?logo=nginx&logoColor=white) ![Docker](https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=white) -Application web auto-hébergée pour l'inventaire manuel de réseau et la visualisation de topologie réseau logique. +
+ +--- ![Vue Topologie](img/tpology.png) -## Fonctionnalités +--- -- **Inventaire manuel** — ajout et gestion d'équipements (18 types) avec IPs, VLANs, descriptions et liens web optionnels -- **Vue topologie** — disposition en cards par réseau (LAN / VLAN 802.1Q), avec sections WAN et passerelle -- **Ping ICMP** — vérification de l'accessibilité de tous les hôtes connus en un clic -- **Découverte automatique** — ping sweep + lookup PTR DNS sur un sous-réseau pour importer de nouveaux hôtes -- **Authentification** — connexion JWT avec changement de mot de passe forcé à la première utilisation -- **Mode sombre** — bascule thème clair / sombre -- **Logos de marques** — détection et affichage automatiques des logos éditeurs/fabricants (Proxmox, Cisco, Synology, Docker, et plus de 30 autres) -- **i18n** — français, anglais, espagnol +## ✨ Fonctionnalités -## Stack +- 🗂️ **Inventaire manuel** — ajout et gestion d'équipements (18 types) avec IPs, VLANs, descriptions et liens web optionnels +- 🗺️ **Vue topologie** — disposition en cards par réseau (LAN / VLAN 802.1Q), avec sections WAN et passerelle +- 📡 **Ping ICMP** — vérification de l'accessibilité de tous les hôtes connus en un clic +- 🔍 **Découverte automatique** — ping sweep + lookup PTR DNS sur un sous-réseau pour importer de nouveaux hôtes +- 🏷️ **Logos de marques** — détection et affichage automatiques des logos éditeurs/fabricants (Proxmox, Cisco, Synology, Docker, et plus de 30 autres) +- 🔐 **Authentification** — connexion JWT avec changement de mot de passe forcé à la première utilisation +- 🌙 **Mode sombre** — bascule thème clair / sombre +- 🌍 **i18n** — français, anglais, espagnol + +## 🛠️ Stack | Couche | Technologie | |--------|------------| @@ -33,7 +45,7 @@ Application web auto-hébergée pour l'inventaire manuel de réseau et la visual --- -## Démarrage rapide +## 🚀 Démarrage rapide ```bash # 1. Cloner et entrer dans le projet @@ -64,7 +76,7 @@ docker compose --env-file .env up --build -d --- -## Configuration +## ⚙️ Configuration Toute la configuration se fait via des variables d'environnement. Voir `.env.example` pour la liste complète avec descriptions. @@ -76,8 +88,6 @@ Toute la configuration se fait via des variables d'environnement. Voir `.env.exa | `BIND_ADDRESS` | `0.0.0.0` | Adresse IP d'écoute. À définir sur l'interface face au reverse proxy. | | `DOCKER_UID` / `DOCKER_GID` | `1000` | UID/GID pour le processus backend. Doit correspondre à l'utilisateur propriétaire de `./db_data/`. | -### Utilisation de .env avec Docker Compose - ```bash cp .env.example .env # Éditer .env — définir au minimum DOCKER_UID, DOCKER_GID, INITIAL_ADMIN_PASSWORD @@ -86,7 +96,7 @@ docker compose --env-file .env up --build -d --- -## Sécurité +## 🔒 Sécurité ### Gestion des secrets @@ -120,8 +130,6 @@ Décommenter ensuite les blocs `secrets:` dans `docker-compose.yml` (voir les co docker compose up -d ``` ---- - ### Rotation de clé Pour faire tourner le secret JWT (invalide toutes les sessions actives) : @@ -142,7 +150,6 @@ docker compose start backend Cette application ne termine pas TLS. Pour un usage en production, placez-la derrière un reverse proxy gérant HTTPS : ```nginx -# Exemple de reverse proxy nginx (externe, sur l'hôte ou un conteneur dédié) server { listen 443 ssl; server_name inventory.example.com; @@ -172,8 +179,6 @@ services: ### Durcissement des conteneurs -Les conteneurs s'exécutent avec des privilèges réduits : - | Mesure | Backend | Frontend | |--------|---------|----------| | Utilisateur non-root | `DOCKER_UID:DOCKER_GID` (utilisateur hôte) | `nginx` (UID 101) | @@ -186,7 +191,7 @@ Les conteneurs s'exécutent avec des privilèges réduits : --- -## Persistance des données +## 💾 Persistance des données Toutes les données sont stockées dans `./db_data/` : @@ -201,7 +206,7 @@ Toutes les données sont stockées dans `./db_data/` : --- -## Développement +## 🧑‍💻 Développement ### Tests backend @@ -227,6 +232,6 @@ npm run dev # Serveur dev Vite sur :5173, proxifie /api/ vers :8000 --- -## Architecture +## 🏗️ Architecture Voir [`docs/architecture.md`](docs/architecture.md) pour le flux de requêtes détaillé, la configuration Docker et le modèle d'authentification. diff --git a/README.md b/README.md index 292db0e..71b4f64 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,12 @@ -# Stupid Simple Network Inventory +
+ + + +# Stupid Simple Network Inventory + +**Self-hosted network inventory and logical topology visualisation** + +[Français](README.fr.md) · [Español](README.es.md) ![Python](https://img.shields.io/badge/Python-3.11-3776AB?logo=python&logoColor=white) ![FastAPI](https://img.shields.io/badge/FastAPI-009688?logo=fastapi&logoColor=white) @@ -7,22 +15,26 @@ ![Nginx](https://img.shields.io/badge/Nginx-009639?logo=nginx&logoColor=white) ![Docker](https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=white) -Self-hosted web application for manual network inventory and logical network topology visualisation. +
+ +--- ![Topology view](img/tpology.png) -## Features +--- -- **Manual inventory** — add and manage devices (18 types) with IPs, VLANs, descriptions and optional web links -- **Topology view** — card-based layout per network (LAN / VLAN 802.1Q), with WAN and gateway sections -- **ICMP ping sweep** — check reachability of all known hosts in one click -- **Auto-discovery** — ping sweep + PTR DNS lookup on a subnet to import new hosts -- **Authentication** — JWT-based login with forced password change on first use -- **Dark mode** — light / dark theme toggle -- **Brand logos** — automatic detection and display of vendor/manufacturer logos (Proxmox, Cisco, Synology, Docker, and 30+ more) -- **i18n** — French, English, Spanish +## ✨ Features -## Stack +- 🗂️ **Manual inventory** — add and manage devices (18 types) with IPs, VLANs, descriptions and optional web links +- 🗺️ **Topology view** — card-based layout per network (LAN / VLAN 802.1Q), with WAN and gateway sections +- 📡 **ICMP ping sweep** — check reachability of all known hosts in one click +- 🔍 **Auto-discovery** — ping sweep + PTR DNS lookup on a subnet to import new hosts +- 🏷️ **Brand logos** — automatic detection and display of vendor logos (Proxmox, Cisco, Synology, Docker, 30+ more) +- 🔐 **Authentication** — JWT-based login with forced password change on first use +- 🌙 **Dark mode** — light / dark theme toggle +- 🌍 **i18n** — French, English, Spanish + +## 🛠️ Stack | Layer | Technology | |-------|-----------| @@ -33,7 +45,7 @@ Self-hosted web application for manual network inventory and logical network top --- -## Quick start +## 🚀 Quick start ```bash # 1. Clone and enter the project @@ -64,7 +76,7 @@ docker compose --env-file .env up --build -d --- -## Configuration +## ⚙️ Configuration All configuration is via environment variables. See `.env.example` for the full list with descriptions. @@ -76,8 +88,6 @@ All configuration is via environment variables. See `.env.example` for the full | `BIND_ADDRESS` | `0.0.0.0` | IP address to listen on. Set to the interface facing the reverse proxy. | | `DOCKER_UID` / `DOCKER_GID` | `1000` | UID/GID for the backend process. Must match the host user owning `./db_data/`. | -### Using .env with Docker Compose - ```bash cp .env.example .env # Edit .env — at minimum set DOCKER_UID, DOCKER_GID, INITIAL_ADMIN_PASSWORD @@ -86,7 +96,7 @@ docker compose --env-file .env up --build -d --- -## Security +## 🔒 Security ### Secret management @@ -120,8 +130,6 @@ Then uncomment the `secrets:` blocks in `docker-compose.yml` (see comments in th docker compose up -d ``` ---- - ### Key rotation To rotate the JWT secret (invalidates all active sessions): @@ -142,7 +150,6 @@ docker compose start backend This application does not terminate TLS. For production use, place it behind a reverse proxy that handles HTTPS: ```nginx -# Example nginx reverse-proxy (external, on the host or a dedicated container) server { listen 443 ssl; server_name inventory.example.com; @@ -172,8 +179,6 @@ services: ### Container hardening -The containers run with reduced privileges: - | Measure | Backend | Frontend | |---------|---------|----------| | Non-root user | `DOCKER_UID:DOCKER_GID` (host user) | `nginx` (UID 101) | @@ -186,7 +191,7 @@ The containers run with reduced privileges: --- -## Data persistence +## 💾 Data persistence All data is stored in `./db_data/`: @@ -201,7 +206,7 @@ All data is stored in `./db_data/`: --- -## Development +## 🧑‍💻 Development ### Backend tests @@ -227,6 +232,6 @@ npm run dev # Vite dev server on :5173, proxies /api/ to :8000 --- -## Architecture +## 🏗️ Architecture See [`docs/architecture.md`](docs/architecture.md) for the detailed request flow, Docker setup, and authentication model.