LightRAG 1.5.7

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Pick LightRAG 1.5.7 on Ubuntu 24.04 as the software version, choose your Region, then choose Launch through EC2.

Choose m5.large, your key pair and a security group as described above. LightRAG keeps its knowledge graph and vector index in memory while serving, so size up for a large corpus.

Size the root EBS volume for your documents. They and the knowledge base live under /var/lib/lightrag on the root volume, which you can grow later.

To launch with the AWS CLI instead, replace the values in angle brackets.

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --block-device-mappings 'DeviceName=/dev/sda1,Ebs={VolumeSize=30,VolumeType=gp3}' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=lightrag}]'

For LightRAG 1.5.7 on Ubuntu 24.04, the SSH user is ubuntu. Connect with your key pair.

ssh -i <your-key.pem> ubuntu@<public-ip>

First boot generates the certificate and the credentials, starts LightRAG, opens nginx and runs a sign-in check before it finishes. This takes about a minute. Confirm that the services are active and first boot has finished.

systemctl is-active lightrag nginx lightrag-firstboot
sudo test -f /var/lib/sac/data/lightrag-firstboot.done && echo FIRSTBOOT_DONE

active active active FIRSTBOOT_DONE

Only SSH and nginx listen on public addresses. LightRAG listens on loopback. Confirm the listeners.

sudo ss -lntp | awk 'NR>1 {print $4}' | grep -v '127.0.0.5' | sort

0.0.0.0:22 0.0.0.0:443 0.0.0.0:80 127.0.0.1:9621 [::]:22 [::]:443 [::]:80

Read the URL and the user name.

sudo grep -E '^LIGHTRAG_(URL|USERNAME)=' /root/lightrag-credentials.txt

LIGHTRAG_URL=https://ec2-<public-ip-dashed>.<region>.compute.amazonaws.com/ LIGHTRAG_USERNAME=admin

The password and the API key are in the same root-only file. Display the file when you need them.

sudo cat /root/lightrag-credentials.txt

• LIGHTRAG_URL is the web UI and API address. It uses the instance's public DNS name from EC2 instance metadata (the public IP address when the subnet has no public DNS names). The certificate also names the public and private IP addresses. To use your own DNS name, follow Step 11.
• LIGHTRAG_USERNAME and LIGHTRAG_PASSWORD sign in to the web UI.
• LIGHTRAG_APIKEY authenticates REST API calls. Send it in the X-API-Key header.

Open LIGHTRAG_URL in a browser. The certificate is self-signed, so your browser warns once. Continue past the warning, or install your own certificate (Step 11). Sign in as admin with the password from the file.

Send unauthenticated requests to the data, query and Ollama routes. Every one must return HTTP 401.

C=/etc/ssl/lightrag/lightrag.crt; U=https://127.0.0.1 for p in /health /graph/label/list /documents/pipeline_status /api/tags; do echo "GET $p (not signed in) -> HTTP $(curl -s --cacert $C -o /dev/null -w '%{http_code}' $U$p)"; done echo "POST /query (not signed in) -> HTTP $(curl -s --cacert $C -o /dev/null -w '%{http_code}' -X POST -H 'Content-Type: application/json' --data '{}' $U/query)" curl -s --cacert $C $U/auth-status | jq -c '{auth_configured, auth_mode, core_version}'

GET /health (not signed in) -> HTTP 401 GET /graph/label/list (not signed in) -> HTTP 401 GET /documents/pipeline_status (not signed in) -> HTTP 401 GET /api/tags (not signed in) -> HTTP 401 POST /query (not signed in) -> HTTP 401 {"auth_configured":true,"auth_mode":"enabled","core_version":"1.5.7"}

/api/tags is the Ollama-compatible API, which upstream leaves open by default. Here it needs the API key like everything else.

From another machine, use LIGHTRAG_URL instead of https://127.0.0.1. Add -k or the instance's certificate, because the certificate is self-signed.

The examples read the key or password from the credentials file and hand it to curl on standard input. It never appears on a command line or in your shell history.

C=/etc/ssl/lightrag/lightrag.crt; U=https://127.0.0.1
sudo sed -n 's/^LIGHTRAG_APIKEY=/X-API-Key: /p' /root/lightrag-credentials.txt | curl -s --cacert $C -H @- $U/health | jq -c '{status, auth_mode, core_version, llm_host: .configuration.llm_binding_host}' printf 'X-API-Key: %s\n' wrong-key | curl -s --cacert $C -o /dev/null -w 'wrong API key -> HTTP %{http_code}\n' -H @- $U/health
sudo sed -n 's/^LIGHTRAG_PASSWORD=/username=admin\&password=/p' /root/lightrag-credentials.txt | curl -s --cacert $C --data @- $U/login | jq -c '{token_type, auth_mode, signed_in: (.access_token | length > 0)}'

{"status":"healthy","auth_mode":"enabled","core_version":"1.5.7","llm_host":"https://api.openai.com/v1"} wrong API key -> HTTP 401 {"token_type":"bearer","auth_mode":"enabled","signed_in":true}

/login returns a session token. Send it as Authorization: Bearer <token>. The web UI uses the same flow.

