RDoc-4061 + RDoc-4062 + RDoc-4063 Security & Architecture: The appliance surfaces + Operator authentication + Networking & DNS by Danielle9897 · Pull Request #2599 · ravendb/docs

Danielle9897 · 2026-08-13T15:05:51Z

Issue link

https://issues.hibernatingrhinos.com/issue/RDoc-4061/Quill-documentation-Security-Architecture-The-appliance-surfaces
https://issues.hibernatingrhinos.com/issue/RDoc-4062/Quill-documentation-Security-Architecture-operator-authentication
https://issues.hibernatingrhinos.com/issue/RDoc-4063/Quill-documentation-Networking-DNS

Additional description

The "Appliance surfaces" article covers:

how nginx routes connections through the appliance's single external TLS entry point
the four customer-facing hostnames (dashboard.*, api.*, public.*, and db.*), what each serves, and RavenDB's additional a.* routing alias
the public embed-link routes and their token-based access, the support endpoints available before authentication, and the operational endpoints protected by the Dashboard API key or a browser session
TLS termination for Quill web traffic, TLS passthrough for RavenDB traffic, and the wildcard server certificate
direct RavenDB access over HTTPS and mutual TLS, including the client-certificate requirements and the fact that native TCP is not exposed
the appliance's internal admin client certificate, which is not exposed to browsers, chat widgets, or API callers
relevant network limitations, including unpublished internal ports and the loss of the original caller IP address

The "Operator authentication" article covers:

Dashboard access using the required API key, browser sessions, or request headers
key scope, storage, recovery, and replacement
surfaces that use other access controls, including embed links and direct RavenDB connections

The "Networking & DNS" article covers:

The DNS hostnames provisioned for a Quill instance and what each one serves.
Updating the published records when the host IP changes.
DNS propagation, verification, and troubleshooting.

===========================

Type of change

Changes in docs URLs

No changes in docs URLs
Articles are restructured, URLs will change, mapping is required (update /scripts/redirects.json file, set Documents Moved PR label)

Changes in UX/UI

No changes in UX/UI
Changes in UX/UI (include screenshots and description)

…hentication

Danielle9897 · 2026-08-17T10:27:31Z

+   is present and functional in the default release image and the source-built image.
+The current dashboard displays the wrapper command, but the Dockerfiles do not package a consistently
+working wrapper/rvn combination.
+*/}


@karmeli87 @TheGoldenPlatypus

What is the intended DNS contract for a.<domain> ?

RavenDB advertises it as its PublicServerUrl, so external topology-aware clients can receive it after initially connecting to db.<domain>.

However, Quill currently relies on a.<domain> resolving to loopback, and the DNS update script excludes it.

Should a.<domain> remain loopback-only?
If so, how should external clients connect after receiving it through topology discovery?
Or should it resolve to the instance’s public IP, with Quill’s internal connection adjusted accordingly?

@Danielle9897 this is tracked, and the contract isn't settled yet, so please don't document either behavior.

current state: the wizard registers all five subdomains at the customer's IP, and update-dns.sh then excludes a. from subsequent updates. that inconsistency is the bug, and the effect is on internal traffic - Quill's calls to ravendb should be loopback and aren't guaranteed to be.

I proposed pinning a. to 127.0.0.1 in dns but @ayende rejected that, because in a clustered setup every node would resolve its peers to itself. he wants us tp override the hostname in the container's /etc/hosts instead, keeping public dns pointing at real IPs.

Under that model, to answer your question directly: a.<domain> is not loopback-only in DNS. It resolves publicly like the others, and external topology-aware clients can use it.
only the container itself short-circuits it to loopback. BUT that's the intended contract, not the implemented one.
db.<domain> remains the documented external entry point either way, so docs can safely say that much.

@karmeli87 can I get this on my board? https://issues.hibernatingrhinos.com/issue/RavenDB-27224/Quill-Wizard-should-always-set-a.domain-DNS-record-to-fixed-127.0.0.1

