From 4c1f5b40622b85abcb119851a2c6563ec223bb1c Mon Sep 17 00:00:00 2001 From: Amir Raminfar Date: Wed, 20 Nov 2024 09:41:58 -0800 Subject: [PATCH] docs: fixes grammar and spelling errors (#3413) --- docs/guide/actions.md | 9 ++++---- docs/guide/agent.md | 36 ++++++++++++++++---------------- docs/guide/analytics.md | 10 ++++----- docs/guide/authentication.md | 24 +++++++++------------ docs/guide/changing-base.md | 4 ++-- docs/guide/debugging.md | 4 ++-- docs/guide/faq.md | 24 ++++++++++----------- docs/guide/getting-started.md | 2 +- docs/guide/healthcheck.md | 4 ++-- docs/guide/hostname.md | 2 +- docs/guide/log-files-on-disk.md | 8 +++---- docs/guide/podman.md | 22 +++++++++---------- docs/guide/remote-hosts.md | 20 +++++++++--------- docs/guide/sql-engine.md | 12 +++++------ docs/guide/supported-env-vars.md | 8 +++---- docs/guide/swarm-mode.md | 14 ++++++------- docs/guide/usage-dashboard.md | 9 -------- 17 files changed, 99 insertions(+), 113 deletions(-) delete mode 100644 docs/guide/usage-dashboard.md diff --git a/docs/guide/actions.md b/docs/guide/actions.md index 9636da99..cd7cb3a7 100644 --- a/docs/guide/actions.md +++ b/docs/guide/actions.md @@ -4,11 +4,9 @@ title: Container Actions # Using Container Actions -Dozzle now supports **Container Actions**, which allows you to `start`, `stop` and `restart` container from within the UI in the dropdown menu. +Dozzle now supports **Container Actions**, which allows you to `start`, `stop` and `restart` containers from within the UI in the dropdown menu. -Container Acions Menu UI - -This feature is **disabled** by default, which can be enabled by setting environment variable`DOZZLE_ENABLE_ACTIONS` to `true` +This feature is **disabled** by default and can be enabled by setting the environment variable `DOZZLE_ENABLE_ACTIONS` to `true`. ::: code-group @@ -24,7 +22,8 @@ services: - /var/run/docker.sock:/var/run/docker.sock ports: - 8080:8080 - environment: DOZZLE_ENABLE_ACTIONS=true + environment: + DOZZLE_ENABLE_ACTIONS: true ``` ::: diff --git a/docs/guide/agent.md b/docs/guide/agent.md index f4eff22b..734527f8 100644 --- a/docs/guide/agent.md +++ b/docs/guide/agent.md @@ -9,7 +9,7 @@ Dozzle can run in agent mode which can expose Docker hosts to other Dozzle insta > [!NOTE] Using Docker Swarm? > If you are using Docker Swarm Mode, you don't need to use agents. Dozzle will automatically discover itself and create a cluster using swarm mode. See [Swarm Mode](/guide/swarm-mode) for more information. -## How to create an agent? +## How to Create an Agent To create a Dozzle agent, you need to run Dozzle with the `agent` subcommand. Here is an example: @@ -37,7 +37,7 @@ The agent will start and listen on port `7007`. You can connect to the agent usi > [!TIP] > You don't need to expose port 7007 if using Docker network. The agent will be available to other containers on the same network. -## How to connect to an agent? +## How to Connect to an Agent To connect to an agent, you need to provide the agent's IP address and port. Here is an example: @@ -65,9 +65,9 @@ Note that when connecting remotely, you don't need to mount local Docker socket. > You can connect to multiple agents by providing multiple `DOZZLE_REMOTE_AGENT` environment variables. For example, `DOZZLE_REMOTE_AGENT=agent1:7007,agent2:7007`. > [!WARNING] -> Dozzle uses the Docker API to gather information about hosts. Each aget needs a unique host ID. They use Docker's system ID or node ID to identify the host. If you are using swarm, then the node ID is used. If you don't see all hosts, then you may have duplicate hosts configured that have the same host ID. To fix this, remove `/var/lib/docker/engine-id` file. See [FAQ](/guide/faq#i-am-seeing-duplicate-hosts-error-in-the-logs-how-do-i-fix-it) for more information. +> Dozzle uses the Docker API to gather information about hosts. Each agent needs a unique host ID. They use Docker's system ID or node ID to identify the host. If you are using swarm, then the node ID is used. If you don't see all hosts, then you may have duplicate hosts configured that have the same host ID. To fix this, remove `/var/lib/docker/engine-id` file. See [FAQ](/guide/faq#i-am-seeing-duplicate-hosts-error-in-the-logs-how-do-i-fix-it) for more information. -## Setting up healthcheck +## Setting Up Healthcheck You can set a healthcheck for the agent, similar to the healthcheck for the main Dozzle instance. When running in agent mode, healthcheck checks agent connection to Docker. If Docker is not reachable, the agent will be marked as unhealthy and will not be shown in the UI. @@ -90,7 +90,7 @@ services: - 7007:7007 ``` -## Changing agent's name +## Changing Agent's Name Similar to Dozzle instance, you can change the agent's name by providing the `DOZZLE_HOSTNAME` environment variable. Here is an example: @@ -115,11 +115,11 @@ services: ::: -This will change the agent's name to `my-special-name` and reflected on the UI when connecting to the agent. +This will change the agent's name to `my-special-name` and will be reflected on the UI when connecting to the agent. -## Custom certificates +## Custom Certificates -By default, Dozzle uses self-signed certificates for communication between agents. This is a private certificate which is only valid to other Dozzle instances. This is secure and recommended for most use cases. However, if Dozzle is exposed extenrally and an attacker knows exactly which port the agent is running on, then they can setup their own Dozzle instance and connect to the agent. To prevent this, you can provide your own certificates. +By default, Dozzle uses self-signed certificates for communication between agents. This is a private certificate which is only valid to other Dozzle instances. This is secure and recommended for most use cases. However, if Dozzle is exposed externally and an attacker knows exactly which port the agent is running on, then they can set up their own Dozzle instance and connect to the agent. To prevent this, you can provide your own certificates. To provide custom certificates, you need to mount or use secrets to provide the certificates. Here is an example: @@ -145,7 +145,7 @@ secrets: ``` > [!TIP] -> Docker secrets are preferred for providing certificates. The can be created using `docker secret create` command or as the example above using `docker-compose.yml`. The same certificates should be provided to the Dozzle instance connecting to the agent. +> Docker secrets are preferred for providing certificates. They can be created using `docker secret create` command or as the example above using `docker-compose.yml`. The same certificates should be provided to the Dozzle instance connecting to the agent. This will mount the `cert.pem` and `key.pem` files to the agent. The agent will use these certificates for communication. The same certificates should be provided to the Dozzle instance connecting to the agent. @@ -157,17 +157,17 @@ $ openssl req -new -key key.pem -out request.csr -subj "/C=US/ST=California/L=Sa $ openssl x509 -req -in request.csr -signkey key.pem -out cert.pem -days 365 ``` -## Comparing agents with remote connection +## Comparing Agents with Remote Connection Agents are similar to remote connections, but they have some advantages. Generally, agents are preferred over remote connections due to performance and security reasons. Here is a comparison: -| Feature | Agent | Remote Connection | -| ----------- | -------------------------- | ------------------------------- | -| Performance | Better with disturbed load | Worse on the UI | -| Security | Private SSL | Insecure or Docker TLS | -| Ease of use | Easy out of the box | Requires exposing Docker socket | -| Permissions | Full access to Docker | Can be controlled with a proxy | -| Reconnect | Automatically reconnects | Requires UI restart | -| Healthcheck | Built-in healthcheck | No healthcheck | +| Feature | Agent | Remote Connection | +| ----------- | ---------------------------- | ------------------------------- | +| Performance | Better with distributed load | Worse on the UI | +| Security | Private SSL | Insecure or Docker TLS | +| Ease of use | Easy out of the box | Requires exposing Docker socket | +| Permissions | Full access to Docker | Can be controlled with a proxy | +| Reconnect | Automatically reconnects | Requires UI restart | +| Healthcheck | Built-in healthcheck | No healthcheck | If you do plan to use remote connections, make sure to secure the connection using Docker TLS or a reverse proxy. diff --git a/docs/guide/analytics.md b/docs/guide/analytics.md index 18a53da1..4cc2b7a2 100644 --- a/docs/guide/analytics.md +++ b/docs/guide/analytics.md @@ -4,12 +4,12 @@ title: Anonymous Analytics # Data Collection of Analytics -Dozzle collects anonymous user configurations using a simple beacon written in Go. _Why?_ Dozzle is an open source project with no funding. As a result, there is no time to do user studies of Dozzle. Analytics is collected to prioritize features and fixes based on how people use Dozzle. +Dozzle collects anonymous user configurations using a simple beacon written in Go. _Why?_ Dozzle is an open source project with no funding. As a result, there is no time to do user studies of Dozzle. Analytics are collected to prioritize features and fixes based on how people use Dozzle. -## Where is data stored +## Where is Data Stored -Dozzle's sends anonymous data to DigitalOcean which is written to a flat file for processing. +Dozzle sends anonymous data to DigitalOcean, where it is written to a flat file for processing. -## Opting out +## Opting Out -Dozzle analytics helps to prioritize features and spend time on most important features. If you do not want to be tracked at all, use `--no-analytics` flag or `DOZZLE_NO_ANALYTICS` env variable. +Dozzle analytics helps to prioritize features and spend time on the most important improvements. If you do not want to be tracked, use the `--no-analytics` flag or `DOZZLE_NO_ANALYTICS` environment variable. diff --git a/docs/guide/authentication.md b/docs/guide/authentication.md index 4783c63a..eb1ef276 100644 --- a/docs/guide/authentication.md +++ b/docs/guide/authentication.md @@ -4,11 +4,11 @@ title: Authentication # Setting Up Authentication -Dozzle support two configurations for authentication. In the first configuration, you bring your own authentication method by protecting Dozzle through a proxy. Dozzle can read appropriate headers out of the box. +Dozzle supports two configurations for authentication. In the first configuration, you bring your own authentication method by protecting Dozzle through a proxy. Dozzle can read appropriate headers out of the box. -If you do not have an authentication solution then Dozzle has a simple file based user management solution. Authentication providers are setup using `--auth-provider` flag. In both of these configurations, Dozzle will try to save user settings to disk. This data is written to `/data`. +If you do not have an authentication solution, then Dozzle has a simple file-based user management solution. Authentication providers are set up using the `--auth-provider` flag. In both configurations, Dozzle will try to save user settings to disk. This data is written to `/data`. -## File Based User Management +## File-Based User Management Dozzle supports multi-user authentication by setting `--auth-provider` to `simple`. In this mode, Dozzle will try to read `/data/users.yml`. @@ -88,11 +88,11 @@ services: ::: -Note that only the duration is supported. You can only use `s`, `m`, `h` for seconds, minutes and hours respectively. +Note that only duration is supported. You can only use `s`, `m`, `h` for seconds, minutes and hours respectively. ## Generating users.yml -Dozzle has a builtin `generate` command to generate `users.yml`. Here is an example: +Dozzle has a built-in `generate` command to generate `users.yml`. Here is an example: ```sh docker run amir20/dozzle generate admin --password password --email test@email.net --name "John Doe" > users.yml @@ -126,7 +126,7 @@ services: In this mode, Dozzle expects the following headers: -- `Remote-User` to map to the username eg. `johndoe` +- `Remote-User` to map to the username e.g. `johndoe` - `Remote-Email` to map to the user's email address. This email is also used to find the right [Gravatar](https://gravatar.com/) for the user. - `Remote-Name` to be a display name like `John Doe` @@ -194,6 +194,7 @@ services: - "--entrypoints.https.address=:443" - "--log=true" - "--log.level=DEBUG" + dozzle: image: amir20/dozzle:latest networks: @@ -216,7 +217,7 @@ services: ```yaml [configuration.yml] ############################################################### -# Authelia configuration # +# Authelia configuration # ############################################################### jwt_secret: a_very_important_secret @@ -269,9 +270,7 @@ Valid SSL keys are required because Authelia only supports SSL. ### Setting up Dozzle with Cloudflare Zero Trust -Cloudflare Zero Trust is a service for authenticated access to selfhosted -software. This section defines how Dozzle can be setup to use Cloudflare Zero -Trust for authentication. +Cloudflare Zero Trust is a service for authenticated access to self-hosted software. This section defines how Dozzle can be set up to use Cloudflare Zero Trust for authentication. ```yaml [docker-compose.yml] services: @@ -291,7 +290,4 @@ services: restart: unless-stopped ``` -After running the Dozzle container, configure the Application in Cloudflare Zero -Trust dashboard by following the -[guide](https://developers.cloudflare.com/cloudflare-one/applications/configure-apps/self-hosted-apps/) -here. +After running the Dozzle container, configure the Application in Cloudflare Zero Trust dashboard by following the [guide](https://developers.cloudflare.com/cloudflare-one/applications/configure-apps/self-hosted-apps/). diff --git a/docs/guide/changing-base.md b/docs/guide/changing-base.md index d4480489..7e93c3e0 100644 --- a/docs/guide/changing-base.md +++ b/docs/guide/changing-base.md @@ -28,9 +28,9 @@ services: Dozzle will be available at `http://localhost:8080/foobar/`. This option rewrites all assets to `/foobar/{file.path}` and automatically redirects `/foobar` to `/foobar/`. -## Example with proxy +## Example with Proxy -Here is an example with Nginx and proxy Dozzle with a different base: +Here is an example with Nginx to proxy Dozzle with a different base: ```nginx location ^~ /foobar/ { diff --git a/docs/guide/debugging.md b/docs/guide/debugging.md index ac2ad355..988fe628 100644 --- a/docs/guide/debugging.md +++ b/docs/guide/debugging.md @@ -2,9 +2,9 @@ title: Debugging --- -# Debugging with logs +# Debugging with Logs -By default, Dozzle does not output a lot of logs. However this can be changed with `--level` flag. The default value is `info` which only prints limited logs. You can use `debug` or `trace` which will show details about memory, configuration and other stats. `DOZZLE_LEVEL` can be used in compose configurations. Below is an example of using `docker-compose.yml` file to enable `debug` level. +By default, Dozzle does not output a lot of logs. However, this can be changed with the `--level` flag. The default value is `info` which only prints limited logs. You can use `debug` or `trace` which will show details about memory, configuration and other stats. `DOZZLE_LEVEL` can be used in compose configurations. Below is an example of using `docker-compose.yml` file to enable `debug` level. ```yaml services: diff --git a/docs/guide/faq.md b/docs/guide/faq.md index 61f1e21d..6ca272b9 100644 --- a/docs/guide/faq.md +++ b/docs/guide/faq.md @@ -31,7 +31,7 @@ server { ### Disabling compression in traefik -Traefik reverse proxy can be configures via middlewares to support compression. If implemented, the usual configuration looks like this: +Traefik reverse proxy can be configured via middlewares to support compression. If implemented, the usual configuration looks like this: ``` http: @@ -40,8 +40,8 @@ http: compress: {} ``` -With this setup, you may find that certain containers do not show logs in dozzle anymore if you open dozzle via traefik (e.g. dozzle.mydomain.com). -You will also note that the same dozzle instance does show the logs when accessed directly (e.g. localhost:8080). +With this setup, you may find that certain containers do not show logs in dozzle anymore if you open dozzle via traefik (e.g., dozzle.mydomain.com). +You will also note that the same dozzle instance does show the logs when accessed directly (e.g., localhost:8080). Containers where this has been observed (non-exhaustive list) are: dozzle, homepage, glances, filebrowser. @@ -56,7 +56,7 @@ http: - text/event-stream ``` -## We have tools that uses Dozzle when a new container is created. How can I get a direct link to a container by name? +## We have tools that use Dozzle when a new container is created. How can I get a direct link to a container by name? Dozzle has a special [route](https://github.com/amir20/dozzle/blob/master/assets/pages/show.vue) that can be used to search containers by name and then forward to that container. For example, if you have a container with name `"foo.bar"` and id `abc123`, you can send your users to `/show?name=foo.bar` which will be forwarded to `/container/abc123`. @@ -73,7 +73,7 @@ WARNING: No memory limit support WARNING: No swap limit support ``` -In this case, you'll need to add the following line to your `/boot/cmdline.txt` file and reboot your device. +In this case, you'll need to add the following line to your `/boot/cmdline.txt` file and reboot your device: ``` cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1 @@ -81,28 +81,28 @@ cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1 ## I am seeing duplicate hosts error in the logs. How do I fix it? -If you are seeing the following error in the logs, then you may have duplicate hosts in configred that with the same host ID. +If you are seeing the following error in the logs, then you may have duplicate hosts configured with the same host ID: ``` time="2024-07-10T13:35:53Z" level=warning msg="duplicate host ID: *********, Endpoint: 1.1.1.1:7007 found, skipping" ``` -Dozzle uses the Docker API to gather information about the hosts. Each host must have a unique ID. This ID is used to identify the host in the UI. In swarm mode, Dozzle uses the node ID from `docker systen info` to identify the host. If you are not using swarm mode, then Dozzle will use the system ID from `docker system info` as the host ID. +Dozzle uses the Docker API to gather information about the hosts. Each host must have a unique ID. This ID is used to identify the host in the UI. In swarm mode, Dozzle uses the node ID from `docker system info` to identify the host. If you are not using swarm mode, then Dozzle will use the system ID from `docker system info` as the host ID. -Somettimes, VMs maybe restored from back ups, with the same host ID. This can cause Dozzle to think that the host is already present and skip adding it to the list of hosts. To fix this, you need to remove `/var/lib/docker/engine-id` file. This file contains the host ID and is created when the Docker daemon starts. +Sometimes, VMs may be restored from backups with the same host ID. This can cause Dozzle to think that the host is already present and skip adding it to the list of hosts. To fix this, you need to remove `/var/lib/docker/engine-id` file. This file contains the host ID and is created when the Docker daemon starts. ## I am seeing host not found error in the logs. How do I fix it? This should be mainly a Podman only error: Using Podman doesn't create an engine-id like Docker. -If you are using Docker check if the ```engine-id``` file exists with correct permissions in ```/var/lib/docker``` and has the UUID inside. +If you are using Docker check if the `engine-id` file exists with correct permissions in `/var/lib/docker` and has the UUID inside. To resolve the error take following steps: -1. Create the folders: ```mkdir -p /var/lib/docker``` +1. Create the folders: `mkdir -p /var/lib/docker` 2. Install uuidgen if necessary -3. Using uuidgen generate an UUID: ```uuidgen > engine-id``` +3. Using uuidgen generate a UUID: `uuidgen > engine-id` -The engine-id file should now have an UUID inside. +The engine-id file should now have a UUID inside. An example setup for Ansible can be found in [Podman Infos](podman.md) diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index a3c12d4c..0d12b335 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -8,7 +8,7 @@ Dozzle supports multiple ways to run the application. You can run it using Docke ## Running with Docker -The easiest way to setup Dozzle is to use the CLI and mount `docker.sock` file. This file is usually located at `/var/run/docker.sock` and can be mounted with the `--volume` flag. You also need to expose the port to view Dozzle. By default, Dozzle listens on port 8080, but you can change the external port using `-p`. You can also run using compose or as a service in Swarm. +The easiest way to set up Dozzle is to use the CLI and mount `docker.sock` file. This file is usually located at `/var/run/docker.sock` and can be mounted with the `--volume` flag. You also need to expose the port to view Dozzle. By default, Dozzle listens on port 8080, but you can change the external port using `-p`. You can also run using compose or as a service in Swarm. ::: code-group diff --git a/docs/guide/healthcheck.md b/docs/guide/healthcheck.md index 313e0f7b..167c3e16 100644 --- a/docs/guide/healthcheck.md +++ b/docs/guide/healthcheck.md @@ -2,9 +2,9 @@ title: Healthcheck --- -# Enabling healthcheck +# Enabling Healthcheck -Dozzle has internal support for healthcheck using `dozzle healthcheck` command. It is not enabled by default as it adds extra CPU usage. To use `healthcheck` you need to configure it. Below is an example that checks the health of Dozzle every 3 seconds. +Dozzle has internal support for healthcheck using the `dozzle healthcheck` command. It is not enabled by default as it adds extra CPU usage. To use `healthcheck`, you need to configure it. Below is an example that checks the health of Dozzle every 3 seconds. ```yaml services: diff --git a/docs/guide/hostname.md b/docs/guide/hostname.md index 23ee4af6..e75d0c34 100644 --- a/docs/guide/hostname.md +++ b/docs/guide/hostname.md @@ -4,7 +4,7 @@ title: Hostname # Changing Dozzle's Hostname -Dozzle's default connection is called localhost. Using `--hostname` flag Dozzle's name can be changed to anything. This value be will shown on the page title and under the Dozzle logo. +Dozzle's default connection is called localhost. Using the `--hostname` flag, Dozzle's name can be changed to anything. This value will be shown on the page title and under the Dozzle logo. Changing the label for localhost also changes the label for the `localhost` connection which is displayed under the multi-host menu. Below is an example of using `--hostname` to change the name of Dozzle's subheader to `mywebsite.xyz`. diff --git a/docs/guide/log-files-on-disk.md b/docs/guide/log-files-on-disk.md index afd3a175..104fd32c 100644 --- a/docs/guide/log-files-on-disk.md +++ b/docs/guide/log-files-on-disk.md @@ -4,15 +4,15 @@ title: Following Log Files on Disk # Following Log Files on Disk -Some containers do not write logs to `sysout` or `syserr`. Many folks have asked if Dozzle can also show logs that are written to files. Unfortunately, files in containers are not accessible to other containers and so Dozzle wouldn't have a way to access these files. Dozzle can only access logs written to `sysout` or `syserr` which is the same functionality as `docker logs` command. +Some containers do not write logs to `sysout` or `syserr`. Many folks have asked if Dozzle can also show logs that are written to files. Unfortunately, files in containers are not accessible to other containers, so Dozzle wouldn't have a way to access these files. Dozzle can only access logs written to `sysout` or `syserr`, which is the same functionality as the `docker logs` command. -If you are creating a service using Docker then make sure to write logs to streams. An application should not attempt to write to logfiles. Instead delegate the logging to Docker. The [twelve factor app](https://12factor.net/logs) has a great principle around logging that explains the importance of this principle. +If you are creating a service using Docker, then make sure to write logs to streams. An application should not attempt to write to logfiles. Instead, delegate the logging to Docker. The [twelve factor app](https://12factor.net/logs) has a great principle around logging that explains the importance of this principle. However, there are workarounds to be able to still access files using mounts. ## Mounting Local Log Files with Alpine -Dozzle reads any output stream. This can be used in combination with alpine to `tail` a mounted file. An example of this is as follows: +Dozzle reads any output stream. This can be used in combination with Alpine to `tail` a mounted file. An example of this is as follows: ::: code-group @@ -37,6 +37,6 @@ services: ::: -In the above example `/var/log/system.log` is mounted from the host and used with `tail -f` to follow the file. `tail` is smart to follow log rotations. During my testing, using alpine only uses about `300KB` of memory. +In the above example, `/var/log/system.log` is mounted from the host and used with `tail -f` to follow the file. `tail` is smart to follow log rotations. During testing, using Alpine only uses about `300KB` of memory. The second tab shows a `docker-compose` file which is useful if you want the log stream to survive server reboot. diff --git a/docs/guide/podman.md b/docs/guide/podman.md index bbb95bbe..ef0d5457 100644 --- a/docs/guide/podman.md +++ b/docs/guide/podman.md @@ -5,35 +5,35 @@ title: Podman ## I am seeing host not found error in the logs. How do I fix it? This should be mainly a Podman only error: Using Podman doesn't create an engine-id like Docker. -If you are using Docker check if the ```engine-id``` file exists with correct permissions in ```/var/lib/docker``` and has the UUID inside. +If you are using Docker, check if the `engine-id` file exists with correct permissions in `/var/lib/docker` and has the UUID inside. -It might be necessary to clean up your existing Dozzle deployment under Podman, stop the container and remove the associated data (container/volumes). After you created the engine-id you can redeploy the Dozzle container and your logs should now show up. +It might be necessary to clean up your existing Dozzle deployment under Podman, stop the container and remove the associated data (container/volumes). After you create the engine-id, you can redeploy the Dozzle container and your logs should now show up. ## Create UUID -Options for generating UUIDs +Options for generating UUIDs: ### uuidgen -:warning: Adjust folder/file permissions if necessary. There isn't any critial info but depending on your existing setup you might want to take additional steps +:warning: Adjust folder/file permissions if necessary. There isn't any critical info but depending on your existing setup you might want to take additional steps. 1. Install uuidgen -2. Create the folders: ```mkdir -p /var/lib/docker``` -3. Using uuidgen generate an UUID: ```uuidgen > /var/lib/docker/engine-id``` -4. Verify with ```cat /var/lib/docker/engine-id``` +2. Create the folders: `mkdir -p /var/lib/docker` +3. Using uuidgen generate a UUID: `uuidgen > /var/lib/docker/engine-id` +4. Verify with `cat /var/lib/docker/engine-id` ### Ansible -:warning: Depending on your setup you might have to take adjustments for file/folder permissions. The following task snippets would run as the become_user/remote_user of the playbook running these tasks. +:warning: Depending on your setup you might have to make adjustments for file/folder permissions. The following task snippets would run as the become_user/remote_user of the playbook running these tasks. -If you wish to adjust the user you have to set individual become/become_user parameters for these tasks. +If you wish to adjust the user, you have to set individual become/become_user parameters for these tasks. -``` +```yaml - name: Create /var/lib/docker ansible.builtin.file: path: /var/lib/docker state: directory - mode: '755' + mode: "755" - name: Create engine-id and derive UUID from hostname ansible.builtin.lineinfile: diff --git a/docs/guide/remote-hosts.md b/docs/guide/remote-hosts.md index 9472bf1a..7cb7ff1d 100644 --- a/docs/guide/remote-hosts.md +++ b/docs/guide/remote-hosts.md @@ -11,13 +11,13 @@ However, with Dozzle agents, you can connect to remote hosts without exposing th > [!WARNING] > Remote hosts have been replaced with agents. Agents provide a more secure way to connect to remote hosts. Although remote hosts are still supported, it is recommended to use agents. See the [agent](/guide/agent) page for more information and examples. For comparison, see the [comparing agents with remote connections](/guide/agent#comparing-agents-with-remote-connection) section. -## Connecting to remote hosts with TLS +## Connecting to Remote Hosts with TLS -Remote hosts can be configured with `--remote-host` or `DOZZLE_REMOTE_HOST`. All certs must be mounted to `/certs` directory. The `/certs` directory expects to have `/certs/{ca,cert,key}.pem` or `/certs/{host}/{ca,cert,key}.pem` in case of multiple hosts. +Remote hosts can be configured with `--remote-host` or `DOZZLE_REMOTE_HOST`. All certificates must be mounted to `/certs` directory. The `/certs` directory expects to have `/certs/{ca,cert,key}.pem` or `/certs/{host}/{ca,cert,key}.pem` in case of multiple hosts. Note the `{host}` value referred to here is the IP or FQDN configured and not the [optional label](#adding-labels-to-hosts). -Multiple `--remote-host` flags can be used to specify multiple hosts. However, using `DOZZLE_REMOTE_HOST` the value should be comma separated. +Multiple `--remote-host` flags can be used to specify multiple hosts. However, when using `DOZZLE_REMOTE_HOST`, the value should be comma-separated. ::: code-group @@ -40,9 +40,9 @@ services: ::: -## Connecting with a socket proxy +## Connecting with a Socket Proxy -If you are in a private network then you can use [Docker Socket Proxy](https://github.com/Tecnativa/docker-socket-proxy) which expose `docker.sock` file without the need of TLS. Dozzle will never try to write to Docker but it will need access to list APIs. The following command will start a proxy with minimal access. +If you are in a private network, then you can use [Docker Socket Proxy](https://github.com/Tecnativa/docker-socket-proxy) which exposes `docker.sock` file without the need for TLS. Dozzle will never try to write to Docker but it will need access to list APIs. The following command will start a proxy with minimal access: ```sh docker container run --privileged -e CONTAINERS=1 -e INFO=1 -v /var/run/docker.sock:/var/run/docker.sock -p 2375:2375 tecnativa/docker-socket-proxy @@ -51,7 +51,7 @@ docker container run --privileged -e CONTAINERS=1 -e INFO=1 -v /var/run/docker.s > [!TIP] > Using `CONTAINERS=1` is required to list running containers. `EVENTS` is also needed but it is enabled by default. `INFO=1` is needed to list system information. -Running Dozzle without any certs should work. Here is an example: +Running Dozzle without any certificates should work. Here is an example: ```sh docker run --volume=/var/run/docker.sock:/var/run/docker.sock -p 8080:8080 amir20/dozzle --remote-host tcp://123.1.1.1:2375 @@ -60,9 +60,9 @@ docker run --volume=/var/run/docker.sock:/var/run/docker.sock -p 8080:8080 amir2 > [!WARNING] > Docker Socket Proxy is not recommended for production use. It is only for private networks. -## Adding labels to hosts +## Adding Labels to Hosts -`--remote-host` supports host labels by appending them to the connection string with `|`. For example, `--remote-host tcp://123.1.1.1:2375|foobar.com` will use foobar.com as the label in the UI. A full example of this using the CLI or compose are: +`--remote-host` supports host labels by appending them to the connection string with `|`. For example, `--remote-host tcp://123.1.1.1:2375|foobar.com` will use foobar.com as the label in the UI. A full example using the CLI or compose: ::: code-group @@ -86,8 +86,8 @@ services: ::: > [!WARNING] -> Dozzle uses the Docker API to gather information about hosts. Each aget needs a unique host ID. They use Docker's system ID or node ID to identify the host. If you are using swarm, then the node ID is used. If you don't see all hosts, then you may have duplicate hosts configured that have the same host ID. To fix this, remove `/var/lib/docker/engine-id` file. See [FAQ](/guide/faq#i-am-seeing-duplicate-hosts-error-in-the-logs-how-do-i-fix-it) for more information. +> Dozzle uses the Docker API to gather information about hosts. Each agent needs a unique host ID. They use Docker's system ID or node ID to identify the host. If you are using swarm, then the node ID is used. If you don't see all hosts, then you may have duplicate hosts configured that have the same host ID. To fix this, remove `/var/lib/docker/engine-id` file. See [FAQ](/guide/faq#i-am-seeing-duplicate-hosts-error-in-the-logs-how-do-i-fix-it) for more information. -## Changing localhost label +## Changing Localhost Label `localhost` is a special connection and uses different configuration than `--remote-host`. Changing the label for localhost can be done using the `--hostname` or `DOZZLE_HOSTNAME` env variable. See [hostname](/guide/hostname) page for examples on how to use this flag. diff --git a/docs/guide/sql-engine.md b/docs/guide/sql-engine.md index f70129f3..48a03398 100644 --- a/docs/guide/sql-engine.md +++ b/docs/guide/sql-engine.md @@ -10,11 +10,11 @@ This feature is currently in beta and is available to all users. If you have any ## Getting Started -To get started with the SQL Engine, you will need to have a dataset that you can query. Only JSON logs can be queried using SQL. Dozzle leveages the power of WebAssembly to run SQL queries in the browser, which means that your data never leaves your machine. +To get started with the SQL Engine, you will need to have a dataset that you can query. Only JSON logs can be queried using SQL. Dozzle leverages the power of WebAssembly to run SQL queries in the browser, which means that your data never leaves your machine. -To start using the SQL Engine, make sure you have JSON logs and naviage to the drop down and choose `SQL Analytics`. There is also a keyboard shortcut `^+⇧+f` or `⌘+⇧+f` to quickly open the SQL Engine. +To start using the SQL Engine, make sure you have JSON logs and navigate to the dropdown and choose `SQL Analytics`. There is also a keyboard shortcut `^+⇧+f` or `⌘+⇧+f` to quickly open the SQL Engine. -## How does it work? +## How Does It Work? The SQL Engine uses WebAssembly to run SQL queries in the browser with DuckDB. When the SQL Engine is first opened, DuckDB WASM is downloaded and initialized in the browser. This could take a while if you are on a slow connection. The SQL Engine then reads _only_ the JSON logs and creates a virtual table in DuckDB. This allows you to run SQL queries against your data in real-time. @@ -52,6 +52,6 @@ SELECT level, COUNT(*) FROM logs GROUP BY level WebAssembly has some limitations that you should be aware of when using the SQL Engine: -- The SQL Engine only supports structured data such as JSON. -- The SQL Engine is limited to running queries in the browser. This means that you cannot run queries that require access to external resources or databases. -- There is a maximum of 4GB of memory that can be used by the SQL Engine. If you run out of memory, you will need to refresh the page to clear the memory. +- The SQL Engine only supports structured data such as JSON +- The SQL Engine is limited to running queries in the browser. This means that you cannot run queries that require access to external resources or databases +- There is a maximum of 4GB of memory that can be used by the SQL Engine. If you run out of memory, you will need to refresh the page to clear the memory diff --git a/docs/guide/supported-env-vars.md b/docs/guide/supported-env-vars.md index 4e365770..0073bc42 100644 --- a/docs/guide/supported-env-vars.md +++ b/docs/guide/supported-env-vars.md @@ -1,5 +1,5 @@ --- -title: Environment variables and subcommands +title: Environment Variables and Subcommands --- # Global Environment Variables @@ -24,8 +24,8 @@ Configurations can be done with flags or environment variables. The table below | `--remote-agent` | `DOZZLE_REMOTE_AGENT` | | | `--timeout` | `DOZZLE_TIMEOUT` | `3s` | -> [!TIP] Repeated Flags -> Some flags like `--remote-host` or `--remote-agent` can be used multiple times. For example, `--remote-agent tcp://167.99.1.1:7007 --remote-agent tcp://167.99.1.2:7007` or comma separated `DOZZLE_REMOTE_AGENT=tcp://167.99.1.1:7007,tcp://167.99.1.2:7007`. +> [!TIP] +> Some flags like `--remote-host` or `--remote-agent` can be used multiple times. For example, `--remote-agent tcp://167.99.1.1:7007 --remote-agent tcp://167.99.1.2:7007` or comma-separated `DOZZLE_REMOTE_AGENT=tcp://167.99.1.1:7007,tcp://167.99.1.2:7007`. ## Generate users.yml @@ -61,6 +61,6 @@ See [agent](/guide/agent) for more information. ## Healthcheck -Dozzle supports healthcheck using `dozzle healthcheck` command. It is not enabled by default as it adds extra CPU usage. To use `healthcheck` you need to configure it. +Dozzle supports healthcheck using `dozzle healthcheck` command. It is not enabled by default as it adds extra CPU usage. To use `healthcheck`, you need to configure it. See [healthcheck](/guide/healthcheck) for more information. diff --git a/docs/guide/swarm-mode.md b/docs/guide/swarm-mode.md index 10c7e6aa..86810c3d 100644 --- a/docs/guide/swarm-mode.md +++ b/docs/guide/swarm-mode.md @@ -4,15 +4,15 @@ title: Swarm Mode # Swarm Mode -Dozzle supports Docker Swarm Mode starting from version 8. When using Swarm Mode, Dozzle will automatically discover services and custom groups. Dozzle does not use Swarm API internally as it is [limited](https://github.com/moby/moby/issues/33183). Dozzle implements its own grouping using swarm labels. Additionally, Dozzle merges stats for containers in a group. This means that you can see logs and stats for all containers in a group in one view. But it does mean each host needs to be setup with Dozzle. +Dozzle supports Docker Swarm Mode starting from version 8. When using Swarm Mode, Dozzle will automatically discover services and custom groups. Dozzle does not use Swarm API internally as it is [limited](https://github.com/moby/moby/issues/33183). Instead, Dozzle implements its own grouping using swarm labels. Additionally, Dozzle merges stats for containers in a group. This means that you can see logs and stats for all containers in a group in one view. However, it does mean each host needs to be set up with Dozzle. -## How does it work? +## How Does It Work? -When deployed in Swarm Mode, Dozzle will create a secured mesh network between all the nodes in the swarm. This network is used to communicate between the different Dozzle instances. The mesh network is created using [mTLS](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls) with a private TLS certificate. This means that all communication between the different Dozzle instances is encrypted and safe to deploy any where. +When deployed in Swarm Mode, Dozzle will create a secured mesh network between all the nodes in the swarm. This network is used to communicate between the different Dozzle instances. The mesh network is created using [mTLS](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls) with a private TLS certificate. This means that all communication between the different Dozzle instances is encrypted and safe to deploy anywhere. Dozzle supports Docker [stacks](https://docs.docker.com/reference/cli/docker/stack/deploy/), [services](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/) and custom groups for joining logs together. `com.docker.stack.namespace` and `com.docker.compose.project` labels are used for grouping containers. For services, Dozzle uses the service name as the group name which is `com.docker.swarm.service.name`. -## How to enable Swarm Mode? +## How to Enable Swarm Mode? To deploy on every node in the swarm, you can use `mode: global`. This will deploy Dozzle on every node in the swarm. Here is an example using Docker Stack: @@ -40,9 +40,9 @@ Note that the `DOZZLE_MODE` environment variable is set to `swarm`. This tells D > [!NOTE] > Due to implementation details, the name for the service must be exactly `dozzle`. This is no longer required starting with version `v8.2`. You can name the service anything you want. The service name is automatically detected by Dozzle using `com.docker.swarm.service.name` label. -## Setting up simple authentication in Swarm Mode +## Setting Up Simple Authentication in Swarm Mode -To setup simple authentication, you can use Docker secrets to store `users.yml` file. Here is an example using Docker Stack: +To set up simple authentication, you can use Docker secrets to store `users.yml` file. Here is an example using Docker Stack: ```yml services: @@ -75,7 +75,7 @@ secrets: In this example, `users.yml` file is stored in a Docker secret. It is the same as the [simple authentication](/guide/authentication#generating-users-yml) example. -## Adding standalone Agents to Swarm Mode +## Adding Standalone Agents to Swarm Mode From version v8.8.x, Dozzle supports adding standalone [Agents](/guide/agent) when running in Swarm Mode. diff --git a/docs/guide/usage-dashboard.md b/docs/guide/usage-dashboard.md deleted file mode 100644 index 9cf2b400..00000000 --- a/docs/guide/usage-dashboard.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Usage Dashboard ---- - -# Usage Dashboard - -This data is based on collected data which is completely anonymous. - -