fix: align quickstart with d0a1.es ecosystem and current reality

Hardening pass over the quickstart repo to make it match the actual
d0a1.es stack and remove long-standing drift.

- README: align with 8 GB RAM reality across all sections, add
  explicit security warning on WEBUI_AUTH=false, remove dead link
  to d0a1.es/vps, drop stack services not part of d0a1.es
  (n8n, WordPress, Qdrant). Re-point the d0a1 section to the
  services that actually run at git/mail/app.d0a1.es.
- docker-compose: move all tunables (ports, default model, auth,
  secret key, keep-alive) to .env with sensible defaults. Add
  commented GPU passthrough block for NVIDIA hosts.
- deploy.sh: pre-flight checks (docker, compose, daemon),
  copy .env.example on first run, auto-detect system RAM on
  Linux and macOS and warn on sub-8 GB hosts.
- Add .env.example documenting every variable and required RAM
  per model.
- Add MIT LICENSE (was promised in README but missing).
- Add .gitignore (local .env, editor cruft, OS junk).
- .gitattributes: use a single rule (text=auto eol=lf) to cover
  every text file, not just *.sh - fixes CRLF warnings on new
  text files on Windows checkouts.

Refs: d0a1/quickstart rename (companion: new repo at
git.d0a1.es/d0a1/quickstart).
This commit is contained in:
Claude Agent
2026-06-20 02:38:55 +02:00
parent 3d75b77dd7
commit 9ca770962f
7 changed files with 265 additions and 160 deletions
+61 -14
View File
@@ -8,6 +8,12 @@ Un comando y tendrás un asistente de IA corriendo **en tu propia máquina**.
Sin enviar datos a terceros. Sin pagar por tokens. Sin crear cuentas.
Usa modelos de lenguaje de código abierto (Ollama) con una interfaz web moderna (Open WebUI).
Este repo forma parte del ecosistema **d0a1.es**: un conjunto de servicios
self-hosted que demuestran que la IA útil no requiere ceder tus datos a
terceros. El quickstart es la puerta de entrada: el resto de servicios
(Gitea, mail, aplicaciones internas) están disponibles bajo el mismo paraguas
en [d0a1.es](https://d0a1.es).
## Requisitos
| Requisito | Mínimo | Recomendado |
@@ -17,21 +23,26 @@ Usa modelos de lenguaje de código abierto (Ollama) con una interfaz web moderna
| Sistema | Linux, macOS, Windows (WSL2) | Linux |
| Software | Docker + Docker Compose v2 | Docker + Docker Compose v2 |
> **Importante:** con 8 GB de RAM, usa modelos de hasta 7B cuantizados (Q4).
> Los modelos de 8B funcionan en CPU pero pueden ralentizar el sistema bajo carga.
## Instalación
### Opción rápida (recomendada)
```bash
git clone https://git.d0a1.es/devops/quickstart.git
git clone https://git.d0a1.es/d0a1/quickstart.git
cd quickstart
cp .env.example .env
./deploy.sh
```
### Opción manual
```bash
git clone https://git.d0a1.es/devops/quickstart.git
git clone https://git.d0a1.es/d0a1/quickstart.git
cd quickstart
cp .env.example .env
docker compose up -d
# Esperar ~30s a que Ollama arranque
docker exec d0a1-ollama ollama pull llama3.2:3b
@@ -45,24 +56,40 @@ Abre tu navegador en **http://localhost:3000**
- **Open WebUI** — Interfaz web tipo ChatGPT, pero local y privada.
- **llama3.2:3b** — Modelo inicial ligero (~2 GB). Buen punto de partida.
## Configuración
Toda la configuración se gestiona vía el archivo `.env` (copia `.env.example`):
| Variable | Por defecto | Descripción |
|----------|-------------|-------------|
| `WEBUI_PORT` | 3000 | Puerto de Open WebUI |
| `OLLAMA_PORT` | 11434 | Puerto de Ollama |
| `WEBUI_AUTH` | `true` | Si `false`, desactiva el login. **Recomendado solo para uso personal en local** — no exponer a internet sin autenticación. |
| `DEFAULT_MODEL` | `llama3.2:3b` | Modelo que Open WebUI sugiere al registrarse |
| `OLLAMA_KEEP_ALIVE` | `5m` | Tiempo que Ollama mantiene un modelo en memoria tras usarlo |
| `WEBUI_SECRET_KEY` | *(generar)* | Clave de sesión de Open WebUI. **Cámbiala en producción.** Genera una con: `openssl rand -hex 32` |
## Añadir modelos
Cuanta más RAM tengas, mejores modelos puedes usar:
```bash
# Mejor en español (5 GB RAM)
# Mejor en español (8 GB RAM)
docker exec d0a1-ollama ollama pull qwen2.5:7b
# Más inteligente (6 GB RAM)
# Más inteligente (8 GB RAM)
docker exec d0a1-ollama ollama pull llama3.1:8b
# Para programar (5 GB RAM)
# Para programar (8 GB RAM)
docker exec d0a1-ollama ollama pull codellama:7b
# Listar modelos instalados
docker exec d0a1-ollama ollama list
```
> Los tiempos de respuesta de los modelos grandes son sensiblemente mejores
> con GPU. En CPU funcionan, pero pueden tardar varios segundos por respuesta.
## Comandos
```bash
@@ -74,17 +101,16 @@ docker exec d0a1-ollama ollama pull MODELO # Descargar otro modelo
## ¿Y después?
Esto es solo el principio. El stack completo d0a1 añade:
Esto es solo el principio. El stack completo d0a1 incluye servicios
auto-hospedados en [d0a1.es](https://d0a1.es):
- **git.d0a1.es** — Gitea, repositorios Git con Pull Requests y code review
- **mail.d0a1.es** — Webmail SnappyMail
- **app.d0a1.es** — Aplicaciones internas
- **Hermes Agent** — Agente autónomo con memoria, skills y 14+ plataformas
- **n8n** — Automatizaciones visuales sin código
- **Qdrant** — Base de datos vectorial para búsqueda semántica
- **WordPress** — CMS con IA integrada
- **Correo, backups, HTTPS** — Todo automatizado
Si la IA local te sabe a poco, despliega el stack completo en un VPS:
**[d0a1.es/vps](https://d0a1.es/vps)** — Desde 6€/mes, todo incluido
Todos los servicios son open source, usan solo HTTPS 443 y se pueden
ejecutar en una sola máquina.
## Preguntas frecuentes
@@ -124,10 +150,31 @@ Esto ocurre sobre todo cuando se descarga el archivo desde un navegador
en Windows o se edita con el bloc de notas. Con `git clone` desde
cualquier sistema queda en LF automáticamente.
### El modelo no carga / `model requires more system memory`
Has intentado descargar un modelo demasiado grande para tu RAM. Elimínalo
y prueba con uno más pequeño:
```bash
docker exec d0a1-ollama ollama rm llama3.1:8b
docker exec d0a1-ollama ollama pull llama3.2:3b
```
### Open WebUI no arranca / `address already in use`
Tienes otro servicio en el puerto 3000 (o el que configuraste en `.env`).
Cámbialo en `.env`:
```bash
WEBUI_PORT=8080
```
Y reinicia: `docker compose down && docker compose up -d`.
## Licencia
MIT. Usa, modifica y comparte libremente.
---
[d0a1.es](https://d0a1.es) — Humano decides, agente ejecuta.
[d0a1.es](https://d0a1.es) — Humano decides, agente ejecuta.