Skip to main content

Networking & DNS

Quill DNS records​

The published hostnames​

During sign-up, you choose a Quill name and provide the IP address of the host that will run your Quill instance.
Quill assigns your instance a base domain in the following form:

<quill-name>.myquill.ai

For example, the Quill name acme produces the base domain acme.myquill.ai.
In this article, <domain> represents this complete base domain.

Quill provisions five DNS hostnames beneath the base domain.
By default, all five resolve to the IP address provided during sign-up:

HostnameUsed for
dashboard.<domain>The operator dashboard, dashboard API requests, and health checks.
api.<domain>Programmatic access to the Quill API and health checks, without the dashboard UI.
public.<domain>Embedded chat pages, widget assets, chat requests, and public channel webhooks.
db.<domain>Direct RavenDB access for applications authenticated with a client certificate.
a.<domain>RavenDB's advertised node URL, which RavenDB.Client may receive through topology discovery.

The first four hostnames expose Quill's customer-facing service surfaces.
a.<domain> identifies the RavenDB node rather than a separate Quill web surface.

Quill does not publish corresponding -tcp records.
Direct RavenDB access through db.<domain> or a topology-discovered a.<domain> address uses HTTPS on port 443;
the native RavenDB TCP listener is not exposed by default. Learn more in Direct database access.

For details about how connections to these hostnames are routed and protected, see The Quill hostnames.

The behavior of the RavenDB node hostname is described in The a hostname.

The `a` hostname​

a.<domain> is one of the five DNS hostnames provisioned for each Quill instance:

a.<domain>

This hostname identifies the RavenDB node.
RavenDB stores https://a.<domain> as its PublicServerUrl and advertises that address as its node URL.

In public DNS, a.<domain> resolves to the externally reachable address configured for the other DNS records.
This allows appropriately authenticated RavenDB clients to reach the advertised node URL.

Inside the Quill container, startup adds a.<domain> to /etc/hosts with the address 127.0.0.1.
Quill uses this hostname with RavenDB's internal HTTPS port and disables topology updates.
As a result, communication between Quill and RavenDB remains on loopback without changing the public DNS record.

a.<domain> differs from the other service hostnames:

  • It does not represent a separate dashboard, API, or chat surface.
  • Applications should use https://db.<domain> as their initial address for direct RavenDB access.
  • A RavenDB.Client that updates its topology may subsequently receive https://a.<domain> as the RavenDB node address.
  • DNS updates include a.<domain> together with the other four records.

For more information about direct RavenDB connections and your Quill's network limitations,
see Direct database access.

Who manages the records​

RavenDB operates the myquill.ai domain and manages its DNS records. During sign-up, Quill assigns your instance its <quill-name>.myquill.ai base domain and provisions the required records on your behalf.

Because the records belong to a RavenDB-managed DNS zone:

  • You do not need to register a domain or configure a DNS provider.
  • You do not receive DNS-provider credentials or a DNS console for the instance.
  • Moving or restarting your Quill does not update the records automatically.

When a record must change, run the supported update-dns command from the Docker host. The command reads the licensed domain from the activated server certificate and uses the setup package's license.json file to authorize the request to the RavenDB DNS service at api.ravendb.net.

The exact command and the records it updates are described in Update the records.

DNS and Quill routing​

DNS resolution determines which IP address receives a connection. It does not determine which Quill component handles the connection, which routes are available, or whether the caller is authorized.

The five DNS hostnames normally resolve to the same host address.
Clients then connect to that host over HTTPS on port 443.
After the connection reaches your Quill, nginx uses the requested hostname to route it:

  • Connections to dashboard.<domain>, api.<domain>, and public.<domain> terminate TLS at nginx.
    nginx forwards only the routes allowed for that hostname to the Quill web application.
  • Connections to db.<domain> and a.<domain> are passed to RavenDB without terminating TLS at nginx.
    RavenDB terminates TLS and validates the caller's client certificate.

DNS also does not make the host reachable. The host's firewall, cloud security rules, and any intervening NAT configuration must allow inbound TCP traffic on port 443.

DNS and TLS are separate as well. DNS points a hostname to an address, while the wildcard certificate for your Quill proves the identity of that hostname. Changing the address behind a hostname does not change the hostname itself.

