fix: use native DNS resolution by default for Docker services (#6997)

* fix: use native DNS resolution by default for Docker services

* test: verify Docker service DNS through production Compose

* test: isolate Docker DNS smoke resources per invocation [skip ci]

apps/docs/docs/advanced/environment-variables/index.mdx

@@ -36,7 +36,7 @@ Using the `PUID` and `PGID` will require you to set the correct permissions on t
 | `LOG_LEVEL`              | Log level to use                                                                                                                                                                                                                       | `debug` / `info` / `warn` / `error` | `info`                        |
 | `BASE_URL`               | Public Homarr origin used by MCP OAuth metadata and redirects. Set this when a reverse proxy does not preserve the public host and protocol.                                                                                           | HTTP(S) origin without a path       | -                             |
 | `NO_EXTERNAL_CONNECTION` | Disables Homarr's internet-backed requests, including update checks, weather, location search, and RSS feeds                                                                                                                           | `true` or `false`                   | `false`                       |
-| `ENABLE_DNS_CACHING`     | Enables dns caching. Enabled by default, but if you experience issues with IPv6 or static IPs, see [#4006](https://github.com/homarr-labs/homarr/issues/4006) or disable this flag                                                     | `true` or `false`                   | `true`                        |
+| `ENABLE_DNS_CACHING`     | Opt-in DNS cache. Keep disabled for Docker service names and `extra_hosts`; cached addresses can survive container recreation and DNS-first lookup can override hosts-file entries.                                                    | `true` or `false`                   | `false`                       |
 | `HOMARR_DISABLE_IPV6`    | Disables the IPv6 listener of the internal nginx proxy, even when the host supports IPv6. IPv6 is normally disabled automatically when the host has no IPv6 configured. See [#4596](https://github.com/homarr-labs/homarr/issues/4596) | `true` or `false`                   | `false`                       |
 | `HOMARR_WEBSITE_URL`     | Main Homarr documentation/site base used by runtime links. Must be an absolute HTTP(S) URL.                                                                                                                                            | HTTP(S) URL                         | `https://homarr.dev`          |
 | `WORKSHOP_API_URL`       | PocketBase API used by Homarr and standalone documentation.                                                                                                                                                                            | HTTP(S) URL                         | `HOMARR_WEBSITE_URL`          |

apps/docs/docs/management/integrations/index.mdx

@@ -67,6 +67,29 @@ or groups. Lists are filtered on the server and only include connections the cur
 
 ## Connection problems
 
+### Docker service URLs
+
+Use the service name and **container port** when Homarr and the service share a user-defined Docker network.
+For example, Sonarr with `ports: ["6767:8989"]` is reachable from Homarr at `http://sonarr:8989`.
+Use `http://sonarr:6767` only if Sonarr actually listens on `6767` inside its container.
+The browser-facing app URL can use the published host port or reverse proxy.
+See [Docker Compose networking](https://docs.docker.com/compose/how-tos/networking/).
+
+Homarr uses native name resolution by default. Leave `ENABLE_DNS_CACHING` unset or set it to `false`:
+the optional cache can retain an old IP after a container is recreated and can override `extra_hosts` entries.
+If an outbound proxy is configured, exclude local service names with `NO_PROXY`, for example `sonarr,radarr,jellyfin`.
+
+To check Docker DNS independently of Homarr, replace `homarr` with your container name:
+
+```sh
+docker exec homarr node -e 'require("node:dns").lookup("sonarr", { all: true }, (error, addresses) => console.log(error?.code ?? addresses))'
+```
+
+`ENOTFOUND` here indicates a container resolver or network problem. Check both services' network membership and
+Docker's embedded DNS; changing a Next.js setting cannot repair that resolver.
+
+### Other connection failures
+
 If a connection test fails:
 
 1. Check the integration page for the required base URL and credentials.