After five wrong passwords from one address for one user name, LightRAG refuses that address for five minutes. nginx also limits how fast any one address can try.

All settings are in /etc/lightrag/lightrag.env. Only root can read it. It also holds the hashed password, the token secret and the API key, so do not share the file. Edit the file and restart LightRAG.

sudo nano /etc/lightrag/lightrag.env
sudo systemctl restart lightrag

OpenAI: Set your key on both lines. The defaults use gpt-4o-mini and text-embedding-3-small (1536 dimensions).

LLM_BINDING_API_KEY=<your-openai-api-key> EMBEDDING_BINDING_API_KEY=<your-openai-api-key>

An OpenAI-compatible server in your VPC (Ollama, vLLM, LM Studio, LiteLLM): Point both hosts at its /v1 URL. Set the model names it serves and the embedding size, and give any non-empty key it accepts. This example is for Ollama on another instance at 10.0.1.20.

LLM_BINDING_HOST=http://10.0.1.20:11434/v1 LLM_MODEL=qwen2.5:7b LLM_BINDING_API_KEY=<set-at-first-boot> EMBEDDING_BINDING_HOST=http://10.0.1.20:11434/v1 EMBEDDING_MODEL=bge-m3 EMBEDDING_DIM=1024 EMBEDDING_BINDING_API_KEY=<set-at-first-boot>

Allow the LightRAG instance to reach that server in its security group. Choose the embedding model before you add documents, because changing it later needs a new knowledge base (Step 13).

The values are literal, with no quotes and no $ expansion. Keep HOST=127.0.0.1. LightRAG refuses to start if the file reopens an upstream default (WHITELIST_PATHS other than empty or /health, CORS_ORIGINS containing *, a plaintext password, or the upstream token secret).

In the web UI, open Documents and upload files. LightRAG queues them, extracts entities and relationships with your model, and indexes them. The status changes to Completed.

The Knowledge Graph tab shows the entities and relationships. The Retrieval tab answers questions from them, with references to the source documents.

Once a model is connected, you can do the same through the API with the API key.

K=$(sudo sed -n 's/^LIGHTRAG_APIKEY=//p' /root/lightrag-credentials.txt)
curl -s -k -H "X-API-Key: $K" -F 'file=@report.pdf' https://<your-host>/documents/upload
curl -s -k -H "X-API-Key: $K" https://<your-host>/documents/pipeline_status
curl -s -k -H "X-API-Key: $K" -H 'Content-Type: application/json' \
  --data '{"query":"What are the main findings?","mode":"mix"}' https://<your-host>/query

The query modes are naive (vector search only), local (entities), global (relationships), hybrid and mix (graph plus vectors, the default in the UI). Ollama-compatible clients can use https://<your-host>/api/chat with the X-API-Key header.

The image ships an end-to-end check that you can run at any time. First boot runs it too. It reads the credentials file itself and talks to LightRAG over HTTPS through nginx, with the instance's certificate pinned.

The check confirms each of these:

• Port 80 redirects, and an unknown host name is dropped.
• Every data, query, upload, graph and Ollama route refuses an anonymous request.
• The API documentation is off.
• A wrong password, a wrong user, a wrong API key and a token signed with LightRAG's published default secret are all refused.
• This instance's password and API key work.

Run it.

sudo lightrag-verify.sh

port 80 -> 301 https://ec2-<public-ip-dashed>.<region>.compute.amazonaws.com/ ; an unknown Host is dropped on 80 and 443 ; certificate verifies for ec2-<public-ip-dashed>.<region>.compute.amazonaws.com anonymous: / -> 307 to the sign-in page, /auth-status gives no guest token, 8 GET + 10 POST data/query/upload/graph/Ollama routes and DELETE /documents 401, API docs 404 sign-in: wrong password 401, wrong user 401, this instance's password -> token -> 200; default-secret token 401; wrong API key 401, this instance's API key 200 (LightRAG 1.5.7) LIGHTRAG_ROUNDTRIP_OK

The files that matter are locked down, and the configuration keeps upstream's open defaults closed. Check the file permissions and the settings.

sudo stat -c '%a %U:%G %n' /etc/lightrag/lightrag.env /root/lightrag-credentials.txt /var/lib/lightrag/rag_storage /etc/ssl/lightrag/lightrag.key
sudo grep -E '^(HOST|WHITELIST_PATHS|CORS_ORIGINS|ENABLE_API_DOCS|NATIVE_MD_IMAGE_DOWNLOAD_ENABLED|LLM_BINDING_API_KEY)=' /etc/lightrag/lightrag.env
sudo grep -oE '^AUTH_ACCOUNTS=admin:\{bcrypt\}\$2b\$12\$' /etc/lightrag/lightrag.env

600 root:root /etc/lightrag/lightrag.env 600 root:root /root/lightrag-credentials.txt 700 lightrag:lightrag /var/lib/lightrag/rag_storage 600 root:root /etc/ssl/lightrag/lightrag.key HOST=127.0.0.1 WHITELIST_PATHS= CORS_ORIGINS= ENABLE_API_DOCS=false NATIVE_MD_IMAGE_DOWNLOAD_ENABLED=false LLM_BINDING_API_KEY= <set-at-first-boot>=admin:{bcrypt}$2b$12$

