Skip to content
Klutch.sh Docs

Deploying a Ragflow App

Introduction

Ragflow is an open-source retrieval-augmented generation (RAG) workflow builder that orchestrates document ingestion, vector indexing, and LLM queries. Deploying Ragflow with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage—all configured from klutch.sh/app. This guide covers installation, Dockerfile setup, environment variables, storage, Nixpacks overrides, and sample API calls.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Ragflow Dockerfile (GitHub is the only supported git source)
  • External Postgres (recommended) and a vector database (e.g., Qdrant) if your setup requires it
  • LLM API keys for your providers (store in Klutch.sh secrets)

For onboarding, see the Quick Start.

Architecture and ports

  • Ragflow serves HTTP on internal port 3000. Choose HTTP traffic and set the internal port to 3000.
  • Persistent storage is recommended for uploaded documents and cached embeddings; databases remain external.

Repository layout

ragflow/
├── Dockerfile              # Must be at repo root for auto-detection
├── app/                    # Ragflow source
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Build and run locally (ensure Postgres/vector DB are reachable):

Terminal window
docker build -t ragflow-local .
docker run -p 3000:3000 \
  -e DATABASE_URL=postgres://user:pass@localhost:5432/ragflow \
  -e VECTOR_DB_URL=http://localhost:6333 \
  -e OPENAI_API_KEY=sk-xxxx \
  ragflow-local

Dockerfile for Ragflow (production-ready)

Place this at the repo root; Klutch.sh auto-detects Dockerfiles.

FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build


FROM node:18-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV PORT=3000
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public
COPY --from=builder /app/package*.json ./
RUN npm ci --omit=dev
EXPOSE 3000
CMD ["npm", "run", "start"]

Notes:

— Pin Node to the version Ragflow supports; adjust if upstream changes. — Keep the Dockerfile at the repo root; Docker selection is automatic in Klutch.sh.

Environment variables (Klutch.sh)

Set these before deploying:

  • PORT=3000
  • DATABASE_URL=postgres://<user>:<password>@<host>:5432/<db>
  • VECTOR_DB_URL=https://<vector-host> (e.g., Qdrant or another vector service)
  • OPENAI_API_KEY=<your-api-key> (or other LLM provider keys)
  • Optional: EMBEDDING_MODEL, MAX_CHUNK_SIZE, RAGFLOW_BASE_URL=https://example-app.klutch.sh

If deploying without the Dockerfile and relying on Nixpacks:

  • NIXPACKS_NODE_VERSION=18
  • NIXPACKS_START_CMD=npm run start

Attach persistent volumes

If you cache documents or embeddings locally, add storage in Klutch.sh (path and size only):

  • /app/storage — uploaded docs/cache.

Ensure the path matches your Ragflow configuration.

Deploy Ragflow on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 3000.
  4. Add the environment variables above (database, vector DB, and LLM API keys).
  5. Attach a volume at /app/storage if you need local caching or uploads, sized for your content.
  6. Deploy. Your app will be reachable at https://example-app.klutch.sh.

Sample API usage

Health check:

Terminal window
curl -I https://example-app.klutch.sh/api/health

Example RAG query (placeholder endpoint, adjust to your API):

Terminal window
curl -X POST https://example-app.klutch.sh/api/rag/query \
  -H "Content-Type: application/json" \
  -d '{"question":"What is in the docs?","top_k":3}'

Health checks and production tips

  • Add an HTTP readiness probe to /api/health (or your chosen health endpoint).
  • Keep DB, vector DB, and LLM keys in Klutch.sh secrets; rotate regularly.
  • Pin Node and dependency versions; test upgrades in staging before production.
  • Monitor storage usage on /app/storage if enabled; resize volumes proactively.

Ragflow on Klutch.sh delivers reproducible Docker builds, managed secrets, and optional storage—without extra YAML or CI steps. Configure ports, env vars, and volumes, then launch your RAG workflows.