04 — Instalación paso a paso¶

Esta guía asume que ya tienes los prerrequisitos de 03-prerrequisitos.md.

Tiempo estimado: ~30 minutos.

1. Extraer el código¶

cd /home/blimxapp
unzip blimx-saas.zip -d saas
cd saas/chatbot-v3-workspace
sudo chown -R blimxapp:blimxapp .

A partir de aquí, asumimos que estás en /home/blimxapp/saas/chatbot-v3-workspace.

2. Crear base de datos PostgreSQL¶

sudo -u postgres psql <<EOF
CREATE DATABASE blimx_saas;
CREATE USER blimx_user WITH PASSWORD 'CAMBIA_ESTO_POR_UN_PASSWORD_LARGO';
GRANT ALL PRIVILEGES ON DATABASE blimx_saas TO blimx_user;
\c blimx_saas
GRANT ALL ON SCHEMA public TO blimx_user;
EOF

3. Configurar variables de entorno¶

Copia el template y rellénalo:

cp .env.example .env
nano .env

Variables mínimas obligatorias (todas en .env):

# Django core
SECRET_KEY=                 # genera con: python -c 'import secrets; print(secrets.token_urlsafe(50))'
DEBUG=False
ALLOWED_HOSTS=app.tudominio.com,widget.tudominio.com

# PostgreSQL
DB_NAME=blimx_saas
DB_USER=blimx_user
DB_PASSWORD=                # el que pusiste arriba
DB_HOST=127.0.0.1
DB_PORT=5432

# JWT
JWT_ACCESS_TOKEN_LIFETIME=60     # minutos
JWT_REFRESH_TOKEN_LIFETIME=1440  # minutos (24h)

# Email (SMTP)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=tu-email@gmail.com
EMAIL_HOST_PASSWORD=         # App Password de Gmail
DEFAULT_FROM_EMAIL=noreply@tudominio.com

# CORS (frontend dashboard URL)
FRONTEND_URL=https://app.tudominio.com
CORS_ALLOWED_ORIGINS=https://app.tudominio.com,https://widget.tudominio.com

# Stripe
STRIPE_SECRET_KEY=sk_live_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx       # se completa tras configurar el webhook
STRIPE_DASHBOARD_BASE_URL=https://app.tudominio.com
STRIPE_SUCCESS_URL=https://app.tudominio.com/dashboard/bots/{slug}/subscription?checkout=success&session_id={CHECKOUT_SESSION_ID}
STRIPE_CANCEL_URL=https://app.tudominio.com/dashboard/bots/{slug}/subscription?checkout=cancel
STRIPE_PORTAL_RETURN_URL=https://app.tudominio.com/dashboard

# OpenAI (no usado en runtime del demo, pero el schema lo soporta para futuro)
# OPENAI_API_KEY=sk-...

Plantilla completa con descripciones en .saas-docs/infra/env.example.

4. Backend Django: virtualenv + dependencias¶

cd backend_django
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

5. Migraciones + superusuario + seed de planes¶

# Crear todas las tablas (Django + tablas legacy se crean por SQL si no existen)
python manage.py migrate

# Crear el superusuario que accede a /admin/ y al panel /superadmin
python manage.py createsuperuser

# Sembrar los 3 planes (Free / Starter / Pro) en la tabla `plans`
python manage.py shell <<'PY'
from api.models import Plan
plans = [
    {"name": "Free",    "price_amount": 0,    "currency": "usd",
     "stripe_price_id": "",  # vacío → no crea checkout
     "features": {"limits": {"faqs_per_language": 20, "languages": 1, "branding": True}},
     "is_active": True},
    {"name": "Starter", "price_amount": 1900, "currency": "usd",
     "stripe_price_id": "price_xxx_starter",  # tu Price ID de Stripe
     "features": {"limits": {"faqs_per_language": 100, "languages": 2, "branding": True}},
     "is_active": True},
    {"name": "Pro",     "price_amount": 4900, "currency": "usd",
     "stripe_price_id": "price_xxx_pro",
     "features": {"limits": {"faqs_per_language": 500, "languages": 5, "branding": False}},
     "is_active": True},
]
for p in plans:
    Plan.objects.update_or_create(name=p["name"], defaults=p)
print("Planes creados:", Plan.objects.count())
PY

6. Recoger archivos estáticos de Django (admin)¶

python manage.py collectstatic --noinput

Esto copia los assets del Django admin a backend_django/staticfiles/.

7. Build del frontend cliente (`apps/dashboard`)¶

cd ../apps/dashboard
npm install
npm run build
# Genera apps/dashboard/dist/

8. Build del frontend superadmin (`apps/superadmin`)¶

cd ../superadmin
npm install
npm run build
# Genera apps/superadmin/dist/

9. Build del widget embebible (`static/v3`)¶

cd ../../static/v3
npm install
node build.js
# Genera static/v3/dist/blimx-chatbot.min.js + .min.css + blimx-v3-chatbot-frame.html

10. Verificar que Django arranca¶

cd ../../backend_django
source venv/bin/activate
python manage.py runserver 127.0.0.1:8000

Abre otra terminal:

curl http://127.0.0.1:8000/health
# {"status": "ok", "db": true}

curl http://127.0.0.1:8000/v3/health
# {"status": "healthy", "service": "widget", "timestamp": "..."}

Si ambos responden 200 con JSON, el backend está OK.

Detén el runserver con Ctrl+C y pasa a 05-deploy-produccion.md.

Errores comunes en esta fase¶

Síntoma	Causa	Solución
`psycopg2.OperationalError: password authentication failed`	DB_PASSWORD incorrecto en `.env`	Verifica que coincide con el `CREATE USER`
`django.db.utils.ProgrammingError: relation "..." does not exist`	Falta `migrate`	`python manage.py migrate`
`KeyError: 'SECRET_KEY'`	No existe `.env` o falta la variable	Crea `.env` desde `.env.example`
`ModuleNotFoundError: No module named 'django'`	Olvidaste `source venv/bin/activate`	Activa el venv
Build npm falla con `EACCES`	Permisos de `node_modules`	`sudo chown -R $USER:$USER node_modules`