DEEIX聊天

Prerequisites

• Node.js 22.23.4, 24.22.1 or 26.12.1 — the first patched release of each maintained line (engines allows all three; Node 20 and older are end-of-life). .nvmrc, CI and the Docker image all use 26.12.1.
• pnpm 10.17.0 (npm install -g pnpm@10.17.0; Node 26 no longer bundles Corepack).
• Go 1.26.10 for backend development.
• Docker Engine with Docker Compose v2 for container deployments or local PostgreSQL/Redis services.

The SQLite profile does not require a separately managed database or cache. The default development configuration uses PostgreSQL and Redis; the full Compose profile starts both services for you.

Docker Deployment

All Docker assets live in deploy/; copy that directory to your server, the application source is not needed. Run the following commands from inside deploy/. Choose one installation profile first, then copy the matching config template to deploy/config.yaml. All profiles expose the app at http://localhost:8080 by default and mount ./config.yaml (relative to deploy/) to /app/config.yaml inside the container.

1. Lightweight Installation: SQLite

This is the lowest-dependency deployment. It starts only the app container, stores data and local vector indexes in SQLite, and uses the in-process memory cache. Use it for local evaluation, personal deployments, and small single-node setups.

cd deploy
cp config.sqlite.example.yaml config.yaml
docker compose -f docker-compose.sqlite.yml up -d

SQLite + memory cache is single-process only. It is good for local use, evaluation, and small single-node deployments. Use PostgreSQL + Redis for multi-node or high-concurrency production deployments.

2. Default Installation: External PostgreSQL + Redis

Use this when PostgreSQL and Redis are already managed outside this compose stack. Before starting, set database and Redis addresses to values reachable from inside the container; if the services run on the Docker host, host.docker.internal is usually the right hostname.

```bash cd deploy cp config.example.yaml config.yaml

Separated Deployment

Use this mode when the frontend and backend are served from different public origins, for example https://chat.example.com and https://api.example.com.

1. Configure public URLs.

• Frontend build variable: NEXT_PUBLIC_API_BASE_URL=https://api.example.com
• Backend config: server.public_api_base_url=https://api.example.com
• Backend config: server.public_web_base_url=https://chat.example.com
• Backend config: server.cors_allow_origin=https://chat.example.com

For Docker image builds, pass the frontend API URL at build time:

   docker build --build-arg NEXT_PUBLIC_API_BASE_URL=https://api.example.com -t deeix-chat .
   

1. Build and publish the frontend.

   pnpm install
   NEXT_PUBLIC_API_BASE_URL=https://api.example.com pnpm --filter @deeix/web build
   

The static output is apps/web/out. Serve it with Nginx, CDN, object storage, or any static web server. To let the Go backend serve the frontend, place apps/web/out under server.frontend_dist_dir; the Docker image defaults to /app/frontend/out.

1. Apply CDN rules.

| Path | Rule | | --- | --- | | /_next/static/* | Cache for 1 year with immutable assets enabled. | | /logo*.svg, /*.ico, /*.png, /*.jpg, /*.webp, /*.woff2 | Cache for 1 day to 30 days. | | /, /*.html, /login*, /auth*, /chat*, /recent*, /files*, /knowledge-bases*, /library*, /settings*, /admin*, /share*, /preview* | Do not long-cache. Use no-cache or a short TTL. | | /api/*, /healthz, /readyz, /swagger/* | Bypass CDN cache and forward all request headers, methods, query strings, and request bodies. |

If the CDN serves apps/web/out from object storage, enable route fallback so clean URLs resolve to their exported index.html files, for example /chat -> /chat/index.html.

Quick Start

Quick installation guide: Quick Start.

Feature Guides

• User Guide
• Admin Guide
• Advanced Guide

Configuration

Full configuration guide: Configuration.

Backend configuration is split into static runtime configuration and runtime business settings. Static runtime configuration describes branding and the infrastructure, security, and storage parameters required to start the service, and is provided through config.yaml and environment variables. Runtime business settings cover product capabilities such as authentication, conversations, models, files, and billing; they are stored in system_settings and maintained from the admin console. Environment variables override matching config-file values, which is useful for containerized deployments, separated deployments, and secret injection.

At startup, the backend resolves the default config file from the working directory: starting from the repository root reads config.yaml, while starting from backend/ reads ../config.yaml. Docker deployments mount deploy/config.yaml as read-only /app/config.yaml inside the container. If the config file is stored elsewhere, set CONFIG_FILE to a path accessible from the running process or container. The effective priority is environment variables > config.yaml > built-in defaults.

Frontend branding is also runtime configuration. Set the branding section in config.yaml, then restart the application; rebuilding the frontend or Docker image is not required. See Custom branding.

Static configuration environment variables:

Authentication, registration, conversation settings, model option policies, file processing, RAG, embedding, MCP, billing, payments, and announcements are runtime business settings, not static YAML configuration. Their defaults are seeded by the backend and maintained in the admin console.

When SSRF protection is enabled in production, administrator-saved model, MCP, Embedding, OIDC/OAuth2, and custom Turnstile endpoints are authorized locally by exact origin (scheme + host + port) and do not require entries in the global allowlist. Model, MCP, and Embedding redirects retain standard compatibility: public cross-origin targets are allowed, while private cross-origin targets must match SSRF_ALLOWED_HOSTS or SSRF_ALLOWED_CIDRS; OIDC/OAuth2 and Turnstile keep their stricter identity boundary. Generated media is downloaded, validated, and stored by the backend: a private artifact URL inherits trust only when it has the same origin as the selected model endpoint; public cross-origin artifact URLs remain subject to the strict public-network policy, and private cross-origin artifact URLs are blocked. The global allowlist also remains available for deployment-level integrations that cannot be tied to an administrator-saved endpoint, such as selected GeoIP or extraction deployments. Link-local, multicast, unspecified, and known metadata targets always remain blocked. Invalid allowlist entries stop backend startup, and global allowlist changes require a restart.

Outbound requests honor the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables, including when SSRF protection is enabled. The proxy address itself is treated as deployment-authorized; target URLs are still validated against the SSRF policy before a proxy is selected, so metadata and other blocked targets remain rejected, and requests that bypass the proxy (via NO_PROXY or loopback) keep the full DNS-validated dial path. When a request is sent through the proxy, the proxy resolves the target hostname. Before handing it over, the backend rejects numeric hostnames such as 127.1 or 2130706433 and resolves the hostname locally once, rejecting it if any resolved address is blocked by the policy; if local resolution fails, the request is left to the proxy. This does not protect against DNS rebinding at the proxy, so DNS-level egress control remains the responsibility of your proxy. There is no proxy setting in config.yaml: proxy addresses and credentials stay in the deployment environment. Go does not read ALL_PROXY, so for a SOCKS proxy set HTTP_PROXY and HTTPS_PROXY to a socks5:// URL; if only ALL_PROXY is set, the backend logs outbound_proxy_ignored at startup and connects directly. Proxy environment changes require a restart. In the desktop app's local mode the app sets these variables for its bundled server from the proxy chosen in Settings › Network (by default the system proxy); see apps/desktop/README.md.