For the complete routing and TLS model, see How a connection is routed and The TLS front and the wildcard certificate.
For dashboard and API authentication, see Operator Authentication.

Moving your Quill to a new IP​

When the records must be updated​

The five DNS records continue to return the address configured during sign-up until you explicitly update them.

Update the records whenever the IP address through which callers reach your Quill changes.
This can happen when:

  • you move your Quill to another host;
  • you rebuild or restore the host and it receives a different address;
  • a cloud provider or internet service provider reassigns the host's address;
  • you move your Quill between environments, such as from a local machine to a cloud virtual machine;
  • you change the network or NAT configuration so that a different address receives inbound traffic for your Quill.

You do not need to update the records when:

  • the container restarts or is recreated on the same host;
  • Docker assigns the container a different internal address;
  • an internal network address changes but callers still reach your Quill through the same host address.

Use the address through which operators, chat users, and applications can reach the host on port 443.
Do not use the container's internal Docker address or a loopback address.

Until the records are updated, DNS continues to direct callers to the old address.
If the old host remains available, traffic continues reaching it.
If it is no longer available, the dashboard, embedded chats, API calls, and direct RavenDB connections fail to reach your Quill.

Updating DNS does not move the container or its persisted data.
Complete the host migration separately, and then update the records as described in Update the records.

What remains unchanged​

Changing the host's IP address changes only the address stored in the published DNS records.
The Quill domain and the URLs used by operators, chat users, and applications remain the same.

ItemWhat remains unchanged
Base domain and hostnames<domain> and the dashboard, api, public, db, and a hostnames keep the same names.
Wildcard server certificateThe certificate is issued for *.<domain>, not for a particular IP address.
Activated setup package and licenseYour Quill continues using the existing activated setup package and its license file.
Dashboard API keyThe key is independent of the host's IP address; supply the same QUILL_API_KEY value to a replacement container.
Quill configuration and dataApps, agents, channels, conversations, RavenDB databases, and certificate registrations remain in the persistent Docker volume mounted at /var/lib/quill.

Repointing the DNS records therefore does not require a new domain, new URLs, a new wildcard certificate,
or a different Dashboard API key.

For details about the wildcard certificate, see The TLS front and the wildcard certificate.
For information about preserving or replacing the Dashboard API key, see Operator Authentication.

Moving to another host​

  • A DNS update does not copy your Quill's data or container configuration.

  • When moving your Quill to another host, transfer the persistent Docker volume mounted at /var/lib/quill and preserve the required deployment environment values, including QUILL_API_KEY and QUILL_LICENSE_KEY, before directing traffic to the new host.

  • If only the existing host's externally reachable IP address changes, no data-volume migration is required.

Update the records​

Run the DNS update from the Docker host after the Quill container is running on the host with its new externally reachable address.

The container must:

  • be running and activated;
  • contain the activated setup package, including its server certificate and license.json file;
  • have outbound HTTPS access to api.ravendb.net.

The command derives the base domain from the server certificate and uses the license file for authorization. You do not need to supply the domain, the Dashboard API key, or an authenticated browser session.

Update the five DNS records​

In the commands below, <container-name> is the name specified by docker run --name.
By default, it matches your Quill name.

Run the following command, replacing <new-ip> with the host's new address:

docker exec <container-name> update-dns --ip <new-ip>

If the container uses the default name, the dashboard's Settings > IP configuration page generates this command with the container name filled in after you enter a new IPv4 address.

The command updates all five DNS records in one request:

  • dashboard.<domain>
  • api.<domain>
  • public.<domain>
  • db.<domain>
  • a.<domain>

The command reports its progress while api.ravendb.net processes the request and prints a confirmation when the records have been registered.

Completing the command confirms that the DNS service accepted and processed the update.
Callers may still receive the previous address from DNS caches, as explained in DNS propagation and TTL.

Assigning more than one address​

  • To assign several addresses to each of the five DNS hostnames, separate them with commas in the value passed to --ip:

    docker exec <container-name> update-dns --ip <ip-1>,<ip-2>

  • The command accepts both IPv4 and IPv6 addresses.

If the command times out​

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

  • A timeout means that the command stopped waiting.
    It does not necessarily mean that the DNS update was rejected or rolled back.
    Verify the published records before running the command again.

DNS propagation and TTL​

