docs: add French and Spanish translations of README
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
+231
@@ -0,0 +1,231 @@
|
||||
# <img src="frontend/public/favicon.svg" width="22" height="22" alt="" /> Stupid Simple Network Inventory
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Aplicación web autoalojada para inventario manual de red y visualización de topología de red lógica.
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
- **i18n** — francés, inglés, español
|
||||
|
||||
## Stack
|
||||
|
||||
| Capa | Tecnología |
|
||||
|------|-----------|
|
||||
| Backend | FastAPI + SQLAlchemy + SQLite (Python 3.11) |
|
||||
| Frontend | Vue 3 + Vite, servido por Nginx |
|
||||
| Auth | JWT HS256, expiración 24h |
|
||||
| Runtime | Docker Compose |
|
||||
|
||||
---
|
||||
|
||||
## Inicio rápido
|
||||
|
||||
```bash
|
||||
# 1. Clonar y entrar en el proyecto
|
||||
git clone https://git.raspot.in/olivier/stupid-simple-network-inventory.git
|
||||
cd stupid-simple-network-inventory
|
||||
|
||||
# 2. Crear el directorio de datos propiedad del usuario actual
|
||||
mkdir -p db_data
|
||||
|
||||
# 3. Configurar el entorno (necesario para la propiedad correcta del bind-mount)
|
||||
cp .env.example .env
|
||||
# Editar .env:
|
||||
# DOCKER_UID / DOCKER_GID → resultado de: id -u && id -g
|
||||
# INITIAL_ADMIN_PASSWORD → definir para evitar el bootstrap admin/admin por defecto
|
||||
|
||||
# 4. Construir e iniciar
|
||||
docker compose --env-file .env up --build -d
|
||||
|
||||
# 5. Abrir http://localhost:8080 en el navegador
|
||||
```
|
||||
|
||||
### Primer inicio de sesión
|
||||
|
||||
| Caso | Credenciales | Comportamiento |
|
||||
|------|-------------|----------------|
|
||||
| `INITIAL_ADMIN_PASSWORD` definido | `admin` / `<tu contraseña>` | Inicio de sesión normal |
|
||||
| `INITIAL_ADMIN_PASSWORD` no definido | `admin` / `admin` | Cambio de contraseña obligatorio antes de acceder a la aplicación |
|
||||
|
||||
---
|
||||
|
||||
## Configuración
|
||||
|
||||
Toda la configuración se realiza mediante variables de entorno. Ver `.env.example` para la lista completa con descripciones.
|
||||
|
||||
| Variable | Por defecto | Descripción |
|
||||
|----------|-------------|-------------|
|
||||
| `SECRET_KEY` | auto-generada | Clave de firma JWT. Definir explícitamente en producción. |
|
||||
| `INITIAL_ADMIN_PASSWORD` | _(vacío)_ | Contraseña de bootstrap del admin. Si no se define, se usa `admin/admin` con cambio forzado. |
|
||||
| `ALLOWED_ORIGINS` | `*` | Orígenes CORS permitidos (separados por comas). Definir en tu dominio en producción. |
|
||||
| `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
|
||||
docker compose --env-file .env up --build -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Seguridad
|
||||
|
||||
### Gestión de secretos
|
||||
|
||||
Dos opciones según sus requisitos de seguridad.
|
||||
|
||||
#### Opción A — Secreto auto-generado (recomendado para nodo único)
|
||||
|
||||
Dejar `SECRET_KEY` sin definir (o vacío) en `.env`. En el primer arranque, el backend genera una clave hexadecimal aleatoria de 64 caracteres, la escribe en `db_data/secret_key.txt` con permisos **0600** y la reutiliza en cada reinicio posterior. El secreto nunca aparece en una variable de entorno, un archivo compose o un log.
|
||||
|
||||
```bash
|
||||
# .env — dejar la línea vacía o eliminarla
|
||||
SECRET_KEY=
|
||||
```
|
||||
|
||||
El único requisito es que `db_data/` esté respaldado (ya contiene la base de datos).
|
||||
|
||||
#### Opción B — Secreto mediante archivo Docker Compose
|
||||
|
||||
Almacena el secreto en un archivo en el host, fuera del control de versiones, y lo monta en el contenedor. El valor nunca aparece en una variable de entorno.
|
||||
|
||||
```bash
|
||||
# Generar y almacenar el secreto fuera del directorio del proyecto
|
||||
mkdir -p ~/.secrets
|
||||
python3 -c "import secrets; print(secrets.token_hex(32))" > ~/.secrets/topologie_secret_key
|
||||
chmod 600 ~/.secrets/topologie_secret_key
|
||||
```
|
||||
|
||||
Luego descomentar los bloques `secrets:` en `docker-compose.yml` (ver los comentarios en ese archivo) y eliminar `SECRET_KEY` de `.env`. Docker Compose fusiona la anulación automáticamente:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Rotación de clave
|
||||
|
||||
Para rotar el secreto JWT (invalida todas las sesiones activas):
|
||||
|
||||
```bash
|
||||
# Opción A — variable de entorno (recomendado)
|
||||
# Definir un nuevo SECRET_KEY en la configuración de despliegue y reiniciar
|
||||
|
||||
# Opción B — rotación por archivo
|
||||
docker compose stop backend
|
||||
rm db_data/secret_key.txt
|
||||
docker compose start backend
|
||||
# Todos los usuarios deberán iniciar sesión de nuevo
|
||||
```
|
||||
|
||||
### HTTPS
|
||||
|
||||
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;
|
||||
|
||||
ssl_certificate /etc/letsencrypt/live/inventory.example.com/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/inventory.example.com/privkey.pem;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:8080;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Para uso solo local, enlazar a loopback para evitar exposición accidental en la LAN:
|
||||
|
||||
```yaml
|
||||
# docker-compose.override.yml
|
||||
services:
|
||||
frontend:
|
||||
ports:
|
||||
- "127.0.0.1:8080:8080"
|
||||
```
|
||||
|
||||
### 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) |
|
||||
| `cap_drop: ALL` | ✓ | ✓ |
|
||||
| `cap_add: NET_RAW` | ✓ (ping) | — |
|
||||
| `no-new-privileges` | — ¹ | ✓ |
|
||||
| Healthcheck | ✓ | ✓ |
|
||||
|
||||
¹ Omitido en el backend: el ping usa file capabilities (`cap_net_raw=ep`); `no-new-privileges` suprimiría el bit efectivo del archivo e impediría al subproceso adquirir `CAP_NET_RAW` en su conjunto efectivo aunque el padre lo tenga en su conjunto permitido.
|
||||
|
||||
---
|
||||
|
||||
## Persistencia de datos
|
||||
|
||||
Todos los datos se almacenan en `./db_data/`:
|
||||
|
||||
| Archivo | Descripción |
|
||||
|---------|-------------|
|
||||
| `topology.db` | Base de datos SQLite |
|
||||
| `secret_key.txt` | Secreto JWT auto-generado (permisos 0600) |
|
||||
|
||||
**Copia de seguridad**: `cp -r db_data/ db_data.bak/`
|
||||
|
||||
**Restauración**: detener la stack, reemplazar `db_data/`, reiniciar.
|
||||
|
||||
---
|
||||
|
||||
## Desarrollo
|
||||
|
||||
### Tests del backend
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
pip install -r requirements.txt -r requirements-test.txt
|
||||
pytest tests/ -v
|
||||
```
|
||||
|
||||
### Dev local (sin Docker)
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
cd backend
|
||||
pip install -r requirements.txt
|
||||
uvicorn main:app --reload
|
||||
|
||||
# Frontend (terminal separada)
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev # Servidor dev Vite en :5173, proxifica /api/ hacia :8000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Arquitectura
|
||||
|
||||
Ver [`docs/architecture.md`](docs/architecture.md) para el flujo de solicitudes detallado, la configuración Docker y el modelo de autenticación.
|
||||
Reference in New Issue
Block a user