WeKnora Setup: Self-Host Tencent's Open Source RAG Platform

WeKnora is an open source, LLM-powered knowledge platform from Tencent that ingests your documents (PDF, Word, Excel, Markdown, web pages, images, audio) and serves them back three ways: a RAG chat that answers with clickable citations, a ReAct agent that can search the web and call tools, and a Wiki Mode that rewrites the raw files into an interlinked knowledge base with a graph view. It is trending on GitHub today with roughly 1,200 new stars on top of 25,100 total, sitting at version 0.8.0 (September 3, 2026) under the MIT license. Setup on any machine that runs Docker takes about 15 minutes: clone the repo, copy the example env file, pull five images, register the first account in the web UI, and connect a chat model plus an embedding model from Ollama or any OpenAI-compatible API.

• The standard deployment is five containers: an Nginx frontend on port 80, a Go backend on 8080, a Python document parser, ParadeDB (PostgreSQL 17 with BM25 and vector extensions) and Redis. No separate vector database is needed to start.
• No default account exists. The first person to open http://localhost registers, and that user becomes Owner of a personal workspace. Set DISABLE_REGISTRATION=true before you expose it to a team.
• Every knowledge base needs one chat model and one embedding model; a local Ollama at http://host.docker.internal:11434 works with zero API keys, and the official quickstart uses qwen3:8b plus bge-m3.
• The web UI defaults to Simplified Chinese. Uncomment DEFAULT_LOCALE=en-US in .env before the first start, or switch it from the language menu after.

The exact steps, start to finish

1. Step 1. Check what you already have.

   # WeKnora needs Docker 20.10+ with Compose v2, and Git. Ollama is optional but the easiest model source.
   docker --version
   docker compose version
   git --version
   ollama --version

   The official install doc recommends a 4-core CPU and 8 GB of RAM as a starting point, because the document parser bundles LibreOffice and Playwright. On Windows and macOS that means Docker Desktop is installed and running before you continue; on Linux it means Docker Engine with the Compose plugin.
2. Step 2. Clone the repo and create your env file. These are the README's exact lines:

   git clone https://github.com/Tencent/WeKnora.git
   cd WeKnora
   cp .env.example .env   # Edit .env as needed, see comments in the file

   On Windows the same three lines work in PowerShell (cp is an alias there). In a plain cmd.exe window, replace the copy line with copy .env.example .env. Do not skip this file: the app service loads .env with env_file, and Compose refuses to start if it is missing.
3. Step 3. Set the two secrets and the locale. Open .env and fill JWT_SECRET and SYSTEM_AES_KEY. The file's own comments give the generators:

   # JWT_SECRET: Generate once: openssl rand -hex 32
   openssl rand -hex 32
   # SYSTEM_AES_KEY: Generate once: openssl rand -hex 16 (32 ASCII bytes); retain existing keys on upgrade.
   openssl rand -hex 16

   Paste each value after the = on its line. On Windows, run the two openssl commands inside Git Bash (it ships with Git for Windows) or the WSL shell; PowerShell and cmd.exe do not include openssl by default. While you are in the file, uncomment DEFAULT_LOCALE=en-US so the UI comes up in English and WEKNORA_LANGUAGE=en-US so answers do too (in our test a small Qwen model replied in Chinese until we set it), and leave WEKNORA_VERSION=latest alone for now. The AES key encrypts every model API key and data-source credential at rest, so store it somewhere safe: lose it and those fields come back blank.
4. Step 4. Pull the images and start the stack.

   docker compose pull     # Pull the latest images
   docker compose up -d    # Start core services
   docker compose ps       # wait until every service is healthy/running

   The pull is the slow part: on our test machine it fetched wechatopenai/weknora-ui (130 MB), weknora-app (2.4 GB), weknora-docreader (5.7 GB), paradedb/paradedb:v0.22.2-pg17 (2.4 GB) and redis:7.0-alpine (49 MB), about 10.6 GB of images in total, and the whole stack reported healthy about 25 seconds after up -d. The install doc warns that running docker compose up -d alone reuses whatever images are cached, so always pull first when you want the release you read about.
5. Step 5. Confirm the backend is up.

   curl http://localhost:8080/health

   The quickstart says this returns {"status":"ok"} once the Go backend has migrated the database and connected to Redis and the parser. If it hangs, give the postgres and docreader health checks another minute; app waits on both.
6. Step 6. Get a chat model and an embedding model ready. Any OpenAI-compatible endpoint with a base_url and api_key works (OpenAI, DeepSeek, Qwen, Zhipu, SiliconFlow and a dozen more are listed). For a key-free local setup, install Ollama from ollama.com and pull the two models the official quickstart configures:

   ollama pull qwen3:8b
   ollama pull bge-m3

   The README adds one line for Ollama users: run ollama serve > /dev/null 2>&1 & first (on Windows and macOS the desktop app keeps it running for you). Inside the containers, your host's Ollama is reachable at http://host.docker.internal:11434, which is already the default OLLAMA_BASE_URL in .env; the Settings, Ollama page in the UI shows the connection status and every model it can see.
