Skip to content

InteractiveSetup.md

Latest commit

 

History

History
298 lines (197 loc) · 9.7 KB

InteractiveSetup.md

File metadata and controls

298 lines (197 loc) · 9.7 KB

Interactive Setup Guide

Use the interactive setup wizard when you want LightRAG to guide you through the configuration instead of editing .env by hand.

The wizard is exposed through make targets:

  • make env-base
  • make env-storage
  • make env-server
  • make env-validate
  • make env-security-check
  • make env-backup
  • make env-base-rewrite
  • make env-storage-rewrite

You do not need to call the underlying shell script directly.

What This Wizard Is For

The setup wizard helps you configure LightRAG in three parts:

  • env-base sets up the LLM, embedding model, and optional reranker.
  • env-storage adds or changes storage backends such as PostgreSQL, Neo4j, Redis, Milvus, Qdrant, MongoDB, or Memgraph.
  • env-server sets server host and port, WebUI labels, authentication, API keys, and SSL.

You can rerun each step later. The wizard loads your existing .env and shows current values as defaults, so you only need to change what is different.

Before You Start

  • Run commands from the repository root.
  • The make env-* targets automatically choose a compatible Bash 4+ interpreter.
  • Use the documented make env-* targets rather than invoking the setup script yourself.
  • make env-base is the normal starting point because it creates the initial .env.
  • make env-storage and make env-server require an existing .env.
  • If you choose any wizard-managed Docker service, the wizard also prepares LightRAG for the Docker startup path.

Choose Your Setup Path

Use this quick guide to decide what to run:

  • I want the fastest first run with remote model providers: make env-base
  • I want embedding or reranking to run locally in Docker: make env-base
  • I already configured models and now want databases: make env-storage
  • I already configured models and now want auth, API keys, or SSL: make env-server
  • I want to check whether my current setup is valid: make env-validate
  • I want to audit my current setup before exposing it: make env-security-check
  • I want a standalone backup without changing configuration: make env-backup
  • I need to repair the generated compose services from the bundled templates: make env-base-rewrite or make env-storage-rewrite

Scenario 1: First-Time Local Setup

Use this when you want LightRAG running with the least amount of setup and you already have remote model endpoints or API keys.

Command

make env-base

What the wizard asks

  • LLM provider, model, endpoint, and API key
  • Whether the embedding model should run locally via Docker
  • If embedding stays remote: embedding provider, model, dimension, endpoint, and API key
  • Whether reranking should be enabled
  • If reranking is enabled: whether the rerank service should run locally via Docker
  • If reranking stays remote: rerank provider, model, endpoint, and API key

What gets written

  • .env
  • docker-compose.final.yml only if you enabled wizard-managed Docker services

What to do next

  • If you did not enable wizard-managed Docker services:
lightrag-server
  • If you enabled wizard-managed Docker services:
docker compose -f docker-compose.final.yml up -d

Scenario 2: Local Setup With Docker-Hosted Embedding or Rerank

Use this when you want LightRAG to run local inference services for embedding and/or reranking through Docker.

Command

make env-base

Recommended answers

  • Answer yes to Run embedding model locally via Docker (vLLM)? if you want local embeddings
  • Answer yes to Enable reranking? and then yes to Run rerank service locally via Docker? if you want local reranking

What the wizard asks after you enable local services

  • Embedding model name for local vLLM
  • Rerank model name for local vLLM
  • Remote LLM details if your main LLM is still external

What gets written

  • .env
  • docker-compose.final.yml with the selected local services

What to do next

docker compose -f docker-compose.final.yml up -d

This starts the generated Docker-based LightRAG stack together with the selected local services.

Scenario 3: Add Storage After The Base Setup

Use this when you already have .env from make env-base and now want to switch from default local-file storage to database-backed storage.

Command

make env-storage

Prerequisite

  • .env must already exist

What the wizard asks

  • KV storage backend
  • Vector storage backend
  • Graph storage backend
  • Doc-status storage backend
  • For each required database, whether it should run locally via Docker
  • For each required database, the needed connection details such as host, URI, port, user, password, database name, or device type

