# How to Run WeKnora Locally: Docker and Development Setup Guide > Run WeKnora locally with Docker Compose for full containerization or use fast development mode with hot-reload for efficient coding. Get your WeKnora setup today. - Repository: [Tencent/WeKnora](https://github.com/tencent/WeKnora) - Tags: how-to-guide - Published: 2026-09-13 --- **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`](https://github.com/Tencent/WeKnora/blob/main/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: ```bash 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): ```bash 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: ```bash docker compose --profile minio --profile langfuse up -d ``` Available profiles defined in [`docker-compose.yml`](https://github.com/Tencent/WeKnora/blob/main/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: ```bash 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: ```bash # 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: ```bash 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`.