From dee7d475695c442acb2328c1fce4a1291cac44ce Mon Sep 17 00:00:00 2001
From: Joel Hans <joel@netdata.cloud>
Date: Mon, 26 Oct 2020 10:54:46 -0700
Subject: Add documentation for configuring/editing hostnames of Docker-run
 Agents (#10087)

* Add doc for Docker hostname

* Small tweak

* Remove extra w
---
 packaging/docker/README.md | 37 ++++++++++++++++++++++++++++++++++---
 1 file changed, 34 insertions(+), 3 deletions(-)

(limited to 'packaging')

diff --git a/packaging/docker/README.md b/packaging/docker/README.md
index 2b53f5f837..ecdde44099 100644
--- a/packaging/docker/README.md
+++ b/packaging/docker/README.md
@@ -119,9 +119,9 @@ need to use a non-default configuration for health checks to work.
 
 ## Configure Agent containers
 
-If you started an Agent container using one of the [recommended methods](#create-a-new-netdata-agent-container), you
-must first use `docker exec` to attach to the container. Replace `netdata` with the name of your Agent container in the
-first command below.
+If you started an Agent container using one of the [recommended methods](#create-a-new-netdata-agent-container) and you
+want to edit Netdata's configuration, you must first use `docker exec` to attach to the container. Replace `netdata`
+with the name of your container.
 
 ```bash
 docker exec -it netdata bash
@@ -199,6 +199,37 @@ volumes:
   netdatacache:
 ```
 
+### Change the default hostname
+
+You can change the hostname of a Docker container, and thus the name that appears in the local dashboard and in Netdata
+Cloud, when creating a new container. If you want to change the hostname of a Netdata container _after_ you started it,
+you can safely stop and remove it. You configuration and metrics data reside in persistent volumes and are reattached to
+the recreated container.
+
+If you use `docker-run`, use the `--hostname` option with `docker run`.
+
+```bash
+docker run -d --name=netdata \
+  --hostname=my_docker_netdata
+```
+
+If you use `docker-compose`, add a `hostname:` key/value pair into your `docker-compose.yml` file, then create the
+container again using `docker-compose up -d`.
+
+```yaml
+version: '3'
+services:
+  netdata:
+    image: netdata/netdata
+    container_name: netdata
+    hostname: my_docker_compose_netdata
+    ...
+```
+
+If you don't want to destroy and recreate your container, you can edit the Agent's `netdata.conf` file directly. See the
+above section on [configuring Agent containers](#configure-agent-containers) to find the appropriate method based on
+how you created the container.
+
 ### Add or remove other volumes
 
 Some of the volumes are optional depending on how you use Netdata:
-- 
cgit v1.2.3