Docker on KnightLi Blog

Deploy Syncthing with Docker: Compose, Ports, and Volume Mapping Pitfalls

Sun, 31 May 2026 12:12:05 +0800

Syncthing Series

Deploying Syncthing in Docker is a good fit for a NAS, a home server, or a VPS. It can act as an always-on sync node for photos, documents, Markdown notes, or download folders.

The important part of a Docker-based Syncthing setup is not merely whether the container starts. The real questions are:

whether the configuration directory is persistent;
whether the data folders you want to sync are mapped into the container;
whether ports and permissions are prepared in advance.

If these details are not handled well, a container update may wipe your configuration, the path you enter in the Web UI may not point to the real host folder, or sync tasks may fail with Permission denied.

Directory Planning

Start by creating a dedicated directory on the server or NAS, for example:

1
2

mkdir -p ~/syncthing
cd ~/syncthing

Put docker-compose.yml in this directory, and keep Syncthing’s configuration in a subdirectory:

1
2
3

syncthing/
├── docker-compose.yml
└── config/

The actual sync data can live in existing host paths, for example:

1
2

/volume1/downloads
/volume1/photos

Keep the configuration directory separate from the data directories. config stores Syncthing’s own configuration, keys, and index database. Folders such as downloads and photos are the actual data you want to sync.

Option 1: Docker Compose

Docker Compose is the recommended approach because updates, restarts, and migrations are easier to understand later.

Create ~/syncthing/docker-compose.yml:

version: "3"

services:
  syncthing:
    image: syncthing/syncthing:latest
    container_name: syncthing
    hostname: my-nas-syncthing
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
    volumes:
      - ./config:/var/syncthing/config
      - /volume1/downloads:/var/syncthing/downloads
      - /volume1/photos:/var/syncthing/photos
    ports:
      - 8384:8384
      - 22000:22000/tcp
      - 22000:22000/udp
      - 21027:21027/udp
    restart: unless-stopped

Start it:

`1`	`docker compose up -d`

Check the status:

1
2

docker compose ps
docker logs -f syncthing

Open the Web UI:

`1`	`http://server-ip:8384`

After the first login, set a GUI username and password first.

Option 2: docker run

For quick testing, you can also start Syncthing directly with docker run:

docker run -d \
  --name syncthing \
  --hostname my-nas-syncthing \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Asia/Shanghai \
  -p 8384:8384 \
  -p 22000:22000/tcp \
  -p 22000:22000/udp \
  -p 21027:21027/udp \
  -v /path/to/config:/var/syncthing/config \
  -v /path/to/data1:/var/syncthing/data1 \
  --restart unless-stopped \
  syncthing/syncthing:latest

Replace /path/to/config and /path/to/data1 with real host paths.

For example:

1
2

-v /volume1/docker/syncthing/config:/var/syncthing/config
-v /volume1/photos:/var/syncthing/photos

For long-term use, convert this into a Compose file so you do not need to rebuild the full command every time the container is recreated.

Container Paths and Host Paths

Docker beginners often get confused by paths.

For example, this volume mapping:

1
2

volumes:
  - /volume1/photos:/var/syncthing/photos

The left side, /volume1/photos, is the host path. The right side, /var/syncthing/photos, is the path inside the container.

When adding a sync folder in the Syncthing Web UI, the folder path must be the container path:

`1`	`/var/syncthing/photos`

That way Syncthing is actually operating on this host directory:

`1`	`/volume1/photos`

If you enter /volume1/photos in the Web UI, that path usually does not exist inside the container. Syncthing may report an error, or it may create a new directory inside the container filesystem that you did not intend to use.

Persist the Configuration Directory

This line is critical:

`1`	`- ./config:/var/syncthing/config`

Syncthing stores its configuration files, device keys, and index database in the configuration directory. If this directory is not mounted to the host, deleting or recreating the container may change the device ID and invalidate existing device pairings.

Use a stable host path such as:

`1`	`/volume1/docker/syncthing/config`

Do not put the configuration directory in a temporary location, and do not mix it with the actual sync data directories.

Ports and Firewalls

Common ports are:

8384/TCP   Web UI administration
22000/TCP Device sync traffic
22000/UDP QUIC sync traffic
21027/UDP Local discovery

