Tencent WeKnora

1. What is WeKnora?

WeKnora is an open-source platform from Tencent that turns a pile of documents (PDF, Word, Excel, images, web pages and more) into a question-answering assistant: you load your documents, then ask questions in plain language and get answers with source citations. This approach is usually called RAG (retrieve first, then let an AI model answer based on your own documents). WeKnora also has an "agent" mode for multi-step tasks and can build a wiki automatically from your documents.

Let us be honest so you do not waste time: this is a tool for developers and system administrators, not a click-and-run app. There is no .exe or .dmg installer. The official way to run it is Docker and the command line, and you must supply an AI model yourself (run it locally with Ollama, or use an API key from a service such as OpenAI). A desktop version with a graphical interface is mentioned but not yet released; you would have to build it from source.

A good fit if:

• You are comfortable with the command line and Docker, and want to build your own Q&A system over your documents.
• You need your data to stay inside your own infrastructure rather than going to an outside service.

Not the right fit if:

• You just want an app that runs right away on a phone or a Windows machine.
• You have never used the command line and do not want to install Docker.

2. What you need

• A computer that can run Docker: Linux, macOS, or Windows (on Windows, Docker Desktop normally uses WSL2, a Linux layer inside Windows). The official docs do not list supported operating systems; Linux is the usual choice for a real server.
• Minimum specs to try it: the docs say to start from 4 CPU cores and 8 GB RAM (the document parser is memory-hungry), plus extra disk space that grows with your documents. The 8 GB figure does not include the AI model itself if you run one locally.
• Docker and Docker Compose v2: the software that downloads and runs WeKnora's parts. Available at https://www.docker.com/
• Git: the tool to fetch the source code. Available at https://git-scm.com/
• An AI model (required): you need at least one chat model and one vector (embedding) model. Two options:
  • Ollama (runs AI on your own machine, free): available at https://ollama.com/
  • Or an API key from an OpenAI-compatible service (such as OpenAI or DeepSeek). This may cost money depending on the service.

3. Step-by-step installation

The standard method is Docker Compose. Everything happens in a command window.

Step 1: Download the source code

git clone https://github.com/Tencent/WeKnora.git
cd WeKnora

What you should see: a folder named WeKnora is created and you are now inside it.

Step 2: Create the configuration file

WeKnora reads its settings from a file named .env. Copy the sample file:

cp .env.example .env

Open .env in any text editor and fill in the required fields: the database name and password (DB_USER, DB_PASSWORD, DB_NAME), the Redis password (REDIS_PASSWORD), and the two secret keys JWT_SECRET and SYSTEM_AES_KEY. These two keys are empty in the sample file and you must generate them once and keep them. On Linux/macOS you can create one quickly with:

openssl rand -hex 32

Use the result for JWT_SECRET. SYSTEM_AES_KEY must be exactly 32 bytes; generate it with openssl rand -hex 16.

Note: Keep your SYSTEM_AES_KEY. If you change it later, anything already encrypted (such as saved API keys) can no longer be decrypted.

Step 3: Pull the images and start

docker compose pull
docker compose up -d
docker compose ps

The last command lists the running parts. Wait until they all turn "healthy" or "running".

What you should see: a list of services (frontend, app, postgres, redis and so on) in a running state.

Step 4: Open the interface

Open a browser at http://localhost. On the first visit you will see a login page (the system has no default account); when public sign-up is allowed it also shows a registration tab, which you use to create your own account. The backend server runs at http://localhost:8080; you can check it is ready by opening http://localhost:8080/health, which should return {"status":"ok"}.

Step 5 (optional): Enable extra components

WeKnora has feature packs you can enable when needed, for example the knowledge graph (Neo4j) or object storage (MinIO):

docker compose --profile neo4j --profile minio pull
docker compose --profile neo4j --profile minio up -d

4. First run

After registering and signing in, the basic flow is: create a knowledge base → choose models → load documents → ask.

Step 1: Create a knowledge base and choose models

Go to the "Knowledge base" page and create a new one. A setup wizard will ask you to choose a chat model (LLM) and a vector model (Embedding). If you use Ollama running on your machine, the address containers use to reach Ollama is http://host.docker.internal:11434. Click the "Test" button in the wizard to confirm the model connection works, then save.

Step 2: Load documents

Open the base you just created, then drag files in or paste a web page URL. Documents are processed in the background, moving through pending → processing → finalizing → completed. Scanned files or large files take longer.

Step 3: Ask a question

Go to the chat page, select the knowledge base and type a question. The system finds relevant passages and generates an answer; click a citation to see the original passage.

What you should see: an answer with clickable citations, which means the whole load-and-ask pipeline is working.

5. Common problems and fixes

• docker: command not found or docker commands do not run. Cause: Docker is not installed or not started. Fix: install Docker from https://www.docker.com/ and open Docker Desktop before running the commands.
• Compose errors because .env is missing. Cause: the app service reads from .env, and it fails if the file is absent. Fix: run cp .env.example .env again and fill in the required fields.
• http://localhost will not open or shows a connection error. Cause: the containers have not finished starting, or a port is in use. Fix: run docker compose ps to check they are "healthy"; view logs with docker compose logs --tail=200 app.
• Login returns a 404 page. A cause noted in the docs: if the SearXNG search service is enabled, it may be sharing port 8080 with the backend. Fix: keep SearXNG on a different port (for example 8888) so it does not clash with the app.
• A loaded document stays stuck on "processing". Cause: the document parser or the vector model cannot connect. Fix: check the model connection in the knowledge base settings; view logs with docker compose logs --tail=200 docreader.
• Search quality drops after changing the vector model. Cause: old and new vectors do not match. Fix: rebuild the index (reindex) for the base after changing the embedding model.

6. Uninstalling and updating

• Stop the services: in the WeKnora folder run docker compose down. To also delete the data, add -v (docker compose down -v) — this wipes all data, so use it with care.
• Update to a new version: set WEKNORA_VERSION in .env to the version you want (or leave it as latest), then:

docker compose pull
docker compose up -d

Note: Before upgrading, read the "upgrade notes" for that version on the official docs, because some releases include breaking changes.

7. Frequently asked questions

• Does it cost anything? WeKnora itself is free and open source (MIT license). But if you use an AI model through a paid API key, that part is billed by the service. Running Ollama locally means no model fees.
• Do I need an internet connection? You need internet to download the source code and Docker images the first time. After that, with a local model (Ollama), the system can run on an internal network.
• Is my data sent anywhere? If you self-host and use a local model, the data stays in your infrastructure. If you use an external API key, your question and the relevant documents are sent to that service to produce the answer.
• Will it run on a weak machine? The docs say to start from about 8 GB RAM. For something lighter, the official docs mention a "Lite" build that runs as a single binary with SQLite, suited to low-spec machines.
• Where are the full docs? The official documentation site: https://weknora.weixin.qq.com/docs/ and the source repository https://github.com/Tencent/WeKnora. The latest version at the time of writing is v0.8.2 (24 September 2026).