From a61597b2783e9491e5329b22a7c27dd2318d2e26 Mon Sep 17 00:00:00 2001 From: Danielle9897 Date: Thu, 22 Oct 2026 21:23:11 +0300 Subject: [PATCH 1/2] RDoc-4123 Document Windows/WSL LAN access --- quill/dashboard/ip-configuration.mdx | 10 +- .../content/_ravendb-client-access-csharp.mdx | 4 +- .../content/_ravendb-client-access-java.mdx | 4 +- .../content/_ravendb-client-access-nodejs.mdx | 4 +- .../content/_ravendb-client-access-php.mdx | 4 +- .../content/_ravendb-client-access-python.mdx | 4 +- quill/getting-started/signing-up.mdx | 4 +- quill/getting-started/starting-quill.mdx | 7 + quill/home.mdx | 4 +- quill/networking/_category_.json | 4 + .../dns-and-ip-configuration.mdx} | 41 ++-- quill/networking/lan-access-on-windows.mdx | 229 ++++++++++++++++++ quill/updating-quill.mdx | 4 +- scripts/redirects.json | 6 + 14 files changed, 289 insertions(+), 40 deletions(-) create mode 100644 quill/networking/_category_.json rename quill/{networking-and-dns.mdx => networking/dns-and-ip-configuration.mdx} (92%) create mode 100644 quill/networking/lan-access-on-windows.mdx diff --git a/quill/dashboard/ip-configuration.mdx b/quill/dashboard/ip-configuration.mdx index 8ddae0d3ea..2c635042ed 100644 --- a/quill/dashboard/ip-configuration.mdx +++ b/quill/dashboard/ip-configuration.mdx @@ -22,7 +22,7 @@ import ContentFrame from '@site/src/components/ContentFrame'; Follow the steps in [Change the IP](#change-the-ip) to generate and run the command on the Docker host. * For details about Quill's DNS records, DNS propagation, and moving to another host, - see [Networking & DNS](../networking-and-dns.mdx). + see [DNS & IP Configuration](../networking/dns-and-ip-configuration.mdx). --- @@ -169,12 +169,12 @@ the generated command also updates `a.`. It updates these five DNS recor When the update succeeds, the command prints a confirmation that the records were registered. For details about these hostnames, DNS propagation, assigning IPv6 or multiple addresses, -and handling a timeout, see [Networking & DNS](../networking-and-dns.mdx). +and handling a timeout, see [DNS & IP Configuration](../networking/dns-and-ip-configuration.mdx). * Repointing the DNS records does not move your Quill's data. -* If you are moving your Quill instance to another host, see [Moving to another host](../networking-and-dns.mdx#moving-to-another-host). +* If you are moving your Quill instance to another host, see [Moving to another host](../networking/dns-and-ip-configuration.mdx#moving-to-another-host). @@ -199,7 +199,7 @@ Seeing the new address confirms that it has reached the DNS resolver used by the Other callers may continue receiving the previous address until their cached DNS records expire. For details about DNS propagation and how to verify the update from outside the Quill container, -see [DNS propagation and TTL](../networking-and-dns.mdx#dns-propagation-and-ttl) -and [Verify the change](../networking-and-dns.mdx#verify-the-change). +see [DNS propagation and TTL](../networking/dns-and-ip-configuration.mdx#dns-propagation-and-ttl) +and [Verify the change](../networking/dns-and-ip-configuration.mdx#verify-the-change). diff --git a/quill/developer-access/content/_ravendb-client-access-csharp.mdx b/quill/developer-access/content/_ravendb-client-access-csharp.mdx index d53eeb1eef..20f0bde189 100644 --- a/quill/developer-access/content/_ravendb-client-access-csharp.mdx +++ b/quill/developer-access/content/_ravendb-client-access-csharp.mdx @@ -398,7 +398,7 @@ store.Conventions.DisableTopologyUpdates = true; ```
-For more information, see [The `a` hostname](../../networking-and-dns.mdx#the-a-hostname). +For more information, see [The `a` hostname](../../networking/dns-and-ip-configuration.mdx#the-a-hostname). @@ -423,7 +423,7 @@ If the Quill deployment is unavailable, the RavenDB Client API cannot switch to If the Quill host moves to another IP address, update all Quill DNS records so that `db.`, `a.`, and the other Quill hostnames resolve to the new address. -See [Moving your Quill to a new IP](../../networking-and-dns.mdx#moving-your-quill-to-a-new-ip). +See [Moving your Quill to a new IP](../../networking/dns-and-ip-configuration.mdx#moving-your-quill-to-a-new-ip). diff --git a/quill/developer-access/content/_ravendb-client-access-java.mdx b/quill/developer-access/content/_ravendb-client-access-java.mdx index a7346fc071..d65600baa9 100644 --- a/quill/developer-access/content/_ravendb-client-access-java.mdx +++ b/quill/developer-access/content/_ravendb-client-access-java.mdx @@ -429,7 +429,7 @@ store.getConventions().setDisableTopologyUpdates(true); ```
-For more information, see [The `a` hostname](../../networking-and-dns.mdx#the-a-hostname). +For more information, see [The `a` hostname](../../networking/dns-and-ip-configuration.mdx#the-a-hostname). @@ -454,7 +454,7 @@ If the Quill deployment is unavailable, the RavenDB Client API cannot switch to If the Quill host moves to another IP address, update all Quill DNS records so that `db.`, `a.`, and the other Quill hostnames resolve to the new address. -See [Moving your Quill to a new IP](../../networking-and-dns.mdx#moving-your-quill-to-a-new-ip). +See [Moving your Quill to a new IP](../../networking/dns-and-ip-configuration.mdx#moving-your-quill-to-a-new-ip). diff --git a/quill/developer-access/content/_ravendb-client-access-nodejs.mdx b/quill/developer-access/content/_ravendb-client-access-nodejs.mdx index 7607840db2..debc7e1e81 100644 --- a/quill/developer-access/content/_ravendb-client-access-nodejs.mdx +++ b/quill/developer-access/content/_ravendb-client-access-nodejs.mdx @@ -403,7 +403,7 @@ store.conventions.disableTopologyUpdates = true; ```
-For more information, see [The `a` hostname](../../networking-and-dns.mdx#the-a-hostname). +For more information, see [The `a` hostname](../../networking/dns-and-ip-configuration.mdx#the-a-hostname). @@ -428,7 +428,7 @@ If the Quill deployment is unavailable, the RavenDB Client API cannot switch to If the Quill host moves to another IP address, update all Quill DNS records so that `db.`, `a.`, and the other Quill hostnames resolve to the new address. -See [Moving your Quill to a new IP](../../networking-and-dns.mdx#moving-your-quill-to-a-new-ip). +See [Moving your Quill to a new IP](../../networking/dns-and-ip-configuration.mdx#moving-your-quill-to-a-new-ip). diff --git a/quill/developer-access/content/_ravendb-client-access-php.mdx b/quill/developer-access/content/_ravendb-client-access-php.mdx index 6760a4f163..96fbbd15de 100644 --- a/quill/developer-access/content/_ravendb-client-access-php.mdx +++ b/quill/developer-access/content/_ravendb-client-access-php.mdx @@ -417,7 +417,7 @@ $store->getConventions()->setDisableTopologyUpdates(true); ```
-For more information, see [The `a` hostname](../../networking-and-dns.mdx#the-a-hostname). +For more information, see [The `a` hostname](../../networking/dns-and-ip-configuration.mdx#the-a-hostname). @@ -442,7 +442,7 @@ If the Quill deployment is unavailable, the RavenDB Client API cannot switch to If the Quill host moves to another IP address, update all Quill DNS records so that `db.`, `a.`, and the other Quill hostnames resolve to the new address. -See [Moving your Quill to a new IP](../../networking-and-dns.mdx#moving-your-quill-to-a-new-ip). +See [Moving your Quill to a new IP](../../networking/dns-and-ip-configuration.mdx#moving-your-quill-to-a-new-ip). diff --git a/quill/developer-access/content/_ravendb-client-access-python.mdx b/quill/developer-access/content/_ravendb-client-access-python.mdx index 140c046ff7..c90575708b 100644 --- a/quill/developer-access/content/_ravendb-client-access-python.mdx +++ b/quill/developer-access/content/_ravendb-client-access-python.mdx @@ -387,7 +387,7 @@ store.conventions.disable_topology_updates = True ```
-For more information, see [The `a` hostname](../../networking-and-dns.mdx#the-a-hostname). +For more information, see [The `a` hostname](../../networking/dns-and-ip-configuration.mdx#the-a-hostname). @@ -412,7 +412,7 @@ If the Quill deployment is unavailable, the RavenDB Client API cannot switch to If the Quill host moves to another IP address, update all Quill DNS records so that `db.`, `a.`, and the other Quill hostnames resolve to the new address. -See [Moving your Quill to a new IP](../../networking-and-dns.mdx#moving-your-quill-to-a-new-ip). +See [Moving your Quill to a new IP](../../networking/dns-and-ip-configuration.mdx#moving-your-quill-to-a-new-ip). diff --git a/quill/getting-started/signing-up.mdx b/quill/getting-started/signing-up.mdx index d7d2de2cb5..eaea919b5f 100644 --- a/quill/getting-started/signing-up.mdx +++ b/quill/getting-started/signing-up.mdx @@ -24,7 +24,7 @@ for Quill to an AI agent answering your users through your first channel: a web - * A [Quill domain](../networking-and-dns.mdx#quill-dns-records) is a web address that your Quill deployment can be reached at. + * A [Quill domain](../networking/dns-and-ip-configuration.mdx#quill-dns-records) is a web address that your Quill deployment can be reached at. * A [license key](#saving-your-setup-details) activates Quill. * An [API key](../security-and-architecture/operator-authentication.mdx#the-dashboard-api-key) signs you into the deployment's management dashboard. @@ -199,7 +199,7 @@ All the details that are displayed here are also sent to the email address you p adding an agent. 5. **If your server IP changes** - The command that [re-registers the domain](../networking-and-dns.mdx#moving-your-quill-to-a-new-ip) with a new address. + The command that [re-registers the domain](../networking/dns-and-ip-configuration.mdx#moving-your-quill-to-a-new-ip) with a new address. Run it on the machine that hosts Quill. 6. **Done** diff --git a/quill/getting-started/starting-quill.mdx b/quill/getting-started/starting-quill.mdx index 48fa19199f..506077f073 100644 --- a/quill/getting-started/starting-quill.mdx +++ b/quill/getting-started/starting-quill.mdx @@ -46,6 +46,8 @@ Before starting Quill, make sure you have: * **Docker**, on the machine that will run Quill, at the public IP address you gave at sign-up. * Docker Desktop on Windows and macOS, or Docker Engine on Linux. + * On Windows, Docker Desktop runs Quill in WSL 2 by default, where other devices on your network may be unable to reach Quill. + Learn more in [LAN Access on Windows](../networking/lan-access-on-windows.mdx). * **Port 443 available** on Quill's machine. * The dashboard, the API, and the chat channels of your deployment are all [served on this one port](../security-and-architecture/network-architecture.mdx#how-a-connection-is-routed). @@ -128,6 +130,8 @@ Quill reports its progress in the terminal you ran the Docker command in, one li elapsed since the container started. The first run is longer, since Quill also fetches the certificate and configuration for your domain. +For example, on a Linux host running Docker Engine directly: + ``` Logs: /var/lib/quill/logs/{ravendb,web,proxy,certwatch}.log 2026-08-26 10:23:42 Sharpening the quill... (5s) @@ -144,6 +148,9 @@ The first run is longer, since Quill also fetches the certificate and configurat * **Dashboard**: this is where you sign in to manage Quill. * **Database**: reaches the RavenDB server inside the container, allowing you to [read the mirrored data directly](../security-and-architecture/network-architecture.mdx#direct-database-access). +* **Note**: appears only when Quill runs in WSL 2, e.g., on Docker Desktop for Windows. + It warns that other devices on your network may be unable to reach Quill, and links to + [LAN Access on Windows](../networking/lan-access-on-windows.mdx). diff --git a/quill/home.mdx b/quill/home.mdx index 79ca1288cf..dca4aa42e2 100644 --- a/quill/home.mdx +++ b/quill/home.mdx @@ -94,10 +94,10 @@ import CardWithIcon from "@site/src/components/Common/CardWithIcon"; url="/quill/dashboard/my-apps" /> @@ -20,6 +19,9 @@ import ContentFrame from '@site/src/components/ContentFrame'; * This article explains the DNS names associated with a Quill instance, what DNS controls, and how to update and verify the published records after the host's IP address changes. +* If Quill runs on Docker Desktop or WSL on Windows, other devices on your network may be unable to reach it. + [LAN Access on Windows](lan-access-on-windows.mdx) explains how to allow them. + * In this article: * [Quill DNS records](#quill-dns-records) * [The published hostnames](#the-published-hostnames) @@ -69,9 +71,9 @@ The first four hostnames expose Quill's customer-facing service surfaces. Quill does not publish corresponding `-tcp` records. Direct RavenDB access through `db.` or a topology-discovered `a.` address uses HTTPS on port `443`; the native RavenDB TCP listener is not exposed by default. -Learn more in [Direct database access](security-and-architecture/network-architecture.mdx#direct-database-access). +Learn more in [Direct database access](../security-and-architecture/network-architecture.mdx#direct-database-access). -For details about how connections to these hostnames are routed and protected, see [The Quill hostnames](security-and-architecture/network-architecture.mdx#the-quill-hostnames). +For details about how connections to these hostnames are routed and protected, see [The Quill hostnames](../security-and-architecture/network-architecture.mdx#the-quill-hostnames). The behavior of the RavenDB node hostname is described in [The `a` hostname](#the-a-hostname). @@ -104,7 +106,7 @@ As a result, communication between Quill and RavenDB remains on loopback without * DNS updates include `a.` together with the other four records. For more information about direct RavenDB connections and your Quill's network limitations, -see [Direct database access](security-and-architecture/network-architecture.mdx#direct-database-access). +see [Direct database access](../security-and-architecture/network-architecture.mdx#direct-database-access). @@ -146,9 +148,9 @@ The host's firewall, cloud security rules, and any intervening NAT configuration 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](security-and-architecture/network-architecture.mdx#how-a-connection-is-routed) and -[The TLS front and the wildcard certificate](security-and-architecture/network-architecture.mdx#the-tls-front-and-the-wildcard-certificate). -For dashboard and API authentication, see [Operator Authentication](security-and-architecture/operator-authentication.mdx). +[How a connection is routed](../security-and-architecture/network-architecture.mdx#how-a-connection-is-routed) and +[The TLS front and the wildcard certificate](../security-and-architecture/network-architecture.mdx#the-tls-front-and-the-wildcard-certificate). +For dashboard and API authentication, see [Operator Authentication](../security-and-architecture/operator-authentication.mdx). @@ -205,8 +207,8 @@ The Quill domain and the URLs used by operators, chat users, and applications re 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](security-and-architecture/network-architecture.mdx#the-tls-front-and-the-wildcard-certificate). -For information about preserving or replacing the Dashboard API key, see [Operator Authentication](security-and-architecture/operator-authentication.mdx). +For details about the wildcard certificate, see [The TLS front and the wildcard certificate](../security-and-architecture/network-architecture.mdx#the-tls-front-and-the-wildcard-certificate). +For information about preserving or replacing the Dashboard API key, see [Operator Authentication](../security-and-architecture/operator-authentication.mdx). @@ -401,7 +403,7 @@ If your deployment uses the other surfaces, verify them through their normal acc * open an existing embed link through `public.`; * connect to `db.` with a recognized client certificate. -For the requirements of a direct RavenDB connection, see [Direct database access](security-and-architecture/network-architecture.mdx#direct-database-access). +For the requirements of a direct RavenDB connection, see [Direct database access](../security-and-architecture/network-architecture.mdx#direct-database-access). If any verification step fails, continue with [Diagnose failures](#diagnose-failures). @@ -416,11 +418,12 @@ Use the point at which verification fails to identify the affected layer: | A hostname does not resolve | The hostname or base domain is incorrect, the record was not provisioned, or a resolver cached an earlier "not found" response | Compare 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 address | The answer is cached or the update has not completed | Allow for the TTL, then resolve all five hostnames again | | The hostname resolves correctly, but the connection times out | External TCP port `443` is blocked or does not reach container port `443` | Check the firewall, cloud security rules, NAT or load-balancer forwarding, and Docker port mapping | +| Other devices cannot connect, although the hostname resolves to the LAN address of the Windows machine running Quill | WSL's default networking mode or a firewall may be preventing LAN access to Quill | Check port publishing, firewalls, and WSL networking, as described in [LAN Access on Windows](lan-access-on-windows.mdx) | | The hostname resolves correctly, but the connection is refused | The container is stopped or nothing is accepting the forwarded connection | Check the container state and Docker port mapping | | HTTPS reports a certificate error | The certificate is expired, invalid, or does not cover the requested hostname | Inspect the certificate and certificate-renewal logs | | `/healthz` returns an unsuccessful response | The Quill web application or RavenDB is not ready | Check bootstrap status and the Quill logs | -| `/healthz` succeeds, but the dashboard or API returns `401` | The DNS change succeeded, but the expected Dashboard API key was not preserved | Check `QUILL_API_KEY` and see [Operator Authentication](security-and-architecture/operator-authentication.mdx) | -| Dashboard health succeeds, but `db.` connections fail | DNS and the web surface are working; investigate the client certificate and RavenDB connection separately | See [Direct database access](security-and-architecture/network-architecture.mdx#direct-database-access) | +| `/healthz` succeeds, but the dashboard or API returns `401` | The DNS change succeeded, but the expected Dashboard API key was not preserved | Check `QUILL_API_KEY` and see [Operator Authentication](../security-and-architecture/operator-authentication.mdx) | +| Dashboard health succeeds, but `db.` connections fail | DNS and the web surface are working; investigate the client certificate and RavenDB connection separately | See [Direct database access](../security-and-architecture/network-architecture.mdx#direct-database-access) | --- @@ -525,10 +528,10 @@ docker exec tail -n 100 \ ```
-For general guidance on reading and following log files, see [Read a log file](logging.mdx#read-a-log-file). -For certificate behavior and renewal, see [The TLS front and the wildcard certificate](security-and-architecture/network-architecture.mdx#the-tls-front-and-the-wildcard-certificate). -For dashboard and API authorization failures, see [Operator Authentication](security-and-architecture/operator-authentication.mdx). -For client-certificate requirements, see [Direct database access](security-and-architecture/network-architecture.mdx#direct-database-access). +For general guidance on reading and following log files, see [Read a log file](../logging.mdx#read-a-log-file). +For certificate behavior and renewal, see [The TLS front and the wildcard certificate](../security-and-architecture/network-architecture.mdx#the-tls-front-and-the-wildcard-certificate). +For dashboard and API authorization failures, see [Operator Authentication](../security-and-architecture/operator-authentication.mdx). +For client-certificate requirements, see [Direct database access](../security-and-architecture/network-architecture.mdx#direct-database-access). diff --git a/quill/networking/lan-access-on-windows.mdx b/quill/networking/lan-access-on-windows.mdx new file mode 100644 index 0000000000..6bb418e902 --- /dev/null +++ b/quill/networking/lan-access-on-windows.mdx @@ -0,0 +1,229 @@ +--- +title: "LAN Access on Windows" +sidebar_label: "LAN Access on Windows" +description: "Allow devices on your local network to reach Quill running on Windows with Docker Desktop's WSL 2 backend or Docker Engine inside WSL." +sidebar_position: 2 +--- + +import Admonition from '@theme/Admonition'; +import Panel from '@site/src/components/Panel'; +import ContentFrame from '@site/src/components/ContentFrame'; + + + +* This article explains how to make Quill running on a Windows machine reachable from other devices on your local network. + +* In this article: + * [When other devices cannot reach Quill](#when-other-devices-cannot-reach-quill) + * [Enable mirrored networking](#enable-mirrored-networking) + * [Point the records at the LAN address](#point-the-records-at-the-lan-address) + * [Verify access from the LAN](#verify-access-from-the-lan) + * [Summary](#summary) + + + + + +On Windows, Quill runs in WSL 2 when you use Docker Desktop with its default WSL 2 backend, or Docker Engine installed in a WSL distribution. + +In some setups, WSL's default networking mode or a firewall may prevent LAN traffic from reaching Quill. +Possible symptoms include: + +* Devices on your local network cannot connect to Quill, even when its hostnames resolve to the Windows machine's LAN address. +* The Windows machine itself cannot connect to Quill through its own LAN address, although it can connect through `localhost`. + +A Linux host that runs Docker Engine directly is not affected. + +When Quill detects WSL, it prints a note with the `Status: READY` message at startup, +as described in [Starting Quill: Watching Quill come up](../getting-started/starting-quill.mdx#watching-quill-come-up). + +--- + +To let other devices reach Quill: + +1. [Enable mirrored networking](#enable-mirrored-networking) in WSL. +2. [Point the records at the LAN address](#point-the-records-at-the-lan-address) of the Windows machine. +3. [Verify access from the LAN](#verify-access-from-the-lan), on the Windows machine and on another device. + +In the commands below: + +* `` is your Quill's base domain, `.myquill.ai` (e.g., `acme.myquill.ai`). +* `` is the name specified by `docker run --name`. + +Run `docker` commands in PowerShell when you use Docker Desktop, or in the WSL distribution's shell when you use Docker Engine in WSL. + + + +#### Prerequisites + +* Windows 11, version 22H2 or later. + WSL's mirrored networking mode is not available on earlier Windows versions. +* The requirements of the `update-dns` command, listed in [Update the records](dns-and-ip-configuration.mdx#update-the-records). + + + +{/* +TODO: Questions to Omer: +* Which Windows, WSL, and Docker Desktop versions was the workaround verified on? +* Was access verified from another LAN device as well as from the Windows machine through its LAN address? +* Is an inbound firewall rule for port 443 required (Windows Firewall or Hyper-V firewall)? If so, which one? + +=> Update this section and "If another device cannot connect" accordingly. +*/} + + + + + +WSL reads its settings from the `.wslconfig` file in your Windows user profile folder. +These settings apply to every WSL 2 distribution on the Windows machine, including the one Docker Desktop runs. + +1. Create or open `%UserProfile%\.wslconfig` (e.g., `C:\Users\\.wslconfig`), and add the following settings: + + ```text + [wsl2] + networkingMode=mirrored + + [experimental] + hostAddressLoopback=true + ``` + + If the file already has a `[wsl2]` or `[experimental]` section, add the setting to that section rather than adding the section again. + + * `networkingMode=mirrored` mirrors the Windows machine's network interfaces into WSL, + so devices on your network can connect to Quill through the Windows machine's LAN address. + * `hostAddressLoopback=true` lets the Windows machine connect to Quill through its own IPv4 LAN address, + in addition to `127.0.0.1`. WSL lists this setting as experimental. + +2. Shut down WSL, so it restarts with the new settings: + + ```powershell + wsl --shutdown + ``` + + This stops every running WSL distribution, including Docker Desktop's engine and the Quill container. + +3. Restart Docker Desktop. + If you use Docker Engine in a WSL distribution, open the distribution again and make sure Docker is running. + +4. Start Quill again: + + ```bash + docker start + ``` + + The container keeps its data volume, so Quill starts with its existing apps and settings. + + + + + +Other devices reach Quill through its hostnames, so the five DNS records must resolve to the Windows machine's LAN address. + +1. Find the LAN address: + + ```powershell + ipconfig + ``` + + Use the **IPv4 Address** of the adapter that connects the Windows machine to your network, + such as Wi-Fi or Ethernet (e.g., `192.168.1.20`). + +2. Check the address that the records currently return: + + ```powershell + nslookup dashboard. + ``` + + If the lookup already returns the LAN address, continue with [Verify access from the LAN](#verify-access-from-the-lan). + +3. Otherwise, update the records, replacing `` with the LAN address: + + ```bash + docker exec update-dns --ip + ``` + + The command and its output are described in [Update the records](dns-and-ip-configuration.mdx#update-the-records). + Resolvers that cached the previous address may keep returning it for about 30 minutes, + as described in [DNS propagation and TTL](dns-and-ip-configuration.mdx#dns-propagation-and-ttl). + +A LAN address is usually private, so devices outside your network cannot reach Quill through it. +If your router later assigns the Windows machine a different address, update the records again. + + + + + +Verify access from the Windows machine that runs Quill, and from another device on the same network. + +--- + + + +### Check from the Windows machine + +Run the following commands in PowerShell: + +```powershell +nslookup dashboard. +curl.exe --fail --silent --show-error https://dashboard./healthz +``` +
+ +The lookup should return the LAN address, and the health check should print `Healthy`. +In Windows PowerShell, `curl` is an alias of `Invoke-WebRequest`, so type `curl.exe`. + +If the lookup returns the LAN address but the health check fails, +make sure that `hostAddressLoopback=true` is in the `[experimental]` section of `.wslconfig`, +and that WSL was shut down after the file was saved. + + + + +### Check from another device + +On another device on the same network: + +* `nslookup dashboard.` should return the LAN address. +* `https://dashboard.` should open the management dashboard in a browser. + To check without a browser, run `curl --fail --silent --show-error https://dashboard./healthz`, which should print `Healthy`. + + + + +### If another device cannot connect + +* If the lookup returns a different address, the records were not updated, or a resolver still returns the previous address. + See [Point the records at the LAN address](#point-the-records-at-the-lan-address) and [DNS propagation and TTL](dns-and-ip-configuration.mdx#dns-propagation-and-ttl). + +* Make sure that the container publishes port `443`, as described in [Check the container and published port](dns-and-ip-configuration.mdx#check-the-container-and-published-port). + +* Check Windows Firewall and any other firewall software on the Windows machine. + Allow inbound TCP connections on port `443`. + +* If WSL's Hyper-V firewall blocks inbound traffic, allow TCP connections on port `443`. + Microsoft's [Mirrored mode networking](https://learn.microsoft.com/en-us/windows/wsl/networking#mirrored-mode-networking) documentation gives the following command for allowing inbound connections on a port. + + Run it in PowerShell as an administrator: + + ```powershell + New-NetFirewallHyperVRule -Name "Quill-HTTPS" -DisplayName "Quill HTTPS" -Direction Inbound -VMCreatorId '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -Protocol TCP -LocalPorts 443 + ``` + + + + + + +* On Windows, WSL's default networking mode or a firewall may prevent LAN access to Quill. + +* Enable WSL mirrored networking with `hostAddressLoopback` and shut down WSL. + Restart Docker Desktop, or reopen the WSL distribution if you use Docker Engine, and start Quill again. + +* Point Quill's five DNS records at the Windows machine's LAN address. + A private LAN address is reachable only from within your network. + +* Verify DNS resolution and HTTPS access from both the Windows machine and another device on the same network. + If access fails, check port publishing, Windows Firewall, and WSL's Hyper-V firewall. + + diff --git a/quill/updating-quill.mdx b/quill/updating-quill.mdx index b98f1316a7..a593056829 100644 --- a/quill/updating-quill.mdx +++ b/quill/updating-quill.mdx @@ -116,7 +116,7 @@ In these names: For `https://dashboard.acme.myquill.ai`, the examples use `quill-acme` as the container name and `quill-acme-data` as the volume name. If your deployment uses different names, use the actual names identified in the next panel. -For the hostnames published beneath the base domain, see [The published hostnames](networking-and-dns.mdx#the-published-hostnames). +For the hostnames published beneath the base domain, see [The published hostnames](networking/dns-and-ip-configuration.mdx#the-published-hostnames). Mounting the same data volume at `/var/lib/quill` reconnects the replacement container to the existing Quill data. Preserve the same required environment values and port mapping so that Quill returns with the same credentials and at the same address. @@ -318,7 +318,7 @@ The `state` field reports `Ready` when startup is complete. | The dashboard loads, but the expected apps or data are missing | The replacement mounted the wrong volume, or created a new empty volume | Stop the replacement container and follow [Recover the recorded data volume](#recover-the-recorded-data-volume). | | The container does not remain running | Startup failed | Read `docker logs --tail 100 ` and verify the image, port mapping, and environment options against the setup-email command. | | The dashboard returns `401` | The replacement uses a different Dashboard API key, or you are signing in with the previous key | Sign in with the `QUILL_API_KEY` supplied to the replacement. If the key changed unintentionally, recreate the container with the recorded original value. See [Operator Authentication](security-and-architecture/operator-authentication.mdx). | -| Quill is not reachable at its usual address | The published port changed, or the host address or DNS records no longer match | Confirm the port mapping. If the host address changed, follow [Networking & DNS](networking-and-dns.mdx). | +| Quill is not reachable at its usual address | The published port changed, or the host address or DNS records no longer match | Confirm the port mapping. If the host address changed, follow [DNS & IP Configuration](networking/dns-and-ip-configuration.mdx). | diff --git a/scripts/redirects.json b/scripts/redirects.json index e49294d400..3f2fd60ff5 100644 --- a/scripts/redirects.json +++ b/scripts/redirects.json @@ -1192,5 +1192,11 @@ "value": { "targetUrl": "/quill/getting-started/adding-a-web-widget-channel" } + }, + { + "key": "/quill/networking-and-dns", + "value": { + "targetUrl": "/quill/networking/dns-and-ip-configuration" + } } ] From fea7664640c1f5dd6c8b9b00ae3541f96aa6f68a Mon Sep 17 00:00:00 2001 From: Danielle9897 Date: Sun, 25 Oct 2026 16:28:30 +0200 Subject: [PATCH 2/2] RDoc-4123 Remove the TODO comment. Questions were answered; no changes to the guidance were needed. --- quill/networking/lan-access-on-windows.mdx | 9 --------- 1 file changed, 9 deletions(-) diff --git a/quill/networking/lan-access-on-windows.mdx b/quill/networking/lan-access-on-windows.mdx index 6bb418e902..63e8d2cb4b 100644 --- a/quill/networking/lan-access-on-windows.mdx +++ b/quill/networking/lan-access-on-windows.mdx @@ -62,15 +62,6 @@ Run `docker` commands in PowerShell when you use Docker Desktop, or in the WSL d -{/* -TODO: Questions to Omer: -* Which Windows, WSL, and Docker Desktop versions was the workaround verified on? -* Was access verified from another LAN device as well as from the Windows machine through its LAN address? -* Is an inbound firewall rule for port 443 required (Windows Firewall or Hyper-V firewall)? If so, which one? - -=> Update this section and "If another device cannot connect" accordingly. -*/} -