If Syncthing runs on a home NAS, usually check:

whether the NAS firewall allows these ports;
whether Docker bridge port mapping is correct;
whether the router isolates Wi-Fi from wired devices;
whether the phone and computer are on the same subnet.

If Syncthing runs on a cloud server, also check the cloud provider’s security group. In particular, if 22000/TCP and 22000/UDP are not allowed, other devices may only connect through a relay, and the speed will be much slower.

8384 is the administration port. Do not expose it directly to the public internet. If remote administration is necessary, at least set a strong password, and preferably combine it with a reverse proxy, HTTPS, access control, or a VPN.

Permission Issues: PUID and PGID

If Syncthing starts and the Web UI is accessible, but a sync folder reports:

`1`	`Permission denied`

the container process usually does not have read/write permission on the host directory.

Check the UID and GID of the current user on the host:

id

The output may look like this:

`1`	`uid=1000(user) gid=1000(user) groups=1000(user)`

Then set the corresponding values in Compose:

1
2
3

environment:
  - PUID=1000
  - PGID=1000

Also confirm that the host directory itself allows this user to read and write:

`1`	`ls -ld /volume1/photos`

If necessary, adjust the owner or permissions:

`1`	`sudo chown -R 1000:1000 /volume1/photos`

On a NAS, do not blindly run recursive permission changes on an entire shared directory, especially if it is shared by multiple users. A safer approach is to prepare a dedicated sync directory for Syncthing, or grant the corresponding user access from the NAS permission management interface.

First-Time Web UI Security

After the container starts, visit:

`1`	`http://server-ip:8384`

On the first visit, Syncthing usually prompts you to set a GUI username and password. Do not skip this step.

Recommended practice:

set a GUI username and strong password immediately;
do not expose 8384 to the public internet;
use a VPN, SSH tunnel, or controlled reverse proxy for remote access;
if using a reverse proxy, proxy only the Web UI and do not accidentally expose unnecessary ports.

If someone else controls the administration interface, they may be able to add devices, modify shared folders, and change sync relationships. Syncthing encrypts data in transit, but the administration entry point still needs protection.

Add Sync Folders in the Web UI

Take a photo directory as an example. The Compose file already mounts:

`1`	`- /volume1/photos:/var/syncthing/photos`

When adding the folder in the Web UI:

Folder Label: you can use Photos;
Folder ID: use a stable English ID such as photos;
Folder Path: enter /var/syncthing/photos;
Sharing: choose the devices that should receive this folder;
Folder Type: choose Send & Receive, Send Only, or Receive Only based on the data flow.

If this Docker node is the central NAS node, common choices are:

regular documents: Send & Receive;
phone photo collection: Receive Only on the NAS;
outbound distribution folder: Send Only on the NAS.

Choose based on the intended direction of the data. Do not set every folder to bidirectional sync without thinking.

Update the Container

With Compose, updates are usually:

1
2

docker compose pull
docker compose up -d

As long as the configuration directory and data directories are mounted correctly, updating the container will not lose the device ID, pairings, or sync folder configuration.

Before updating, you can back up the configuration directory:

`1`	`tar -czf syncthing-config-backup.tar.gz ./config`

The configuration directory contains device private keys. Do not upload the backup casually to a public location.

Common Issues

Web UI Does Not Open

First check whether the container is running:

1
2

docker ps
docker logs syncthing

Then check port mappings:

`1`	`docker port syncthing`

If the container is healthy but the page still does not open, check the host firewall, NAS firewall, or cloud security group.

Folder Does Not Exist After Adding It

Check whether the path entered in the Web UI is the container path.

For example, if the host path is:

`1`	`/volume1/downloads`

and the container path is:

`1`	`/var/syncthing/downloads`

the Web UI should use the latter.

Only Relay Connections, Very Slow

Check first:

whether 22000/TCP is allowed;
whether 22000/UDP is allowed;
whether router port forwarding is correct;
whether the cloud security group allows both TCP and UDP;
whether the local firewall blocks Docker’s mapped ports.

Relays improve reachability, but they are not suitable for long-term heavy sync traffic.

File Permissions Are Wrong After Sync

