|
1 | 1 | # Docker Deployment Guide |
2 | 2 |
|
3 | | -> **See also:** the shorter [Docker (development)](/guide/docker) guide in the sidebar covers the essentials. This page is the expanded reference with all environment variables, troubleshooting, and production notes. |
| 3 | +This page has been consolidated into the main [Docker guide](/guide/docker), which now includes all environment variables, troubleshooting, and production notes. |
4 | 4 |
|
5 | | -## Architecture |
6 | | - |
7 | | -``` |
8 | | -┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ |
9 | | -│ Nuxt 3 App │────▶│ PostgreSQL 16 │ │ Ollama │ |
10 | | -│ (app, :3000) │ │ + pgvector │ │ (optional, │ |
11 | | -│ UI + API │ │ (postgres,:5432)│ │ :11434) │ |
12 | | -└─────────────────┘ └──────────────────┘ └─────────────────┘ |
13 | | -``` |
14 | | - |
15 | | -Everything in one container — no separate frontend/backend split. |
16 | | - |
17 | | ---- |
18 | | - |
19 | | -## Quick Start |
20 | | - |
21 | | -### 1. Configure |
22 | | - |
23 | | -```bash |
24 | | -cp .env.example .env |
25 | | -# Edit .env — set GOOGLE_API_KEY (recommended) or OPENAI_API_KEY at minimum |
26 | | -# For Ollama Cloud: set OLLAMA_API_KEY + OLLAMA_URL (local Ollama needs no key) |
27 | | -# Optional: uncomment COMPOSE_PROFILES=full in .env so `docker compose up -d --build` |
28 | | -# starts app + postgres + ollama without passing --profile each time. |
29 | | -``` |
30 | | - |
31 | | -### 2. Start |
32 | | - |
33 | | -```bash |
34 | | -# App + database + local Ollama |
35 | | -docker compose --profile full up -d --build |
36 | | - |
37 | | -# App + database only (omit Ollama; use cloud Ollama/Google/OpenAI) |
38 | | -docker compose --profile full up -d --build app postgres |
39 | | -``` |
40 | | - |
41 | | -### 3. Access |
42 | | - |
43 | | -| Service | URL | |
44 | | -|---|---| |
45 | | -| App (UI + API) | http://localhost:3000 | |
46 | | -| PostgreSQL | localhost:5432 | |
47 | | -| Ollama (if running) | http://localhost:11434 | |
48 | | - |
49 | | ---- |
50 | | - |
51 | | -## Profiles |
52 | | - |
53 | | -| Profile | Services started | |
54 | | -|---|---| |
55 | | -| `full` | postgres + ollama + app | |
56 | | -| `api` | postgres + ollama (no app) | |
57 | | -| `all` | same as `full` | |
58 | | - |
59 | | -```bash |
60 | | -docker compose --profile full up -d --build |
61 | | -docker compose --profile full down |
62 | | -docker compose --profile full down -v # ⚠️ deletes volumes |
63 | | -``` |
64 | | - |
65 | | ---- |
66 | | - |
67 | | -## Environment Variables |
68 | | - |
69 | | -For the full variable reference including all provider options, see [Environment variables guide](./guide/env.md). |
70 | | - |
71 | | -### Minimum required |
72 | | - |
73 | | -| Variable | Default | Description | |
74 | | -|---|---|---| |
75 | | -| `PORT` | 3000 | App port | |
76 | | -| `DATABASE_URL` | — | Full Postgres connection string (pgvector or Supabase) | |
77 | | - |
78 | | -### PostgreSQL container (docker-compose only) |
79 | | - |
80 | | -| Variable | Default | Description | |
81 | | -|---|---|---| |
82 | | -| `POSTGRES_USER` | rag | DB user | |
83 | | -| `POSTGRES_PASSWORD` | rag_password | DB password | |
84 | | -| `POSTGRES_DB` | rag_db | DB name | |
85 | | -| `POSTGRES_PORT` | 5432 | Postgres port | |
86 | | - |
87 | | -### Provider selection |
88 | | - |
89 | | -| Variable | Default | Description | |
90 | | -|---|---|---| |
91 | | -| `EMBEDDING_PROVIDER` | auto-detect | `gemini` / `openai` / `voyage` / `ollama-local` | |
92 | | -| `LLM_PROVIDER` | auto-detect | `anthropic` / `openai` / `mistral` / `ollama-cloud` / `ollama-local` | |
93 | | - |
94 | | -### AI providers (set at least one pair) |
95 | | - |
96 | | -| Variable | Default | Description | |
97 | | -|---|---|---| |
98 | | -| `GOOGLE_API_KEY` | — | Gemini embedding | |
99 | | -| `OPENAI_API_KEY` | — | OpenAI embedding or chat | |
100 | | -| `OPENAI_LLM_MODEL` | gpt-4.1-mini | OpenAI chat model | |
101 | | -| `VOYAGE_API_KEY` | — | Voyage AI embedding | |
102 | | -| `ANTHROPIC_API_KEY` | — | Anthropic chat (Claude) | |
103 | | -| `ANTHROPIC_MODEL` | claude-sonnet-4-6 | Anthropic model | |
104 | | -| `MISTRAL_API_KEY` | — | Mistral chat | |
105 | | -| `MISTRAL_MODEL` | mistral-medium-latest | Mistral model | |
106 | | -| `OLLAMA_URL` | http://ollama:11434 | Ollama endpoint (embedding + chat) | |
107 | | -| `OLLAMA_API_KEY` | — | Ollama Cloud auth | |
108 | | -| `OLLAMA_MODEL` | nomic-embed-text | Ollama embedding model | |
109 | | -| `OLLAMA_LLM_MODEL` | llama3.1:8b | Ollama chat model (use a tool-calling model; `tinyllama` will skip KB search) | |
110 | | -| `OLLAMA_CHAT_TIMEOUT_MS` | 180000 | LLM response timeout ms | |
111 | | -| `OLLAMA_PLANNER_TIMEOUT_MS` | 60000 | Planner timeout ms | |
112 | | -| `EMBEDDING_DIMENSIONS` | 768 | Must match pgvector column | |
113 | | - |
114 | | -### Application |
115 | | - |
116 | | -| Variable | Default | Description | |
117 | | -|---|---|---| |
118 | | -| `MEMORY_SCOPE` | local_per_user | `local_per_user` / `global` / `disabled` | |
119 | | -| `MEMORY_PROACTIVE` | true | Auto-save user facts | |
120 | | - |
121 | | ---- |
122 | | - |
123 | | -## Useful Commands |
124 | | - |
125 | | -```bash |
126 | | -# Logs |
127 | | -docker compose logs -f app |
128 | | -docker compose logs -f postgres |
129 | | -docker compose logs -f ollama |
130 | | - |
131 | | -# Shell access |
132 | | -docker compose exec app sh |
133 | | -docker compose exec postgres psql -U rag -d rag_db |
134 | | - |
135 | | -# Rebuild after code changes |
136 | | -docker compose --profile full up -d --build |
137 | | - |
138 | | -# Pull latest Ollama model manually |
139 | | -docker compose exec ollama ollama pull nomic-embed-text |
140 | | -``` |
141 | | - |
142 | | ---- |
143 | | - |
144 | | -## Data Volumes |
145 | | - |
146 | | -| Volume | Contents | |
147 | | -|---|---| |
148 | | -| `postgres_data` | PostgreSQL data files | |
149 | | -| `ollama_data` | Downloaded Ollama models | |
150 | | - |
151 | | ---- |
152 | | - |
153 | | -## First Run |
154 | | - |
155 | | -On first start, the Ollama container downloads the configured models — this can take a few minutes. Watch progress with: |
156 | | - |
157 | | -```bash |
158 | | -docker compose logs -f ollama |
159 | | -``` |
160 | | - |
161 | | ---- |
162 | | - |
163 | | -## Troubleshooting |
164 | | - |
165 | | -**App can't reach database:** |
166 | | -```bash |
167 | | -docker compose exec postgres pg_isready -U rag |
168 | | -docker compose logs postgres |
169 | | -``` |
170 | | - |
171 | | -**Port already in use:** |
172 | | -Change `PORT` or `POSTGRES_PORT` in `.env`. |
173 | | - |
174 | | -**Rebuild from scratch:** |
175 | | -```bash |
176 | | -docker compose --profile full down -v |
177 | | -docker system prune -a |
178 | | -docker compose --profile full up -d --build |
179 | | -``` |
180 | | - |
181 | | ---- |
182 | | - |
183 | | -## Production Notes |
184 | | - |
185 | | -- Change all default passwords in `.env` before deploying |
186 | | -- Use a managed PostgreSQL service (Railway, Supabase, Neon) instead of the Docker container in production |
187 | | -- The app runs `prisma migrate deploy` automatically on startup via `docker-entrypoint.sh` |
188 | | -- Add a reverse proxy (nginx, Caddy) in front for HTTPS |
189 | | - |
190 | | -**Backup database:** |
191 | | -```bash |
192 | | -docker compose exec postgres pg_dump -U rag rag_db > backup_$(date +%Y%m%d).sql |
193 | | -``` |
| 5 | +Go to **[Docker guide →](/guide/docker)** |
0 commit comments