The Quill DNS records are published with a time to live (TTL) of 1800 seconds, or 30 minutes.

The TTL controls how long a DNS resolver may reuse a cached answer.
It is separate from the time the update command spends submitting and processing the change.

After the authoritative records are updated:

  • callers without a cached answer receive the new address;
  • callers whose cached answer has expired receive the new address;
  • callers that still hold the previous answer continue using the old address until that cached answer expires.

The remaining cache time depends on when each resolver last looked up the hostname.
A resolver that cached the old answer immediately before the update may continue returning it for approximately 30 minutes.

Plan for callers using both addresses​

  • Prepare your Quill on the new host before updating the records.

  • During the propagation window, some callers may reach the new address while others continue using the old one. If the old host is stopped immediately, callers with a cached answer can fail until their cache expires.

  • The DNS change does not alter existing embed URLs or their tokens.
    During propagation, new embed-page loads and chat requests may reach either address.

  • An in-flight chat remains on its existing connection. If the old host is stopped before the chat finishes, the connection can be interrupted and the user may need to retry after their DNS cache refreshes.

  • Do not run two independent copies of your Quill with separately changing data merely to cover the DNS transition.
    If both old and new hosts remain reachable, make sure your migration plan prevents their persisted data from diverging.

Operating systems, browsers, DNS resolvers, and application runtimes may add their own caching behavior.
Some callers can therefore retain an address longer than the DNS TTL.

Restarting an affected browser or application may clear its local cache, but it does not clear an answer cached by an intermediate DNS resolver.

After allowing for propagation, confirm the current answers as described in Verify the change.

Verify the change​

Verify the change in two stages:

  1. Confirm that all five DNS hostnames resolve to the intended address.
  2. Confirm that HTTPS reaches your Quill through its normal hostname.

Check the DNS records​

Resolve each of the five DNS hostnames from the Docker host or another machine outside the container:

nslookup dashboard.<domain>
nslookup api.<domain>
nslookup public.<domain>
nslookup db.<domain>
nslookup a.<domain>

Each hostname should return the new address.
If you intentionally assigned several addresses, the results should contain every address you configured.

Inside the Quill container, a.<domain> intentionally resolves to 127.0.0.1.
This internal override does not change its public DNS record.

If a resolver still returns the old address, allow for the caching period described in DNS propagation and TTL,
and then query it again.

Check HTTPS and certificate validation​

Confirm that the dashboard hostname reaches your Quill and that its TLS certificate is accepted:

curl --fail --silent --show-error \
  https://dashboard.<domain>/healthz

Do not add curl's -k or --insecure option.
Skipping certificate validation could hide a certificate or hostname problem introduced during the move.

You can also verify the API hostname independently:

curl --fail --silent --show-error \
  https://api.<domain>/healthz

A successful response confirms that:

  • DNS resolves the hostname to a reachable address;
  • inbound traffic reaches the host on port 443;
  • nginx recognizes the hostname and routes the request;
  • the wildcard server certificate is valid for the hostname;
  • the Quill web application is responding.

If your deployment uses the other surfaces, verify them through their normal access paths as well:

  • open an existing embed link through public.<domain>;
  • connect to db.<domain> with a recognized client certificate.

For the requirements of a direct RavenDB connection, see Direct database access.
If any verification step fails, continue with Diagnose failures.

Diagnose failures​

Use the point at which verification fails to identify the affected layer:

SymptomLikely causeNext check
The DNS update command exits with an errorThe new IP address is invalid, the activated server certificate or license file is unavailable, outbound HTTPS failed, or the DNS service rejected the requestRead the returned error, verify the new IP address and the activated setup package, confirm outbound access to api.ravendb.net, and verify all five DNS records before retrying
A hostname does not resolveThe hostname or base domain is incorrect, the record was not provisioned, or a resolver cached an earlier "not found" responseCompare the hostname with the PublicServerUrl in the activated setup package. If the hostname was recently provisioned, wait up to 15 minutes for the cached response to expire, then resolve it again
A hostname still resolves to the old addressThe answer is cached or the update has not completedAllow for the TTL, then resolve all five hostnames again
The hostname resolves correctly, but the connection times outExternal TCP port 443 is blocked or does not reach container port 443Check the firewall, cloud security rules, NAT or load-balancer forwarding, and Docker port mapping
The hostname resolves correctly, but the connection is refusedThe container is stopped or nothing is accepting the forwarded connectionCheck the container state and Docker port mapping
HTTPS reports a certificate errorThe certificate is expired, invalid, or does not cover the requested hostnameInspect the certificate and certificate-renewal logs
/healthz returns an unsuccessful responseThe Quill web application or RavenDB is not readyCheck bootstrap status and the Quill logs
/healthz succeeds, but the dashboard or API returns 401The DNS change succeeded, but the expected Dashboard API key was not preservedCheck QUILL_API_KEY and see Operator Authentication
Dashboard health succeeds, but db.<domain> connections failDNS and the web surface are working; investigate the client certificate and RavenDB connection separatelySee Direct database access