First confirm that the container user is correct, then check the host directory permissions. Linux, NAS, and Windows shared folders have different permission models. Do not treat Syncthing as a permission repair tool.

For cross-system sync, try to sync ordinary files and directories. Avoid syncing system folders that depend on complex ACLs, ownership, or extended attributes.

A More Stable Setup

If your goal is to use a NAS or server as the central node, design it like this:

Run Syncthing with Docker on the NAS.
Mount the configuration directory to /volume1/docker/syncthing/config.
Mount each data category separately, for example /volume1/photos and /volume1/notes.
Add the NAS device ID from phones and computers.
Enable file versioning on important folders on the NAS side.
Keep the Web UI accessible only on the LAN or through a VPN.
Back up the NAS independently. Do not treat sync as the only backup.

In this setup, Syncthing handles device-to-device synchronization, the NAS provides always-on availability and version buffering, and real backup is still handled by snapshots, external disks, or off-site backups.

Summary

The key to deploying Syncthing with Docker is separating the container lifecycle from the sync data lifecycle.

The container can be updated, recreated, or migrated at any time. The configuration directory and data directories, however, must remain stable on the host. Use container paths in the Web UI, handle host permissions with PUID, PGID, and directory access rules, and open ports according to the actual network environment.

Once these pieces are clear, Syncthing works very well as a lightweight sync layer between a NAS, a server, and personal devices.

rembg Project Notes: A Local Background Removal Tool

Sun, 19 Apr 2026 08:56:01 +0800

rembg is an image background removal tool. It can be used as a command-line tool, a Python library, an HTTP server, or a Docker container. Its purpose is straightforward: take an image as input and output the foreground with an alpha channel. It works well for product images, portraits, material processing, and automated image workflows.

The best part is that it can run locally. If you do not want to upload source images to an online cutout service, need batch processing, or want to connect background removal to scripts and business systems, rembg is easier to automate than a web tool.

01 Installation

The current version requires Python >=3.11,<3.14. Choose the backend according to your hardware:

`1`	`pip install "rembg[cpu]"`

If you need the CLI, add cli:

`1`	`pip install "rembg[cpu,cli]"`

For NVIDIA CUDA environments, install the GPU version:

`1`	`pip install "rembg[gpu,cli]"`

For AMD ROCm environments, install onnxruntime-rocm first by following the official ROCm instructions, then install:

`1`	`pip install "rembg[rocm,cli]"`

Most GPU-version trouble is not in rembg itself, but in whether onnxruntime-gpu, CUDA, cuDNN, and the driver versions match. If installation fails, first confirm the workflow with the CPU version, then deal with the GPU environment.

02 CLI Subcommands

After installing the CLI, you can use rembg directly in the terminal. It mainly provides 4 subcommands:

i: process a single file.
p: process a whole folder.
s: start an HTTP server.
b: process an RGB24 pixel binary stream, often used with FFmpeg.

Show help:

1
2

rembg --help
rembg i --help

Process a single local image:

`1`	`rembg i input.png output.png`

Pipe in a remote image:

`1`	`curl -s http://input.png \| rembg i > output.png`

Specify a model:

`1`	`rembg i -m u2netp input.png output.png`

Return only the mask:

`1`	`rembg i -om input.png mask.png`

Enable alpha matting:

`1`	`rembg i -a input.png output.png`

-a can sometimes produce more natural hair, fuzzy edges, and semi-transparent boundaries, but it is slower and does not noticeably improve every image.

03 Batch Processing Folders

Batch processing is one of the more useful parts of rembg. Put source images in one directory and output results to another:

`1`	`rembg p path/to/input path/to/output`

Watch for directory changes and automatically process new or modified images:

`1`	`rembg p -w path/to/input path/to/output`

This mode works well with download scripts, product image cleanup, and material folders. For example, drop images into input, and let rembg generate transparent PNG files in output.

04 Using It as a Python Library

If you want to integrate it into your own script, the simplest way is remove:

from rembg import remove

with open("input.png", "rb") as i:
    with open("output.png", "wb") as o:
        input_data = i.read()
        output_data = remove(input_data)
        o.write(output_data)

You can also process PIL images directly:

from rembg import remove
from PIL import Image

input_image = Image.open("input.png")
output_image = remove(input_image)
output_image.save("output.png")