7. Step 7. Register the first account. Open http://localhost. There is no default login: the first visit lands on a register tab. Username is 2 to 50 characters, password 8 to 32 with at least one letter and one digit. That account becomes Owner of its own workspace. If you later want it to be the platform's system admin too, set WEKNORA_BOOTSTRAP_SYSTEM_ADMIN_EMAIL=<that email> in .env and restart the app container.
8. Step 8. Register the models in Settings. Open Settings, then Model Management, and click Add Model. Choose the Embedding tab, pick Ollama as the source (or API for a remote provider, which asks for a provider, base URL and key), select your embedding model from the list, click Detect Dimension (it fills in 768 for nomic-embed-text, 1024 for bge-m3) and Save. Repeat on the Chat tab for the chat model. The API source has a Test Connection button; use it before saving.
9. Step 9. Create a knowledge base and set the agent's model. On the Knowledge Base page click Create Knowledge Base, give it a name and keep the document type. Under Model Configuration the LLM and embedding you just added are pre-selected; click Create Knowledge Base. The embedding choice is sticky: changing it later means re-indexing everything in that base. Then open Agents, click Quick Answer, and under Model Config select the chat model and Save and Close. Skip this and the first question fails with Agent "Quick Answer" is not ready. Please configure: Chat model, which is exactly what happened in our test.
10. Step 10. Upload a document and ask something. Open the knowledge base, drop in a PDF or Markdown file, click Upload and parse, and watch the status go from pending to processing to completed. Then click New Chat and ask a question about the file. The Quick Answer agent retrieves the matching chunks and answers with the referenced documents listed above the reply. In our test, a one-page runbook and the 0.6B Qwen model produced "Backups are scheduled nightly at 02:00 UTC and stored in the MinIO bucket named kb-backups for 30 days" with one document referenced, about three seconds after sending. When that reference line shows up, WeKnora is working end to end.

What is WeKnora and why is it trending?

WeKnora is the engine behind Tencent's WeChat Dialog Open Platform, released as open source in July 2025 and now at 25,100 stars with contributions landing daily. The pitch is a knowledge base you own end to end: documents go in through the parser, get chunked and embedded into ParadeDB, and come back out as a chat answer with citations, an agent that can chain retrieval with web search and MCP tools, or a wiki that the agent writes and keeps updated. Version 0.8.0 on September 3 added session-persistent skill sandboxes (Docker, E2B or Cube), a per-workspace skill catalog, cross-session long-term memory, GitLab and Tencent IMA data sources, LiteLLM support and an in-process office parser called anydoc. The 0.7 line before it shipped scoped API keys, a runtime task-queue dashboard, chunk editing with revision history, a folder tree for uploads and an official documentation site.

RelatedEver Gauzy Setup: Self-Host an Open Source ERP and CRM

Why the spike today: the project is the fastest-moving self-hosted RAG stack in the open right now, and it covers a lot of enterprise surface that rivals charge for. Workspace RBAC with four roles, per-workspace audit logs, AES-256-GCM encryption of stored credentials, OIDC login, and IM channels for Slack, Telegram, Feishu, WeCom, DingTalk and Mattermost are all in the MIT-licensed core. It also speaks to 20-plus LLM providers and eight vector stores, so nothing about the stack locks you to Tencent. The Chinese-first documentation is the main tax an English-speaking reader pays.

How do you install WeKnora on Windows?

Install Docker Desktop with the WSL 2 backend and Git for Windows, start Docker Desktop, then run the README commands in PowerShell:

# PowerShell
git clone https://github.com/Tencent/WeKnora.git
cd WeKnora
cp .env.example .env
docker compose pull
docker compose up -d

# cmd.exe (same steps, cmd's copy verb)
git clone https://github.com/Tencent/WeKnora.git
cd WeKnora
copy .env.example .env
docker compose pull
docker compose up -d

Generate JWT_SECRET and SYSTEM_AES_KEY in Git Bash with the two openssl rand lines from Step 3 and paste them into .env before the up. Docker Desktop provides host.docker.internal automatically, so a Windows Ollama install is reachable from the containers with no extra configuration. Port 80 must be free; if IIS or another web server holds it, set FRONTEND_PORT=8081 (or any free port) in .env and open that instead.

How do you install WeKnora on macOS and Linux?