Danielle9897 · 2026-08-17T10:32:13Z

+The container currently expects it to resolve to loopback, and update-dns.sh excludes it from IP updates.
+However, external RavenDB.Client instances can receive a.<domain> through topology discovery.
+Do not state that operators must or must not repoint this hostname until that contract is settled and tested.
+*/}


@karmel @TheGoldenPlatypus

What is the intended supported DNS-update command for users?

The dashboard currently shows:
docker exec quill update-dns --ip <new-ip>

However, the default Dockerfile does not include the update-dns wrapper.
Dockerfile.source includes the wrapper, but it calls /app/ravendb/rvn;
is that executable guaranteed to be present in the source-built image?

Should both image variants be updated and tested to support the wrapper command,
or should the dashboard and documentation show the direct rvn dns update ... command instead?

that's true. the two dockerfiles acting as different sources of truth, and sure enough they drifted (we had a decision to build it from source and then we told otherwise as we progress ). we need to align Dockerfile with the missing parts that are present on the .source file and drop Dockerfile.source.
can you hold it till then?
ticket:
RavenDB-27372 Quill: align both dockerfiles and eventually drop Dockerfile.source
@karmeli87 can I get it on my board?

Danielle9897 · 2026-08-18T11:34:22Z

@TheGoldenPlatypus

I updated the TODOs in quill/networking-and-dns.mdx to track RavenDB-27224 and RavenDB-27372.
I added a table to RDoc-4063 listing the passages to revisit after those issues are resolved:
https://issues.hibernatingrhinos.com/issue/RDoc-4063/Quill-documentation-Networking-DNS#focus=Comments-67-1097904.0-0

Could you please review the remaining parts of this article and the other two articles in the PR?

TheGoldenPlatypus

@Danielle9897 I think this PR is not synced with the current work we do.
that's natural, since we still rework things especially around networking. best will be to park this whole PR for a while , until things get settled and then come back to it to update it

TheGoldenPlatypus · 2026-08-18T13:22:17Z

+It does not use the Dashboard API key, a browser session, or a client certificate.  
+Instead, access is granted by the embed-link token included in the URL.  
+
+nginx forwards only these two routes on `public.<domain>`:


ravendb/ravendb#23390 added a third route to this server block. so it's not entirely accurate.
the embed page also loads its widget bundle from /widget/assets/* on the same origin.
might not be so interesting from the user perspective until he decides to put a WAF or something infront the whole thing and the widget stops loading.
@kalczur should we add the assets ep here?

TheGoldenPlatypus · 2026-08-18T13:24:15Z

+```
+<br/>
+
+The current nginx front does not preserve the caller's IP address.  


accurate for the current release, but RavenDB-27364 changes it:
the SNI front now sends the PROXY protocol and the terminators recover the real client address

TheGoldenPlatypus · 2026-08-18T13:25:13Z

+
+The current nginx front does not preserve the caller's IP address.  
+The Quill web application and RavenDB see nginx's loopback address instead,  
+so downstream logs cannot identify individual callers by source IP.


first we don't have access.log enabled - and we should enabled it. second ravendb/ravendb#23400 addresses this by the proxy protocol trick

TheGoldenPlatypus · 2026-08-18T13:25:38Z

+so downstream logs cannot identify individual callers by source IP.
+
+The login endpoint and public chat endpoint both apply IP-based rate limits.  
+Because the original caller IP is not preserved, each limit uses one shared appliance-wide bucket instead of separate buckets for individual clients.


not true anymore once we merge ravendb/ravendb#23400

TheGoldenPlatypus · 2026-08-18T13:29:04Z

+For example, the Quill name `acme` produces the base domain `acme.myquill.ai`.  
+In this article, `<domain>` represents this complete base domain.
+
+Quill provisions four published hostnames beneath the base domain.  


five records are provisioned. including a.* once this ravendb/ravendb#23416 will be merged. it should be also in the table below. which means a. still accessible from outside - but the comm between ravendb and quill is via lo by overriding /etc/hosts

TheGoldenPlatypus · 2026-08-18T13:36:53Z

+  -l /var/lib/quill/setup/license.json \
+  -d <domain> \
+  -n <ip-1>,<ip-2>=dashboard,db,public,api
+```


outdated, see comment above

well it's true, but we have more UXish nicer way for the users

TheGoldenPlatypus · 2026-08-18T13:37:51Z

+
+#### If the command times out
+
+The command waits up to 15 minutes for the DNS service to complete the request.


where is this info from? it's not related to my work I know , but I was under the impression that the timeout is 30m. but I probably wrong. worth rechecking

TheGoldenPlatypus · 2026-08-18T13:38:13Z

+nslookup api.<domain>
+nslookup public.<domain>
+nslookup db.<domain>
+```


a. should be also here after ravendb/ravendb#23416 lands

TheGoldenPlatypus · 2026-08-18T13:39:12Z

+| Base domain and hostnames | `<domain>` and the `dashboard`, `api`, `public`, and `db` hostnames keep the same names. |
+| Wildcard server certificate | The certificate is issued for `*.<domain>`, not for a particular IP address. |
+| Activated setup package and license | Your Quill continues using the existing activated setup package and its license file. |
+| Dashboard API key | The key is independent of the host's IP address; supply the same `QUILL_API_KEY` value to a replacement container/ |


sorry for pointing out, but spotted it :) there is a stray '/' at the end

TheGoldenPlatypus · 2026-08-18T13:39:55Z

+
+<Admonition type="info" title="">
+
+#### The sign-in rate limit is instance-wide


whole block will not be true once ravendb/ravendb#23400 will land

RDoc-4061 Security & Architecture: The appliance surfaces

fca6a82

Danielle9897 requested a review from karmeli87 August 13, 2026 15:13

RDoc-4062 [Quill documentation] Security & Architecture: operator aut…

8cd8470

…hentication

Danielle9897 changed the title ~~RDoc-4061 Security & Architecture: The appliance surfaces~~ RDoc-4061 + RDoc-4062 Security & Architecture: The appliance surfaces + Operator authentication Aug 16, 2026

RDoc-4063 [Quill documentation] Networking & DNS

00c2594

Danielle9897 changed the title ~~RDoc-4061 + RDoc-4062 Security & Architecture: The appliance surfaces + Operator authentication~~ RDoc-4061 + RDoc-4062 + RDpc=4063 Security & Architecture: The appliance surfaces + Operator authentication + Networking & DNS Aug 17, 2026

Danielle9897 commented Aug 17, 2026

View reviewed changes

Danielle9897 requested a review from TheGoldenPlatypus August 18, 2026 11:23

RDoc-4063 Update the TODO text

f1b09c6

TheGoldenPlatypus reviewed Aug 18, 2026

View reviewed changes

Danielle9897 marked this pull request as draft August 18, 2026 14:07


		#### If the command times out

		The command waits up to 15 minutes for the DNS service to complete the request.


		<Admonition type="info" title="">

		#### The sign-in rate limit is instance-wide

Uh oh!

Conversation

Danielle9897 commented Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issue link

Additional description

Type of change

Changes in docs URLs

Changes in UX/UI

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TheGoldenPlatypus Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Danielle9897 commented Aug 18, 2026

Uh oh!

TheGoldenPlatypus left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TheGoldenPlatypus Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TheGoldenPlatypus Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Danielle9897 commented Aug 13, 2026 •

edited

Loading

TheGoldenPlatypus Aug 17, 2026 •

edited

Loading

TheGoldenPlatypus left a comment •

edited

Loading

TheGoldenPlatypus Aug 18, 2026 •

edited

Loading

TheGoldenPlatypus Aug 18, 2026 •

edited

Loading