The password is stored only as a bcrypt hash. LightRAG runs unprivileged in a sandbox that can write only to its data and log directories. Neither LightRAG nor nginx can reach the instance metadata service, so a model endpoint can never be pointed at it. Confirm the sandbox settings.

systemctl show lightrag -p User -p ProtectSystem -p ReadWritePaths -p NoNewPrivileges -p IPAddressDeny
systemctl show nginx -p IPAddressDeny

IPAddressDeny=168.63.129.16/32 fd00:ec2::254/128 169.254.169.254/32 User=lightrag ReadWritePaths=/var/lib/lightrag /var/log/lightrag ProtectSystem=strict NoNewPrivileges=yes IPAddressDeny=168.63.129.16/32 fd00:ec2::254/128 169.254.169.254/32

nginx passes LightRAG a fixed host name and the real client address from the connection, never values a client sends. Confirm the proxy headers.

grep -E 'proxy_set_header (Host|X-Forwarded-For|X-Real-IP|Forwarded)' /etc/nginx/lightrag-proxy.conf

proxy_set_header Host $lightrag_host; proxy_set_header Forwarded ""; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $remote_addr;

The Python environment holds exactly the pinned set (135 packages including pip), with the security releases of its dependencies. Count the packages and check the key versions.

/opt/lightrag/venv/bin/pip freeze --all 2>/dev/null | wc -l; /opt/lightrag/venv/bin/pip freeze 2>/dev/null | grep -iE '^(lightrag-hku|aiohttp|cryptography|pillow|pypdf|pyjwt)=='

135 aiohttp==3.14.5 cryptography==50.0.2 lightrag-hku==1.5.7 pillow==13.0.0 PyJWT==2.15.1 pypdf==6.21.2

No credential reaches a log, the journal, the knowledge base, shell history, backups or /etc (other than the configuration file). Run the leak check to confirm.

sudo lightrag-secret-leak-check.sh

LEAKCHECK_OK no password, password hash, JWT secret or API key in the journal, auth.log, syslog, cloud-init, nginx and LightRAG logs, the knowledge base, shell history, MOTD, /var/backups, /etc (only lightrag.env), /usr/local, /opt/lightrag or /tmp

Point a DNS record at the instance, then set the name LightRAG is served as. This command mints a new self-signed certificate for the name, updates nginx's host rule and the URL in /root/lightrag-credentials.txt, reloads nginx and keeps the name across reboots.

sudo lightrag-set-hostname <your-domain>

Without a configured name, the instance re-reads its address from EC2 instance metadata at every boot. A stop and start that changes the public IP address therefore keeps LightRAG reachable.

To use a certificate from your own certificate authority instead, copy it over /etc/ssl/lightrag/lightrag.crt and lightrag.key (key mode 0600), then run sudo systemctl reload nginx. Running lightrag-set-hostname again replaces it with a self-signed one.

Replace the admin password, the session token secret and the API key if one of them was exposed, or whenever you want new ones.

sudo lightrag-rotate-credentials

The command writes the new hash, secret and key to /etc/lightrag/lightrag.env (your model settings are kept), restarts LightRAG and rewrites /root/lightrag-credentials.txt. Every signed-in session and the old API key stop working, so update your API clients.

To add more users, append ,<name>:{bcrypt}<hash> to the AUTH_ACCOUNTS line, where the hash comes from printf '%s' '<password>' | /opt/lightrag/venv/bin/python -c 'import bcrypt,sys; print(bcrypt.hashpw(sys.stdin.buffer.read(), bcrypt.gensalt()).decode())', then restart LightRAG. Plaintext passwords are refused.

The knowledge base (/var/lib/lightrag/rag_storage) and the uploaded originals (/var/lib/lightrag/inputs) are plain files. Back them up with EBS snapshots, or copy them while LightRAG is stopped.

sudo systemctl stop lightrag
sudo tar -czf /root/lightrag-backup.tgz -C /var/lib/lightrag rag_storage inputs
sudo systemctl start lightrag

To start over (for example after changing the embedding model), stop LightRAG and move rag_storage aside. Recreate it empty with owner lightrag and mode 0700, start LightRAG, and upload your documents again.

/opt/lightrag/venv/bin/python -c 'import lightrag; print("LightRAG", lightrag.__version__)'; nginx -v 2>&1; lsb_release -ds ls /usr/share/doc/sac/lightrag/

LightRAG 1.5.7 nginx version: nginx/1.24.0 (Ubuntu) Ubuntu 24.04.5 LTS LICENSE VERSION dependency-licences.txt requirements-pinned.txt

These are the components on the image:

• LightRAG 1.5.7: /opt/lightrag/venv, service lightrag, settings /etc/lightrag/lightrag.env, data /var/lib/lightrag, logs /var/log/lightrag and journalctl -u lightrag
• nginx 1.24.0: TLS on 443, redirect on 80, site /etc/nginx/sites-available/sac-lightrag
• Ubuntu 24.04 LTS: unattended security upgrades on