On macOS, Docker Desktop (or OrbStack) plus Git is all you need, and the commands are identical to the README block in Step 2 and Step 4. Apple Silicon is fine: the images are multi-arch. On Linux, install Docker Engine and the Compose plugin from your distribution or Docker's repository, add your user to the docker group, then run the same five lines. One Linux-specific check from the troubleshooting table: if the wizard cannot see your Ollama, confirm the extra_hosts: host.docker.internal:host-gateway mapping in docker-compose.yml took effect, because on Linux that alias is not automatic the way it is on Docker Desktop.

Upgrading later is two lines from the README: set WEKNORA_VERSION in .env to the release you want (or leave latest), then docker compose pull and docker compose up -d. Database migrations run automatically on start because AUTO_MIGRATE=true is the default. To stop everything, docker compose down; adding -v deletes the data volumes too, so leave it off unless you mean it.

What about the optional pieces: graph, storage, tracing and Lite?

The core stack is deliberately small. Everything else is a Compose profile you can bolt on: docker compose --profile neo4j pull && docker compose --profile neo4j up -d adds Neo4j for the knowledge graph (then set NEO4J_ENABLE=true), --profile minio adds S3-style object storage, --profile langfuse adds a full Langfuse tracing stack on port 3000, and --profile full switches on all of them plus a SearXNG web-search node, a skill sandbox image and the MCP server. Profiles combine, and the README lists each command verbatim.

There is also a Lite edition: one Go binary with SQLite for storage, FTS5 for keyword search and sqlite-vec for vectors, no Redis, no Postgres, built with make run-lite after copying .env.lite.example to .env.lite. The repo carries a Homebrew formula for it, but the install doc is candid that the desktop app has no release packages yet, and the v0.8.0 release page lists no binary assets at all. Treat Lite as a build-from-source path today and use Docker Compose for anything you want to keep.

How does WeKnora compare with Dify, RAGFlow and AnythingLLM?

AnythingLLM is still the lightest way to chat with a folder of files, and Dify remains the better visual workflow builder. WeKnora's edge is depth on the knowledge side: chunk editing with diffs, a wiki the agent maintains, folder-preserving uploads, and a security posture (encrypted credentials, SSRF-safe fetches, audit logs) that most hobby RAG projects skip. The trade is a bigger stack and documentation you may be running through a translator.

What are the gotchas before you rely on it?

Memory. The docreader image carries LibreOffice, OpenJDK 17 and a Playwright WebKit build. On an 8 GB laptop that already runs Docker Desktop and an Ollama model, expect swapping. The install doc's 8 GB figure is a floor, not a target.

RelatedOpenSEO Setup: Self-Host an Open Source SEO Tool

Uploads that sit in processing. The first thing the troubleshooting table says to run is docker logs WeKnora-docreader. Files are capped at MAX_FILE_SIZE_MB (50 by default) and parsing at WEKNORA_DOCUMENT_PROCESS_TIMEOUT (two hours), so a scanned 300-page PDF is a slow first test. Start with a small Markdown or text file.

Empty answers. If chat returns nothing or no citations, confirm the document reached completed, lower vector_threshold in the knowledge base settings, and check that the embedding model you are querying with is the one the base was indexed with. Swapping embeddings silently breaks retrieval until you reindex.

Timezone and language. TZ defaults to Asia/Shanghai, the UI to zh-CN, and the prompt language falls back to the browser's Accept-Language header. All three are one-line edits in .env (TZ, DEFAULT_LOCALE, WEKNORA_LANGUAGE); the locale change only needs the frontend container restarted, the language one needs docker compose up -d app.

Ports and agents. Anything already listening on port 80 (IIS, another proxy, a second Compose project) makes the frontend container fail to start; FRONTEND_PORT=8081 in .env fixes it, as it did on our test laptop. And the built-in agents do not inherit a model automatically: each one has its own Model Config, so set Quick Answer's chat model before the first question.

Exposure. The README's security notice asks you to keep WeKnora on a private network, and the quickstart shows how registration can be locked to invite-only either with DISABLE_REGISTRATION=true or from the admin settings page without a restart. If you do put it behind a domain, do it behind a reverse proxy with TLS and turn on WEKNORA_AUTH_COMPLEX_PASSWORD_ENABLED=true.

Our take

Most self-hosted RAG tools stop at chat with citations. WeKnora treats that as the floor and spends its effort on the parts that make a knowledge base survive contact with a team: editable chunks with history, a wiki that stays current, roles, audit trails and encrypted secrets. That is why it keeps reclaiming the trending page. The install is honest about its weight (five containers, 8 GB), and the model wizard with a built-in Test button is the kind of detail that saves an hour on day one. What it needs now is English documentation that matches the code, and shipped Lite binaries so a single user does not have to run Postgres to read their own PDFs. If you have Docker and a spare afternoon, this is the most complete free knowledge stack you can stand up this week.

Original analysis by GenZTech. Tool documentation: Tencent/WeKnora on GitHub.