docs: add complete installation guide (INSTALL.md)
Step-by-step guide covering: system setup, tenant creation, TecDoc catalog import, inventory CSV import, peer-to-peer config, Gunicorn service, WhatsApp bridge, troubleshooting, and useful commands. Compatible with Raspberry Pi OS, Debian, and Ubuntu. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
401
INSTALL.md
Normal file
401
INSTALL.md
Normal file
@@ -0,0 +1,401 @@
|
||||
# Nexus Autoparts — Guia de Instalacion
|
||||
|
||||
Guia paso a paso para instalar una instancia de Nexus Autoparts POS en un servidor nuevo.
|
||||
|
||||
Compatible con: **Raspberry Pi OS**, **Debian**, **Ubuntu**. Para Windows usar WSL.
|
||||
|
||||
---
|
||||
|
||||
## Requisitos minimos
|
||||
|
||||
| Componente | Minimo | Recomendado |
|
||||
|---|---|---|
|
||||
| RAM | 2 GB | 4 GB |
|
||||
| Almacenamiento | 16 GB | 32 GB |
|
||||
| SO | Raspberry Pi OS / Debian 12+ / Ubuntu 22+ | Debian 13 |
|
||||
| Python | 3.11+ | 3.13 |
|
||||
| PostgreSQL | 14+ | 16 |
|
||||
| Node.js | 18+ | 20 |
|
||||
|
||||
---
|
||||
|
||||
## Paso 1 — Clonar el repositorio
|
||||
|
||||
```bash
|
||||
sudo apt-get update && sudo apt-get install -y git
|
||||
cd /home
|
||||
sudo git clone https://git.consultoria-as.com/consultoria-as/Autoparts-DB.git Autopartes
|
||||
sudo chown -R $(whoami):$(whoami) /home/Autopartes
|
||||
cd /home/Autopartes
|
||||
```
|
||||
|
||||
Si el certificado SSL da problemas:
|
||||
|
||||
```bash
|
||||
GIT_SSL_VERIFY=false sudo git clone https://git.consultoria-as.com/consultoria-as/Autoparts-DB.git Autopartes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Paso 2 — Ejecutar el script de instalacion
|
||||
|
||||
El script instala automaticamente: PostgreSQL, Python, Node.js, ffmpeg, todas las dependencias de pip, crea la base de datos, el tenant, el empleado owner y configura Gunicorn como servicio del sistema.
|
||||
|
||||
```bash
|
||||
sudo bash /home/Autopartes/scripts/setup_instance.sh "NOMBRE_NEGOCIO" "ID_INSTANCIA" "PIN"
|
||||
```
|
||||
|
||||
**Parametros:**
|
||||
|
||||
| Parametro | Descripcion | Ejemplo |
|
||||
|---|---|---|
|
||||
| NOMBRE_NEGOCIO | Nombre de la refaccionaria | `"Refacciones El Toro"` |
|
||||
| ID_INSTANCIA | Identificador unico (sin espacios ni acentos) | `"refac-eltoro"` |
|
||||
| PIN | PIN de 4 digitos para el login del dueno | `"1234"` |
|
||||
|
||||
**Ejemplo completo:**
|
||||
|
||||
```bash
|
||||
sudo bash /home/Autopartes/scripts/setup_instance.sh "Refacciones El Toro" "refac-eltoro" "1234"
|
||||
```
|
||||
|
||||
Al terminar, el script muestra:
|
||||
- El tenant ID asignado
|
||||
- El PIN del owner
|
||||
- La IP local del servidor
|
||||
- Instrucciones para arrancar
|
||||
|
||||
**Anota el tenant_id** — lo necesitas para los siguientes pasos.
|
||||
|
||||
---
|
||||
|
||||
## Paso 3 — Importar el catalogo TecDoc
|
||||
|
||||
El catalogo de partes (1.5M+ partes OEM, 304K aftermarket, 15.8M cross-references) vive en la base de datos `nexus_autoparts`. Si esta es tu primera instalacion, necesitas cargar los datos desde un dump.
|
||||
|
||||
### Opcion A — Dump desde otra instancia
|
||||
|
||||
Desde la maquina que YA tiene el catalogo:
|
||||
|
||||
```bash
|
||||
# Exportar (en la maquina origen)
|
||||
pg_dump -U nexus -h localhost nexus_autoparts > /tmp/nexus_catalog.sql
|
||||
|
||||
# Copiar al nuevo servidor (via USB, SCP, o red)
|
||||
scp /tmp/nexus_catalog.sql usuario@IP_NUEVA:/tmp/
|
||||
```
|
||||
|
||||
En el nuevo servidor:
|
||||
|
||||
```bash
|
||||
PGPASSWORD=nexus_autoparts_2026 psql -U nexus -h localhost -d nexus_autoparts < /tmp/nexus_catalog.sql
|
||||
```
|
||||
|
||||
### Opcion B — Sin catalogo (solo inventario local)
|
||||
|
||||
Si no necesitas el catalogo TecDoc (solo vas a cargar el inventario de la refaccionaria), salta este paso. El POS funciona sin el catalogo — simplemente el buscador de partes OEM no tendra datos.
|
||||
|
||||
---
|
||||
|
||||
## Paso 4 — Importar inventario
|
||||
|
||||
Prepara un archivo CSV con el inventario de la refaccionaria. Columnas aceptadas (los nombres son flexibles):
|
||||
|
||||
```csv
|
||||
numero_de_parte,nombre,marca,precio,existencia
|
||||
FO-1234,Filtro de Aceite Tsuru,FRAM,185.50,12
|
||||
BP-5678,Bujia NGK Sentra,NGK,45.00,50
|
||||
BA-9012,Balata Delantera Jetta,WAGNER,320.00,8
|
||||
```
|
||||
|
||||
**Columnas requeridas:** `numero_de_parte` (o `codigo`, `clave`, `sku`), `nombre` (o `descripcion`)
|
||||
|
||||
**Columnas opcionales:** `marca`, `precio` (o `precio_1`), `existencia` (o `stock`, `cantidad`), `costo`, `precio_2`, `precio_3`, `categoria`, `ubicacion`, `codigo_barras`
|
||||
|
||||
El importador acepta nombres en espanol, ingles, y formato SICAR.
|
||||
|
||||
### Primero verificar (dry run):
|
||||
|
||||
```bash
|
||||
cd /home/Autopartes/pos
|
||||
python3 ../scripts/import_inventory.py --tenant=TENANT_ID --csv=ruta/al/inventario.csv --dry-run
|
||||
```
|
||||
|
||||
### Importar de verdad:
|
||||
|
||||
```bash
|
||||
python3 ../scripts/import_inventory.py --tenant=TENANT_ID --csv=ruta/al/inventario.csv
|
||||
```
|
||||
|
||||
Si el CSV tiene codificacion Latin-1 (comun en archivos de SICAR):
|
||||
|
||||
```bash
|
||||
python3 ../scripts/import_inventory.py --tenant=TENANT_ID --csv=inventario.csv --encoding=latin-1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Paso 5 — Configurar peers (red de bodegas)
|
||||
|
||||
Para que esta instancia pueda ver el inventario de las otras refaccionarias en la red, edita el archivo de peers:
|
||||
|
||||
```bash
|
||||
nano /home/Autopartes/pos/peers.json
|
||||
```
|
||||
|
||||
Ejemplo con 2 peers:
|
||||
|
||||
```json
|
||||
{
|
||||
"instance_name": "Refacciones El Toro",
|
||||
"instance_id": "refac-eltoro",
|
||||
"tenant_id": 12,
|
||||
"peers": [
|
||||
{
|
||||
"name": "Refacciones La Esquina",
|
||||
"url": "http://192.168.10.20:5001",
|
||||
"enabled": true
|
||||
},
|
||||
{
|
||||
"name": "AutoPartes Central",
|
||||
"url": "http://192.168.10.30:5001",
|
||||
"enabled": true
|
||||
}
|
||||
],
|
||||
"peer_timeout_seconds": 3
|
||||
}
|
||||
```
|
||||
|
||||
**Importante:** El `tenant_id` debe coincidir con el que te dio el script de instalacion en el Paso 2.
|
||||
|
||||
---
|
||||
|
||||
## Paso 6 — Arrancar el servicio
|
||||
|
||||
```bash
|
||||
# Arrancar
|
||||
sudo systemctl start nexus-pos
|
||||
|
||||
# Verificar que esta corriendo
|
||||
sudo systemctl status nexus-pos
|
||||
|
||||
# Ver logs en tiempo real
|
||||
sudo journalctl -u nexus-pos -f
|
||||
```
|
||||
|
||||
Para que arranque automaticamente al encender la maquina:
|
||||
|
||||
```bash
|
||||
sudo systemctl enable nexus-pos
|
||||
```
|
||||
|
||||
### Arranque manual (sin Gunicorn):
|
||||
|
||||
```bash
|
||||
cd /home/Autopartes/pos
|
||||
python3 app.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Paso 7 — Verificar
|
||||
|
||||
Desde cualquier dispositivo en la misma red (PC, tablet, celular), abre un navegador:
|
||||
|
||||
```
|
||||
http://IP_DEL_SERVIDOR:5001/pos/login
|
||||
```
|
||||
|
||||
Login con el PIN que configuraste en el Paso 2.
|
||||
|
||||
### Verificar la salud del sistema:
|
||||
|
||||
```bash
|
||||
curl http://localhost:5001/pos/health
|
||||
# Debe responder: {"status": "ok"}
|
||||
|
||||
curl http://localhost:5001/pos/api/peer/health
|
||||
# Debe responder con el nombre de la instancia y conteo de inventario
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Paso 8 — WhatsApp (opcional)
|
||||
|
||||
Para vincular un numero de WhatsApp al chatbot IA:
|
||||
|
||||
1. Arranca el bridge de WhatsApp:
|
||||
|
||||
```bash
|
||||
cd /opt/whatsapp-bridge
|
||||
npm install
|
||||
nohup node server.js > /tmp/wa-bridge.log 2>&1 &
|
||||
```
|
||||
|
||||
2. Abre el POS en el navegador → seccion WhatsApp
|
||||
3. Click "Conectar WhatsApp"
|
||||
4. Escanea el QR con el telefono que quieres vincular
|
||||
|
||||
### Configurar el bridge como servicio:
|
||||
|
||||
```bash
|
||||
sudo cat > /etc/systemd/system/nexus-whatsapp.service << 'EOF'
|
||||
[Unit]
|
||||
Description=Nexus WhatsApp Bridge
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
User=root
|
||||
WorkingDirectory=/opt/whatsapp-bridge
|
||||
ExecStart=/usr/bin/node server.js
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable nexus-whatsapp
|
||||
sudo systemctl start nexus-whatsapp
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Comandos utiles
|
||||
|
||||
| Comando | Descripcion |
|
||||
|---|---|
|
||||
| `sudo systemctl start nexus-pos` | Arrancar el POS |
|
||||
| `sudo systemctl stop nexus-pos` | Detener el POS |
|
||||
| `sudo systemctl restart nexus-pos` | Reiniciar el POS |
|
||||
| `sudo systemctl status nexus-pos` | Ver estado |
|
||||
| `sudo journalctl -u nexus-pos -f` | Ver logs en vivo |
|
||||
| `sudo systemctl start nexus-whatsapp` | Arrancar WhatsApp bridge |
|
||||
| `curl localhost:5001/pos/health` | Verificar salud del POS |
|
||||
| `curl localhost:21465/status` | Verificar WhatsApp bridge |
|
||||
|
||||
---
|
||||
|
||||
## Estructura de archivos
|
||||
|
||||
```
|
||||
/home/Autopartes/
|
||||
├── pos/ # Aplicacion Flask (POS)
|
||||
│ ├── app.py # Punto de entrada
|
||||
│ ├── config.py # Configuracion (DB, JWT, SMTP)
|
||||
│ ├── peers.json # Configuracion de peers (red)
|
||||
│ ├── blueprints/ # Endpoints REST
|
||||
│ ├── services/ # Logica de negocio
|
||||
│ ├── templates/ # Paginas HTML
|
||||
│ └── static/ # CSS, JS, imagenes
|
||||
├── dashboard/ # Servidor web publico (puerto 5000)
|
||||
│ ├── server.py
|
||||
│ ├── landing.html
|
||||
│ └── catalog-public.html
|
||||
├── scripts/ # Scripts de utilidad
|
||||
│ ├── setup_instance.sh # Instalacion automatica
|
||||
│ ├── import_inventory.py # Importar inventario CSV
|
||||
│ └── seed_marketplace.py # Datos de prueba marketplace
|
||||
├── sql/ # Migraciones de base de datos
|
||||
├── pitch/ # Pitch deck para inversionistas
|
||||
└── vehicle_database/ # Schema del catalogo de vehiculos
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Solucion de problemas
|
||||
|
||||
### El POS no arranca
|
||||
|
||||
```bash
|
||||
# Ver el error exacto
|
||||
sudo journalctl -u nexus-pos --no-pager -n 50
|
||||
|
||||
# Verificar que PostgreSQL esta corriendo
|
||||
sudo systemctl status postgresql
|
||||
|
||||
# Verificar que el puerto no esta ocupado
|
||||
sudo fuser 5001/tcp
|
||||
```
|
||||
|
||||
### No puedo acceder desde otro dispositivo
|
||||
|
||||
```bash
|
||||
# Verificar el firewall
|
||||
sudo ufw status
|
||||
# Si esta activo, abrir el puerto:
|
||||
sudo ufw allow 5001/tcp
|
||||
|
||||
# Verificar que el servicio escucha en todas las interfaces
|
||||
ss -tlnp | grep 5001
|
||||
# Debe mostrar 0.0.0.0:5001, NO 127.0.0.1:5001
|
||||
```
|
||||
|
||||
### El inventario no se importo correctamente
|
||||
|
||||
```bash
|
||||
# Verificar cuantos items hay
|
||||
cd /home/Autopartes/pos
|
||||
python3 -c "
|
||||
from tenant_db import get_tenant_conn
|
||||
conn = get_tenant_conn(TENANT_ID)
|
||||
cur = conn.cursor()
|
||||
cur.execute('SELECT COUNT(*) FROM inventory WHERE is_active = TRUE')
|
||||
print(cur.fetchone()[0], 'items en inventario')
|
||||
conn.close()
|
||||
"
|
||||
```
|
||||
|
||||
### WhatsApp no genera QR
|
||||
|
||||
```bash
|
||||
# Limpiar sesion anterior y reiniciar
|
||||
sudo rm -rf /opt/whatsapp-bridge/auth/
|
||||
sudo systemctl restart nexus-whatsapp
|
||||
# Esperar 10 segundos, luego revisar
|
||||
curl localhost:21465/status
|
||||
```
|
||||
|
||||
### Los peers no se ven entre si
|
||||
|
||||
```bash
|
||||
# Desde esta maquina, verificar que el peer responde
|
||||
curl http://IP_DEL_PEER:5001/pos/api/peer/health
|
||||
|
||||
# Si no responde, verificar:
|
||||
# 1. Que el POS del peer esta corriendo
|
||||
# 2. Que estan en la misma red
|
||||
# 3. Que el firewall permite puerto 5001
|
||||
ping IP_DEL_PEER
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Actualizaciones
|
||||
|
||||
Para actualizar el sistema a la ultima version:
|
||||
|
||||
```bash
|
||||
cd /home/Autopartes
|
||||
git pull origin main
|
||||
sudo systemctl restart nexus-pos
|
||||
```
|
||||
|
||||
Si hay migraciones de base de datos nuevas:
|
||||
|
||||
```bash
|
||||
# Aplicar migraciones al master
|
||||
PGPASSWORD=nexus_autoparts_2026 psql -U nexus -h localhost -d nexus_autoparts -f sql/marketplace_schema.sql
|
||||
|
||||
# Aplicar migraciones al tenant
|
||||
PGPASSWORD=nexus_autoparts_2026 psql -U nexus -h localhost -d tenant_NOMBRE -f sql/marketplace_tenant_users.sql
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Soporte
|
||||
|
||||
- **Email:** ialcarazsalazar@consultoria-as.com
|
||||
- **WhatsApp:** +52 664 217 0990
|
||||
- **Gitea:** https://git.consultoria-as.com/consultoria-as/Autoparts-DB
|
||||
Reference in New Issue
Block a user