Check the container and published port​

In the commands below, <container-name> is the name specified by docker run --name. By default, it matches your Quill name.

Confirm that the container is running:

docker inspect <container-name> --format "Status={{.State.Status}}"

Confirm that the container's HTTPS port is published:

docker port <container-name> 443/tcp

If the container is stopped, start it before continuing.
If port 443 is not published, review how the container was started and confirm that container port 443 is published to the host.

Check Quill from inside the container​

Bypass external DNS, the host firewall, and nginx by calling the Quill web application directly:

docker exec <container-name> curl --fail --silent --show-error \
  http://127.0.0.1:5000/healthz

Then inspect the activation state:

docker exec <container-name> curl --silent --show-error \
  http://127.0.0.1:5000/api/bootstrap/status

If the internal health check succeeds but the external health check fails, investigate DNS, port 443, nginx, the host firewall, or NAT.

If the internal health check also fails, investigate the Quill web application and RavenDB startup state.

Read the Quill logs​

Read the most recent Quill web application messages:

docker exec <container-name> tail -n 100 \
  /var/lib/quill/logs/web.log

For nginx request-routing and response-status details, read the access log:

docker exec <container-name> tail -n 100 \
  /var/lib/quill/proxy/access.log

The access log currently has no timestamps or built-in rotation and can continue growing in the persistent data volume. Monitor its size.

The access log covers HTTP requests to dashboard.<domain>, api.<domain>, and public.<domain>;
connections passed through to RavenDB for db.<domain> and a.<domain> do not appear there.

Quill does not record /healthz requests routed to the dashboard or API listeners in the access log.
On public.<domain>, /healthz is not an allowed endpoint; the resulting 404 request is logged.

For nginx startup, configuration, certificate-loading, or upstream connection failures, read the error log:

docker exec <container-name> tail -n 100 \
  /var/lib/quill/logs/proxy.log

The current warn log level does not record common client-side TLS handshake failures or SNI-preread diagnostics that nginx emits below warn.

Quill masks embed-link and Slack webhook tokens in both proxy logs, retaining only the first six characters for correlation.

For RavenDB startup or direct database failures, read:

docker exec <container-name> tail -n 100 \
  /var/lib/quill/logs/ravendb.log

For wildcard-certificate renewal failures, read:

docker exec <container-name> tail -n 100 \
  /var/lib/quill/logs/certwatch.log

For certificate behavior and renewal, see The TLS front and the wildcard certificate.
For dashboard and API authorization failures, see Operator Authentication.
For client-certificate requirements, see Direct database access.

Summary​

  • During sign-up, Quill provisions five DNS records under <quill-name>.myquill.ai:
    dashboard, api, public, db, and a. RavenDB manages these records.

  • a.<domain> is RavenDB's advertised node URL.
    Inside the container, it resolves to 127.0.0.1 so Quill's communication with RavenDB remains internal.

  • DNS maps each hostname to an address.
    Routing, TLS termination, and authorization are handled by your Quill after the connection reaches the host
    on port 443.

  • If the host's externally reachable IP address changes, run docker exec <container-name> update-dns --ip <new-ip>. The command derives the domain from the activated server certificate and uses the activated license to authorize the update of all five DNS records.

  • Updating DNS does not move your Quill to another host.
    Preserve the persistent Docker volume mounted at /var/lib/quill and the required deployment environment values when moving it.

  • The records have a TTL of 30 minutes.
    After an update, verify both DNS resolution and HTTPS connectivity.

In this article