For batch processing, reuse a session so the model is not initialized again for every image:

from pathlib import Path
from rembg import remove, new_session

session = new_session()

for file in Path("input").glob("*.png"):
    output = file.parent / f"{file.stem}.out.png"
    with open(file, "rb") as i:
        with open(output, "wb") as o:
            o.write(remove(i.read(), session=session))

If you are building a long-running image processing service, session reuse is usually a better fit than repeatedly calling the CLI.

05 Starting an HTTP Server

rembg can also start an HTTP server directly:

`1`	`rembg s --host 0.0.0.0 --port 7000 --log_level info`

After startup, visit:

`1`	`http://localhost:7000/api`

Remove background from a URL:

`1`	`curl -s "http://localhost:7000/api/remove?url=http://input.png" -o output.png`

Upload a local image:

`1`	`curl -s -F file=@input.jpg "http://localhost:7000/api/remove" -o output.png`

If you only need the API and do not need the Gradio UI, disable the UI to reduce idle CPU usage:

`1`	`rembg s --no-ui`

Server mode is suitable for internal tools, automation flows, or other applications. But it is not a complete image asset management system. Authentication, rate limiting, queues, and file cleanup still need to be handled outside it.

06 Docker Usage

The CPU version can use the official image directly:

`1`	`docker run -v .:/data danielgatis/rembg i /data/input.png /data/output.png`

CUDA acceleration requires NVIDIA Container Toolkit on the host, and usually requires building an image from the project’s Dockerfile_nvidia_cuda_cudnn_gpu:

`1`	`docker build -t rembg-nvidia-cuda-cudnn-gpu -f Dockerfile_nvidia_cuda_cudnn_gpu .`

Run example:

docker run --rm -it --gpus all \
  -v /dev/dri:/dev/dri \
  -v $PWD:/data \
  rembg-nvidia-cuda-cudnn-gpu \
  i -m birefnet-general /data/input.png /data/output.png

The official README notes that the GPU image is much larger than the CPU image, and model files are not included in the image. To avoid downloading models repeatedly, mount the model directory:

`1`	`docker run -v /path/to/models:/root/.u2net ...`

07 Model Choices

When rembg uses a model for the first time, it automatically downloads it to ~/.u2net/. Common models include:

u2net: a general-purpose model for common cases.
u2netp: a lightweight version with friendlier speed and size.
u2net_human_seg: focused on human segmentation.
u2net_cloth_seg: focused on clothing parsing.
silueta: similar to u2net, but smaller.
isnet-general-use: a newer general-purpose model.
isnet-anime: focused on anime character segmentation.
birefnet-general: a general image model used in the README example.
sam: can work with extra parameters such as prompt points.

In practice, do not choose only by model name. Product images, portraits, anime images, complex backgrounds, and transparent objects all have different requirements. A safer approach is to pick a representative image set, run several models, compare edges, missed areas, false removals, and speed, then decide the default model.

If you want to use a custom .onnx model, place it in the default model directory ~/.u2net/, and set this when needed:

`1`	`MODEL_CHECKSUM_DISABLED=1`

This can prevent rembg from overwriting your model file because of checksum logic.

08 Suitable Use Cases

rembg fits these tasks well:

Batch-generate transparent-background product images.
Extract foregrounds from portraits, ID photos, and material images.
Integrate background removal into Python scripts or backend services.
Deploy a simple background removal API on an internal network.
Use FFmpeg pipes to process video frames or image sequences.
Keep privacy-sensitive or copyrighted materials away from third-party online services.

It is less suitable for these cases:

You need hand-retouched edges and complex transparent materials.
Every image must reach stable commercial photography quality.
You want a full online design tool instead of only background removal.
You do not want to maintain a Python or Docker environment.
Your GPU driver, CUDA, or ROCm environment is already messy and the project needs to launch quickly.

09 Usage Advice

If you only process images occasionally, the CPU version is enough:

`1`	`pip install "rembg[cpu,cli]"`

For batch-processing thousands of images, consider:

Reusing a Python session.
Fixing the model directory to avoid repeated downloads.
Using an SSD for inputs, outputs, and model files.
Testing model quality on a small batch first.
Deciding whether GPU acceleration is worth the trouble afterward.

