Use cases
Running Ragmux on-prem: where personal data goes, and what KVKK asks about it
A map of every place a Ragmux request, document or query can send text, so you can decide what stays on-prem under Turkey's KVKK. Not legal advice.
Updated: Last reviewed: Verified against Ragmux 0.6.0
“Where does our personal data go?” is the first question a Turkish company’s data protection owner asks about any AI system, and for a gateway with retrieval built in the honest answer is a list rather than a sentence. A request to Ragmux can touch a database, an embedding endpoint, a chat endpoint and, depending on settings, a reranker and a query-rewriting model. Each one is a place text can go, and each one is a connection you chose. This page lists them, so that the decision about what stays on-prem is made against concrete flows rather than a feeling.
It is a description of software behaviour, not legal advice. What KVKK requires of you, and whether a given flow is acceptable in your situation, is for your data controller and your counsel to decide.
What KVKK asks that a gateway can inform
Two provisions of Law No. 6698 are the ones an architecture review keeps returning to.
Article 9, transfers abroad. Law No. 7499, published in the Resmî Gazete on 12 March 2024, replaced Article 9 in full, and the new text took effect on 1 June 2024. Under it, a transfer abroad rests on one of three tiers: a Board decision that the destination provides adequate protection, failing that one of the listed safeguards (a Board-announced standard contract, binding corporate rules and others), and failing both, a narrow set of exceptional cases. The text applies the same safeguards to onward transfers. Which tier a particular flow would fall under, and whether it is a transfer at all, is a legal assessment; what you can bring to it from the engineering side is an exact list of the flows.
Article 12, data security. The Authority’s own page on the provision summarises the controller’s duties as preventing unlawful processing of personal data, preventing unlawful access to it and ensuring it is kept safe, by taking the technical and administrative measures that give an appropriate level of security, and by carrying out or commissioning audits inside the organisation. Hosting the gateway yourself puts those measures in your hands, which is the point and also the obligation: there is no vendor whose security programme you inherit.
What stays at rest in your PostgreSQL
Ragmux keeps everything in one PostgreSQL database that you operate:
- Uploaded documents, in full, as
bytea, with their chunks and one embedding table per vector width. - Request logs, which hold usage and identifying columns: model names, token counts, error messages and the like. The backup documentation states they contain no prompts or completions. See the request log.
- The audit log: administrative actions with actor, target and IP address.
- Credentials: provider API keys are AES-256-GCM encrypted with
SECRET_KEY, and project keys are stored hashed.
Two retention settings exist: LOG_RETENTION_DAYS (default 90) and AUDIT_RETENTION_DAYS
(default 365), each with 0 meaning rows are kept forever. They cover request logs and
audit entries. Uploaded documents are not on that list, so how long a document stays in a
store is your own policy to enforce, by deleting it.
Because a dump contains every uploaded document, the backup documentation treats it “like
the database itself”: encrypt it, restrict the directory, and keep SECRET_KEY apart from
it. See Security notes.
What leaves the gateway, and for whom
This is the table to put in front of your review. Every row is a call to a destination that an admin configured or a client named; none of them is a call Ragmux makes on its own initiative.
| Step | Text that leaves | Goes to |
|---|---|---|
| Ingest a document | each chunk, prefixed with the file name and section when contextual_chunks is on |
the store’s embedding connection |
| Retrieve for a request | the last user message, or the condensed query | the store’s embedding connection |
Condense (query_strategy: condense) |
the last history_turns_for_query turns (each a user message and the assistant reply after it) and the last user message |
the connection named by query_model_connection_id, or the project’s chat connection (the first route target when it has routes) |
Rerank, llm backend, in a chat or /v1/retrieve request |
candidate passages, each cut to 800 characters | the project’s chat model |
Rerank, dashboard search test and /v1/rerank (any backend) |
candidate passages, or the documents a client sent | the store’s rerank_connection_id: a chat connection for llm, the vendor’s API for cohere or voyage. In the search test an editor or admin (for a key, the write scope) can name any other chat or rerank connection of the instance for that one search with the rerank_backend and rerank_connection_id overrides. For a viewer the override is ignored, with a Warning: 299 header and rerank_overrides_ignored in the response |
Rerank, cohere or voyage, in a chat or /v1/retrieve request |
candidate passages, each cut to 4000 characters | that vendor’s API, through the rerank_connection_id connection |
/v1/rerank |
the query and up to 1000 documents a client sent (a chat connection ranks at most 100) | a kind = rerank route target, else the store’s rerank_connection_id |
/v1/embeddings |
up to 2048 texts a client sent | a kind = embeddings route target, else the store’s embedding connection |
/v1/retrieve |
the query, and the passages if the store reranks with llm |
the store’s embedding connection, and the project’s chat connection for an llm rerank |
| Answer | the conversation, the project’s system prompt and the retrieved passages | the project’s chat connection |
Image parts (IMAGE_FETCH on) |
a request for each image URL a client sent | the host in that URL, for gemini and ollama connections |
Tracing (when an OTLP endpoint is set through OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT and TRACING_ENABLED is not false) |
trace data; what spans carry is outside this page | the OTLP collector you named |
A document’s text therefore reaches the embedding endpoint when it is ingested and, when a
question matches it, the chat endpoint and, if reranking is on, the reranker. The condense
model does not receive the retrieved passages, but it does receive the conversation,
including earlier assistant replies that may have quoted document content. If every one of
those is a
local ollama or custom_openai server, none of it crosses your network
boundary. If one is a hosted provider, that row is the flow to put the Article 9 question
to. See Reranking and Query strategy
for the exact behaviour of the two optional steps.
Keeping the list closed
A list is only useful if it cannot grow quietly. Three properties of the gateway keep it closed.
- A project reaches only the connections it names. Requests carry a project key, and
the destinations are the project’s model connection or route targets, plus its store’s
embedding and rerank connections and its query model. The
/v1/embeddingsand/v1/rerankendpoints are the same set, reached throughembeddingsandrerankroutes or the store’s implicit connections. One exception: in the dashboard search test, aneditororadmincan name any chat or rerank connection of the instance for a single search (see the table above), so for that path the instance’s whole connection list is in scope. Adding or changing a connection is an administrative action, which the audit log records. - The private-upstream guard refuses private addresses by default, so a local server
has to be allowed by hostname with
PRIVATE_UPSTREAM_ALLOWLISTbefore a connection to it works. LeaveALLOW_PRIVATE_UPSTREAMSoff and allow exactly the hosts you run. See Private upstreams. - The
ragmuxrequest object can only narrow. A client can skip retrieval or filter by metadata for its own request, but it cannot turn retrieval on or change a project setting.
A worked example: an HR assistant for a Turkish company
An HR team wants an assistant over employment contracts and the staff handbook. The contracts contain names, national ID numbers and salaries, so the team’s rule is that no document text goes to a third party.
The chat model and the embedding model both run on an internal ollama server, listed in
PRIVATE_UPSTREAM_ALLOWLIST by name. Reranking uses the llm backend, so the candidates
go to that same local chat model, and the store’s rerank_connection_id, which the dashboard search and /v1/rerank use, is set to a local chat connection too, and the project uses the default last_user query
strategy, so there is no fourth connection to account for. IMAGE_FETCH is off, because
nobody sends images. Request logs are kept 90 days, the audit log a year, and the nightly
dump is encrypted before it leaves the database host. Contracts that expire are deleted
from the store by the HR team, because retention settings do not do it for them.
Before go-live, the team reads the project’s connection list against the table above, and the result is a one-page data-flow description it can hand to the data controller. The page says nothing about whether that is enough under KVKK; that judgement stays where it was.
Where this doesn’t help
- A requirement for a certificate or attestation. Ragmux is AGPL-3.0-or-later software with no vendor behind it, and it carries none. Hosting it yourself gives you control of the flows, not a document that proves anything to an auditor.
- Hosted models as a deliberate choice. If a project is meant to use a hosted provider, the flow table still tells you what it will see, but containing it is not on offer; the decision moves to the contract and the transfer assessment with that provider.
- Documents with mixed access. A RAG store has no per-document access control, so personal data meant for a narrower audience belongs in its own store and project. See Private document Q&A.
- A fully isolated network. If the requirement is no outbound connection at all, the air-gapped deployment page covers what else changes.
Map and contain the data flows of a Ragmux deployment
List every model connection and the host behind its base_url
Open the dashboard's model connections, or call GET /admin/api/models, and write down each connection with its provider_type and base_url. Each one is a place where text can leave the gateway; whether that place is inside your boundary is decided by the host, not by Ragmux.
Decide which of chat, embedding, rerank and condense must be local
Chat and embedding connections are the two every RAG project has. A store with rerank on adds a third (a chat connection for the llm backend, which can be the project's own model and, for the dashboard search and /v1/rerank, the store's rerank_connection_id; or a Cohere or Voyage connection), and a project with query_strategy set to condense adds a fourth, named by query_model_connection_id. Point each at a local ollama or custom_openai server if the text it sees must not leave.
Choose the llm rerank backend, or none, when documents must stay inside
rerank_backend cohere and voyage send passages (each cut to 4000 characters) to those vendors' APIs. The llm backend sends them to a chat model instead: the project's own for a chat or /v1/retrieve request, and the store's rerank_connection_id for the dashboard search and /v1/rerank. Both have to be local chat connections for the backend to stay inside.
Turn IMAGE_FETCH off if the gateway must not fetch URLs a client names
While IMAGE_FETCH is true (the default), the gateway downloads the image_url parts of a request for gemini and ollama connections. Set it to false and such a request is refused with 400 instead.
Set retention to your own policy, and protect the backups
LOG_RETENTION_DAYS defaults to 90 and AUDIT_RETENTION_DAYS to 365; 0 keeps rows forever. Neither setting covers uploaded documents. A database dump contains every uploaded document, so encrypt it and restrict who can read it.
Frequently asked questions
- Does Ragmux store the prompts and answers of my users?
- Request logs hold model names, token counts and error messages, but not prompts or completions, according to the backup documentation. Uploaded documents are a different matter: they are stored in full, as bytea, in your PostgreSQL.
- Is a Ragmux deployment KVKK compliant?
- No software is compliant on its own; compliance is a property of how the data controller processes personal data. Ragmux carries no KVKK certification or attestation. It gives you a database you host, connections you point where you choose and an audit log, which are inputs to your own assessment.
- Does using a hosted model provider count as a transfer of personal data abroad?
- That depends on where the provider processes the data and on your role, and it is a question for your own legal counsel. What Ragmux can tell you is exactly which requests send text to which connection, so the question can be asked about concrete flows.
- How do I make sure nothing reaches a cloud provider?
- Point every connection a project can use, including the rerank and condense ones, at a local server, and leave the private-upstream guard on with only those hosts allowed. A project reaches only the connections it and its store name, so for client requests those lists, not the whole instance, are the destinations to review. The exception is the dashboard search test: an `editor` or `admin` can send the store's passages to any chat or rerank connection of the instance for a single search. Keep hosted connections out of an instance that holds personal data, or limit who holds those roles.
- What do the audit log and the request log record about documents?
- The request log records usage and identifying columns, not text. The audit log records administrative actions with actor, target and IP address; for a document's metadata it records the key names, not the values.
- Does Ragmux send telemetry to its maintainers?
- The configuration reference lists no telemetry, license-check or update-check variable, and the outbound calls the gateway makes go to the endpoints an admin configures. See the air-gapped deployment page for the full list of outbound calls.
Sources
- Resmî Gazete, 12 March 2024, No. 32487 — Law No. 7499, which replaces Article 9 (transfers abroad) of Law No. 6698
- KVKK Authority — Veri Güvenliğine İlişkin Yükümlülükler (Article 12 of Law No. 6698)
Product and provider names are trademarks of their respective owners.