Important rule

  • If you choose MongoVectorDBStorage for vector storage, the wizard does not offer the bundled local Docker MongoDB service. You must provide a MongoDB deployment that supports Atlas Search / Vector Search.

What gets written

  • .env
  • docker-compose.final.yml if you selected wizard-managed storage services

What to do next

  • If you selected Docker-managed storage services:
docker compose -f docker-compose.final.yml up -d
  • If you pointed LightRAG at external databases, make sure those services are reachable before starting LightRAG.

Scenario 4: Harden A Deployment With Auth And SSL

Use this when you already have .env and need to prepare the server for shared or external use.

Commands

make env-server
make env-security-check

Prerequisite

  • .env must already exist

What env-server asks

  • Server host and port
  • WebUI title and description
  • Summary language
  • Whether to configure authentication and API key settings
  • Auth accounts, JWT secret, token lifetime, API key, and whitelist paths
  • Whether to enable SSL/TLS
  • SSL certificate file path and SSL key file path

What gets written

  • .env
  • docker-compose.final.yml may be updated if your current setup already uses wizard-managed Docker services

What to do next

  • Run make env-security-check
  • If the stack uses Docker, recreate the LightRAG service with your compose file
  • If the stack runs on the host, restart lightrag-server

For broader deployment guidance, see DockerDeployment.md.

Validate, Audit, And Backup

These commands do not walk you through a full setup flow, but they are part of normal operations.

Validate The Current Configuration

make env-validate

Use this when you want to confirm that the current .env is internally consistent. It reports problems such as missing required values, malformed auth settings, invalid URIs, invalid ports, or missing SSL files.

Audit Security Before Exposure

make env-security-check

Use this before exposing LightRAG beyond localhost. It reports risky setups such as missing authentication, weak or missing JWT secrets, unsafe whitelist settings, or unresolved sensitive placeholders.

Create A Standalone Backup

make env-backup

Use this when you want a manual backup without running any setup flow.

Outputs And What They Mean

.env

The wizard writes .env in the repository root. This file becomes the current runtime configuration produced by the latest wizard run.

In practice, this means:

  • rerunning the wizard updates .env
  • existing values are reused as defaults on later runs
  • you should treat .env as the active configuration for the workflow you most recently configured
  • before env-base, env-storage, or env-server writes .env, the wizard automatically creates a timestamped backup of the existing file when one is present

docker-compose.final.yml

The wizard creates or updates docker-compose.final.yml only when you choose wizard-managed Docker services or when an existing wizard-generated compose setup needs to stay aligned with new server settings.

When one of the setup flows is about to replace or remove an existing generated compose file, it automatically creates a timestamped backup first.

Use this file when starting the generated Docker stack:

docker compose -f docker-compose.final.yml up -d

The base docker-compose.yml remains the general project compose file. The generated docker-compose.final.yml is the wizard-managed output.

Troubleshooting And Advanced Notes

  • If make env-storage or make env-server says .env is missing, run make env-base first.
  • You do not need to run make env-backup before rerunning env-base, env-storage, or env-server; those flows already back up the existing .env, and they also back up the generated compose file before changing it.
  • If you need to fully rebuild wizard-managed compose services from the current bundled templates, use make env-base-rewrite or make env-storage-rewrite.
  • If you switch between host-oriented and Docker-oriented workflows, rerun the relevant setup step instead of trying to manually merge old settings.
  • If the generated stack includes local Milvus, make sure MINIO_ACCESS_KEY_ID and MINIO_SECRET_ACCESS_KEY are available before running docker compose -f docker-compose.final.yml up -d.
  • For Docker deployment details beyond the interactive wizard, see DockerDeployment.md.

Typical Command Sequences

Remote models, local server

make env-base
lightrag-server

Remote LLM, local embedding and rerank in Docker

make env-base
docker compose -f docker-compose.final.yml up -d

Add storage after the base setup

make env-base
make env-storage
docker compose -f docker-compose.final.yml up -d

Add security and SSL before exposure

make env-base
make env-storage
make env-server
make env-security-check
docker compose -f docker-compose.final.yml up -d