How to Run WeKnora Locally: Docker and Development Setup Guide

You can run WeKnora locally using Docker Compose for full containerization or leverage the fast development mode with hot-reload for active code changes.

Tencent/WeKnora is a modular, Go-backed knowledge-base platform that combines a REST API backend with a Vue 3 frontend. To run WeKnora locally, you will orchestrate three logical processes: the Backend API (Go monolith), the Frontend UI (Vue 3 + Vite), and Infrastructure Services (PostgreSQL, MinIO, optional Neo4j/Langfuse). The repository provides both a containerized quick-start path and a lightweight single-binary option for simplified local testing.

Prerequisites

Running WeKnora locally requires minimal dependencies. You need Docker and Docker Compose installed to manage the infrastructure stack, plus Git to clone the repository from https://github.com/Tencent/WeKnora. No local Go or Node.js installation is required if you use the standard Docker Compose workflow.

Quick Start with Docker Compose

The fastest way to run WeKnora locally is using the provided docker-compose.yml file, which orchestrates the backend, frontend, and database services.

Step 1: Clone and Configure

First, clone the repository and prepare your environment variables:

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

# Copy the example environment file

cp .env.example .env

Edit the .env file to adjust ports, database credentials, or external URLs as needed for your local machine. The default configuration starts core services on http://localhost with the API exposed at http://localhost:8080.

Step 2: Start Core Services

Pull the Docker images and start the default stack, which includes the backend API, frontend UI, and PostgreSQL (with pgvector support):

docker compose pull
docker compose up -d

Once containers are healthy, access the web console at http://localhost. The backend API endpoints are available at http://localhost:8080/api/v1/* for programmatic access or SSE event streams.

Step 3: Add Optional Services with Profiles

WeKnora supports modular infrastructure via Docker Compose profiles. To enable additional services like MinIO for object storage or Langfuse for tracing, append the relevant profiles:

docker compose --profile minio --profile langfuse up -d

Available profiles defined in docker-compose.yml include minio, neo4j for graph database capabilities, and langfuse for LLM observability. You can mix profiles based on your local development needs without modifying source code.

Fast Development Mode

For active development where you need to modify Go or Vue code without rebuilding Docker images, use the fast development mode targets defined in the Makefile.

Running Infrastructure Containers

Start the supporting infrastructure (PostgreSQL, MinIO, Redis) in watch mode while keeping the application code native:

make dev-start

This command runs docker compose up -d for infrastructure services only, providing the databases and caches your local application processes will connect to.

Hot-Reload Backend and Frontend

In separate terminal windows, run the backend and frontend with hot-reload capabilities:

# Terminal 1: Backend with Air (Go hot-reload)

make dev-app

# Terminal 2: Frontend with Vite HMR  

make dev-frontend

The make dev-app command compiles and runs the Go backend binary locally, automatically restarting on file changes. The make dev-frontend command serves the Vue 3 application via Vite's dev server with Hot Module Replacement (HMR) enabled. Both connect to the infrastructure containers started via make dev-start.

Running the Lite Single-Binary Version

For lightweight local testing without Docker, build and run the WeKnora Lite edition, which uses SQLite instead of PostgreSQL and local filesystem storage instead of MinIO:

make build-lite
./weknora-lite

The weknora-lite binary listens on http://localhost:8080 and requires no external containers, making it ideal for quick feature validation or CI/CD testing environments. This version is implemented in the same codebase but compiles with build tags that swap the database and storage interfaces to use local resources.

Architecture Overview

Understanding the component structure helps troubleshoot local deployments:

• Backend (internal/handler, internal/utils): Go 1.26+ monolith exposing REST endpoints and SSE streams. All services (LLM providers, vector stores) are interface-based for easy mocking during local development.
• Frontend (frontend/src): Vue 3 TypeScript application built with Vite. In production builds, static assets are served by the Go backend under /web; in dev mode, the Vite dev server proxies API requests.
• MCP Server: Python package (tencent-weknora-mcp) that runs as a separate process (weknora mcp serve) providing 29 built-in tools for agent orchestration.

Summary

• Docker Compose is the recommended method to run WeKnora locally, requiring only docker compose up -d after configuring .env.
• Compose profiles (--profile minio, --profile langfuse) enable optional services like object storage and tracing without code changes.
• Fast development mode (make dev-start, make dev-app, make dev-frontend) provides hot-reload for Go and Vue code while using Docker for databases.
• WeKnora Lite (make build-lite) offers a single-binary, SQLite-backed option for container-free local testing.
• The default local URLs are http://localhost for the UI and http://localhost:8080 for the API backend.

Frequently Asked Questions

What ports does WeKnora use when running locally?

By default, WeKnora exposes the web UI on port 80 (http://localhost) and the backend API on port 8080 (http://localhost:8080). You can modify these in the .env file by changing APP_EXTERNAL_URL and related port mappings before running docker compose up.

Can I run WeKnora without Docker?

Yes. You can run the lite version locally by building the single binary with make build-lite and executing ./weknora-lite. This version uses SQLite for data persistence and local filesystem storage instead of PostgreSQL and MinIO, eliminating the Docker dependency entirely.

How do I enable Neo4j or Langfuse in my local setup?

Use Docker Compose profiles when starting the services. Run docker compose --profile neo4j up -d to add the graph database, or docker compose --profile langfuse up -d to enable LLM tracing. Multiple profiles can be combined: docker compose --profile minio --profile langfuse up -d.

What is the difference between docker compose up and make dev-start?

docker compose up -d starts the full production-like stack including the compiled backend and frontend containers. make dev-start only launches the infrastructure services (Postgres, MinIO, Redis), allowing you to run the backend and frontend natively on your machine with hot-reload via make dev-app and make dev-frontend.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}