The value of GPU is mainly batch throughput. For occasional single-image processing, the setup cost may be higher than the time saved. Especially on Windows, when CUDA, cuDNN, and onnxruntime-gpu versions do not match, the CPU version can be the more practical choice.

10 Quick Take

rembg is simple, open source, and flexible: it can run as a CLI, be called from Python, expose HTTP endpoints, or be packaged with Docker. It is a good base component for local automatic background removal.

But it is not a magic eraser. Complex backgrounds, fine subject edges, transparent materials, shadow preservation, and commercial-grade retouching may still require manual work or a more specialized workflow. When putting it into batch automation, it is best to keep a human review or failed-sample recovery step.

If the goal is to remove backgrounds from a batch of images quickly while keeping the process local, rembg is worth keeping in the toolbox.

GitHub project: https://github.com/danielgatis/rembg
README: https://github.com/danielgatis/rembg/blob/main/README.md
Releases: https://github.com/danielgatis/rembg/releases
ONNX Runtime installation matrix: https://onnxruntime.ai/

codex-quota Practical Guide: Local, Web, and Docker Usage with Original CLI Commands

Thu, 16 Apr 2026 18:13:04 +0800

What This Project Does

codex-quota is a lightweight tool for checking ChatGPT Codex quota usage, with data fetched from https://chatgpt.com/backend-api/wham/usage.

Main features:

Supports both single-account and multi-account queries (account/*.auth.json).
Outputs five_hour%, weekly%, weekly_reset, and marks the source (network or cache).
Uses exponential backoff retries for temporary failures (408, 429, 5xx).
Includes local caching to reduce repeated requests when quota is already exhausted.
Provides a Web Dashboard, JSON API, and auth file management pages.

Advantages:

Lightweight: runs with simple scripts and minimal dependencies.
Practical: supports both CLI and Web entry points.
Deployable: works with Docker and Docker Compose.
Easy to operate: includes retry, cache, and scheduled refresh support.

Prepare Account Credentials First

Create credential files in account/<name>.auth.json, for example:

{
  "tokens": {
    "access_token": "eyJ...",
    "account_id": "user-xxxxxxxx"
  }
}

Explanation:

access_token and account_id are required by the usage API.
<name> in the filename is used as the account name in output.

Local CLI Usage (Keep Original Commands)

Install dependencies:

`1`	`pip install -r requirements.txt`

Explanation: installs project dependencies.

Query all accounts:

`1`	`python codex_quota.py`

Explanation: reads account/*.auth.json and outputs quota summary for all accounts.

Query one account:

`1`	`python codex_quota.py your_account_name`

Explanation: only queries account/your_account_name.auth.json.

Force refresh (skip cache):

`1`	`python codex_quota.py --refresh`

Explanation: ignores local cache and fetches fresh data directly.

CLI Options (Aligned with README)

account_name: optional account name (without .auth.json).
--account-dir: auth directory, default account.
--chatgpt-url: quota API endpoint.
--raw-json: print full JSON response body.
--raw-headers: print response headers.
--refresh: ignore cache.
--retries: retry count, default 3.
--retry-delay: base retry delay in seconds, default 2.0.

Web Dashboard Usage (Keep Original Command)

Start the service:

`1`	`python codex_quota_service.py --host 0.0.0.0 --port 8081`

Explanation: starts HTTP service listening on port 8081.

Access URL: http://localhost:8081

Service options:

--host: bind address, default 0.0.0.0.
--port: service port, default 8081.
--interval-seconds: scheduled refresh interval, default 3600.
--account-dir: auth directory, default account.
--state-file: state file path, default <account-dir>/codex_quota_web_results.json.
--account-name: optional single-account mode.
--chatgpt-url: quota API endpoint.
--retries: retry count.
--retry-delay: base retry delay.
--refresh: ignore CLI cache during scheduled runs.

HTTP Endpoints (For Automation)

GET /: dashboard page.
GET /api/results: latest results in JSON.
GET /refresh: trigger immediate refresh and redirect to /.
GET /auth: list auth files.
GET /auth/new: form to create auth file.
GET /auth/edit?name=<account>: form to edit auth file.
POST /auth/save: create/update auth file.
POST /auth/delete: delete auth file.

Docker Usage (Keep Original Commands)

Build image:

`1`	`docker build -t codex-quota .`

Explanation: builds the current project as image codex-quota.

Run container (map 8081):

`1`	`docker run --rm -p 8081:8081 -v ./account:/app/account codex-quota`

Explanation:

--rm: remove container automatically after exit.
-p 8081:8081: map host port to container port.
-v ./account:/app/account: mount local credentials into container.

Access URL: http://localhost:8081

Docker Compose Usage (Keep Original Command)

Start:

`1`	`docker compose up --build`

Explanation: build and start services based on docker-compose.yml.

Access URL: http://localhost:8081

Usage Tips

For multi-account scenarios, use Dashboard first for unified view and auth management.
For alerting or automation, prefer GET /api/results.
Do not commit real access_token values to public repositories.
If you see many temporary failures, increase --retries and --retry-delay.

Build Docker Images in VS Code on Windows: From Setup to Build

Thu, 16 Apr 2026 10:20:00 +0800

If you want to build Docker images directly from VS Code on Windows, the workflow is straightforward. You only need three parts: prepare the environment, create a Dockerfile, then run the build.

01 Prerequisites

Make sure these two items are ready:

Install and run Docker Desktop.
Install the official Microsoft Docker extension in VS Code.

On Windows, using the WSL 2 backend in Docker Desktop (Settings > Resources > WSL Integration) is usually more stable and faster.

02 Prepare a Dockerfile

If your project does not have one yet, VS Code can generate it:

Open your project folder in VS Code.
Press F1 or Ctrl+Shift+P to open the Command Palette.
Run Docker: Add Docker Files to Workspace.
Choose your platform (Node.js, Python, .NET, etc.) and follow the prompts.

You will typically get at least:

Dockerfile
.dockerignore

This gives you a working baseline that you can refine later.

03 Three Ways to Build the Image

Method A: Right-click Dockerfile

In the File Explorer, right-click Dockerfile, select Build Image..., and enter an image tag.

Method B: Command Palette

Press F1, run Docker: Build Image, then select context and tag.

Method C: Integrated Terminal

`1`	`docker build -t your-image-name .`

This command builds an image from the current directory context with the tag your-image-name.

04 Quick Checks for Common Issues

Docker Desktop is not running: verify it is started.
Build is very slow: check whether WSL 2 backend is enabled.
Build cannot find files: ensure your terminal is at the project root and files are inside build context.
Docker resources do not show in VS Code: restart VS Code and check Docker CLI (docker version).

Summary

Building Docker images in VS Code on Windows is mostly a setup problem. Once Docker Desktop and the VS Code Docker extension are in place, you can generate Docker files quickly and build images from either the UI or the terminal.

RAGFlow Project Notes: Features and Usage of an Open-Source RAG Engine

Wed, 15 Apr 2026 22:09:25 +0800

RAGFlow is an open-source RAG engine from infiniflow. Its goal is not merely to provide a thin “upload documents and ask questions” shell, but to bring document parsing, chunking, retrieval, reranking, citation tracing, model configuration, agent capabilities, and API integration into one complete workflow.

If you are building an enterprise knowledge base, document Q&A, a support assistant, internal information retrieval, or you want to give an LLM a more reliable context layer, RAGFlow is one of the open-source options worth serious attention.

01 What Problem RAGFlow Solves

Most RAG systems run into three common issues:

Document parsing is unstable, especially for PDFs, scanned files, tables, images, and complex layouts.
Chunking strategy is opaque, so retrieval may look correct while the actual context is incomplete.
Answers lack trustworthy citations, making it hard for users to verify where the response came from.

RAGFlow focuses on exactly these problems. The project README emphasizes Deep document understanding, template-based chunking, chunk visualization, citation grounding, and multi-path retrieval with reranking. In other words, it cares more about “high-quality input leads to high-quality answers” than simply wiring a vector database to a chat UI.

02 Core Features

1. Deep Document Understanding

RAGFlow can extract knowledge from complex unstructured data. The README lists formats such as Word, PPT, Excel, TXT, images, scanned documents, structured data, and web pages.

This matters a lot for enterprise knowledge bases. Real-world material is rarely clean Markdown. It is usually a mix of contracts, reports, tables, scanned PDFs, product manuals, screenshots, and web content. If parsing quality is weak, retrieval and LLM answers will both suffer.

2. Template-Based Chunking

RAGFlow provides template-based chunking. The value here is that chunking is not a black box; different document types can use different strategies.

For example, articles, papers, tables, Q&A documents, image explanations, and contract clauses all need different chunk boundaries and granularity. Template-based chunking helps reduce problems like broken sentences, lost table context, and separated headings and body text.

3. Traceable Citations

RAGFlow emphasizes grounded citations, meaning answers can be traced back to source passages. It also offers chunk visualization, making it easier for people to inspect and adjust parsing and chunking results.

This is especially important in production. Internal enterprise Q&A is not only about producing something that “looks right”; it also has to be verifiable. For policy, compliance, finance, technical documents, and customer support content, citations and traceability are close to mandatory.

4. Automated RAG Workflow

RAGFlow turns the RAG lifecycle into a more complete workflow:

Create a knowledge base
Upload or sync data
Parse documents
Review and adjust chunks
Configure LLM and embedding models
Run multi-path retrieval and reranking
Build chat assistants
Integrate through APIs into business systems

That makes it closer to a RAG platform than a single library. For teams, both the UI and the API matter: non-engineers can maintain the knowledge base, while engineers can integrate the capability into existing systems.

5. Agent, MCP, and Workflow Extensions

Recent RAGFlow updates already include Agentic workflow, MCP, Agent Memory, and code execution components. That suggests it is no longer limited to traditional knowledge-base Q&A and is also moving toward agent-oriented scenarios.

A typical pattern is that an agent can use RAGFlow as a reliable enterprise knowledge layer: retrieve from the knowledge base when it needs context, generate answers with citations, and combine that with tools or workflow steps when necessary.

03 Basic Usage Flow

According to the official quickstart documentation, the common usage path for RAGFlow can be summarized in the following steps.

1. Prepare the Environment

The basic requirements listed in the official README are:

CPU >= 4 cores
RAM >= 16 GB
Disk >= 50 GB
Docker >= 24.0.0
Docker Compose >= v2.26.1

If you want to use the sandbox for the code executor, you also need gVisor. Another practical note is that the official Docker images mainly target x86 platforms. For ARM64, the project documentation recommends building the image yourself.

2. Clone the Project

1
2

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker

3. Check `vm.max_map_count`

RAGFlow deployment depends on components such as Elasticsearch or OpenSearch, so on Linux you usually need to verify:

`1`	`sysctl vm.max_map_count`

If the value is below 262144, you can set it temporarily:

`1`	`sudo sysctl -w vm.max_map_count=262144`

If you want the change to persist after reboot, add it to /etc/sysctl.conf.

4. Start with Docker Compose

You can start the CPU mode directly:

`1`	`docker compose -f docker-compose.yml up -d`

If you want GPU acceleration for DeepDoc tasks, the README shows enabling DEVICE=gpu in .env before startup:

1
2

sed -i '1i DEVICE=gpu' .env
docker compose -f docker-compose.yml up -d

Then inspect the logs:

`1`	`docker logs -f docker-ragflow-cpu-1`

Once the services are ready, open the machine address in your browser. Under the default configuration, that is typically:

`1`	`http://IP_OF_YOUR_MACHINE`

5. Configure Model API Keys

RAGFlow needs LLM and embedding model configuration. The README mentions choosing the default LLM factory in service_conf.yaml.template and updating the corresponding API_KEY.

In practice, you need to configure models according to your provider:

Chat model
Embedding model
Rerank model
Multimodal model, if you want to understand images inside PDFs or DOCX files

6. Create the Knowledge Base and Upload Documents

After the service starts, the typical workflow is:

Log in to the Web UI.
Create a dataset or knowledge base.
Upload documents or configure a data source sync.
Wait for parsing to finish.
Inspect chunk results and adjust them when necessary.
Create a chat assistant and attach the knowledge base.
Test answer quality and citation sources.

If you need to integrate with a business system, you can continue with the RAGFlow API or SDK and connect retrieval and chat capabilities to your own application.

04 Suitable Scenarios

RAGFlow fits these kinds of needs:

Enterprise internal knowledge-base Q&A
Product manuals, technical documentation, and FAQ retrieval
Customer support and pre-sales assistants
Traceable Q&A over contracts, reports, and policy documents
Unified handling of multi-format materials
Teams that want both UI-based maintenance and API integration
Systems that want to use RAG as the context layer for agents

It is especially suitable when document formats are complex, citations matter, and people want to inspect or intervene in parsing results.

05 What to Watch Out For

First, RAGFlow is not a lightweight script. It has real infrastructure requirements. The official recommendation is at least 4 CPU cores, 16 GB RAM, and 50 GB disk. If you only want Q&A over a small amount of Markdown, a full platform may be unnecessary.

Second, document quality still matters. RAGFlow can improve parsing and chunking, but it cannot magically make low-quality, outdated, or contradictory source material reliable. Knowledge-base governance still matters before production.

Third, model selection directly affects quality. Embedding, rerank, chat, and multimodal model choices all influence retrieval and answer quality. RAGFlow gives you the workflow, but the final result still depends on data, models, and tuning.

Fourth, production deployments need careful attention to permissions and data security. Enterprise knowledge bases often contain internal documents, so deployment model, access control, logs, API keys, and model-provider data policy all need to be designed in advance.

06 Quick Take

RAGFlow’s strength is that it turns the hardest parts of RAG into platform capabilities: complex document parsing, explainable chunking, citation grounding, multi-path retrieval, reranking, model configuration, Web UI, API access, and agent extensions.

If what you need is a verifiable, maintainable enterprise knowledge base that can connect to business systems, RAGFlow is more complete than a “vector database plus a simple chat UI” setup. On the other hand, if you only need small-scale personal Q&A over simple data, a lighter RAG framework may be more resource-efficient.

GitHub project: https://github.com/infiniflow/ragflow
Official docs: https://ragflow.io/docs/dev/
Online demo: https://cloud.ragflow.io

Docker on KnightLi Blog

Deploy Syncthing with Docker: Compose, Ports, and Volume Mapping Pitfalls

Syncthing Series

Directory Planning

Option 1: Docker Compose

Option 2: docker run

Container Paths and Host Paths

Persist the Configuration Directory

Ports and Firewalls

Permission Issues: PUID and PGID

First-Time Web UI Security

Add Sync Folders in the Web UI

Update the Container

Common Issues

Web UI Does Not Open

Folder Does Not Exist After Adding It

Only Relay Connections, Very Slow

File Permissions Are Wrong After Sync

A More Stable Setup

Summary

rembg Project Notes: A Local Background Removal Tool

01 Installation

02 CLI Subcommands

03 Batch Processing Folders

04 Using It as a Python Library

05 Starting an HTTP Server

06 Docker Usage

07 Model Choices

08 Suitable Use Cases

09 Usage Advice

10 Quick Take

Related Links

codex-quota Practical Guide: Local, Web, and Docker Usage with Original CLI Commands

What This Project Does

Prepare Account Credentials First

Local CLI Usage (Keep Original Commands)

CLI Options (Aligned with README)

Web Dashboard Usage (Keep Original Command)

HTTP Endpoints (For Automation)

Docker Usage (Keep Original Commands)

Docker Compose Usage (Keep Original Command)

Usage Tips

Build Docker Images in VS Code on Windows: From Setup to Build

01 Prerequisites

02 Prepare a Dockerfile

03 Three Ways to Build the Image

Method A: Right-click Dockerfile

Method B: Command Palette

Method C: Integrated Terminal

04 Quick Checks for Common Issues

Summary

RAGFlow Project Notes: Features and Usage of an Open-Source RAG Engine

01 What Problem RAGFlow Solves

02 Core Features

1. Deep Document Understanding

2. Template-Based Chunking

3. Traceable Citations

4. Automated RAG Workflow

5. Agent, MCP, and Workflow Extensions

03 Basic Usage Flow

1. Prepare the Environment

2. Clone the Project

3. Check vm.max_map_count

4. Start with Docker Compose

5. Configure Model API Keys

6. Create the Knowledge Base and Upload Documents

04 Suitable Scenarios

05 What to Watch Out For

06 Quick Take

Related Links

3. Check `vm.max_map_count`