https://github.com/amerkurev/doku

💽 Doku - Docker disk usage dashboard
https://github.com/amerkurev/doku

dashboard devops disk-space disk-usage docker docker-disk-usage monitoring size-calculation utility

Last synced: 4 days ago
JSON representation

💽 Doku - Docker disk usage dashboard

• Host: GitHub
• URL: https://github.com/amerkurev/doku
• Owner: amerkurev
• License: mit
• Created: 2022-06-13T08:24:02.000Z (almost 3 years ago)
• Default Branch: master
• Last Pushed: 2025-03-11T22:24:48.000Z (about 1 month ago)
• Last Synced: 2025-03-12T22:00:46.033Z (about 1 month ago)
• Topics: dashboard, devops, disk-space, disk-usage, docker, docker-disk-usage, monitoring, size-calculation, utility
• Language: Python
• Homepage: https://docker-disk.space
• Size: 4 MB
• Stars: 331
• Watchers: 2
• Forks: 15
• Open Issues: 10
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md
  • Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

• awesome-docker - Doku - Doku is a simple web-based application that allows you to monitor Docker disk usage. [@amerkurev](https://github.com/amerkurev) (Container Operations / Monitoring)
• awesome-homelab - Doku - Docker disk usage dashboard | (Apps / Monitoring)
• awesome-docker - Doku - Doku is a simple web-based application that allows you to monitor Docker disk usage. [@amerkurev](https://github.com/amerkurev) (Container Operations / Monitoring)
• awesome-docker - Doku - Doku is a simple web-based application that allows you to monitor Docker disk usage. [@amerkurev](https://github.com/amerkurev) (Container Operations / Monitoring)

README

        
# Doku

Doku is a lightweight web application that helps you monitor Docker disk usage through a clean, intuitive interface.



[![Build](https://github.com/amerkurev/doku/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/amerkurev/doku/actions/workflows/ci.yml)

[![Coverage Status](https://coveralls.io/repos/github/amerkurev/doku/badge.svg?branch=master)](https://coveralls.io/github/amerkurev/doku?branch=master)

[![Docker pulls](https://img.shields.io/docker/pulls/amerkurev/doku.svg)](https://hub.docker.com/r/amerkurev/doku)

[![License](https://img.shields.io/badge/license-mit-blue.svg)](https://github.com/amerkurev/doku/blob/master/LICENSE)



## Quick Start

For those eager to get started, here's the fastest way to run Doku:

```bash

docker run -d -v /var/run/docker.sock:/var/run/docker.sock:ro -v /:/hostroot:ro -p 9090:9090 amerkurev/doku

```

Then open http://localhost:9090/ in your browser. That's it!

This command runs Doku with default settings and read-only access to your Docker socket and filesystem. See the sections below for more detailed setup options.

![doku_screenshot](https://raw.githubusercontent.com/amerkurev/doku/master/docs/img/doku.svg)

## Features

Doku monitors disk space used by:

- Images

- Containers

- Volumes

- Builder cache

- Overlay2 storage (typically the largest consumer of disk space)

- Container logs

- Bind mounts

## Getting Doku

Pull the latest release from the Docker Hub:

```bash

docker pull amerkurev/doku:latest

```

## Using Doku

The simplest way to use Doku is to run the Docker container. You'll need to mount two key resources:

1. The Docker Unix socket with `-v /var/run/docker.sock:/var/run/docker.sock:ro`

2. The top-level directory (`/`) of the host machine with `-v /:/hostroot:ro`

The root directory mount is critical for Doku to calculate disk usage of logs, bind mounts, and especially Overlay2 storage. Without this mount, many key features of Doku will not function properly.

```bash

docker run --name doku -d -v /var/run/docker.sock:/var/run/docker.sock:ro -v /:/hostroot:ro -p 9090:9090 amerkurev/doku

```

Important: All host mounts are in read-only (ro) mode. This ensures Doku can only read data and cannot modify or delete any files on your host system. Doku is strictly a monitoring tool and never performs any cleanup or disk space reclamation actions on its own.

For more advanced configurations, you can add SSL certificates, authentication, and environment variables:

```bash

docker run -d --name doku \

    --env-file=.env \

    -v /var/run/docker.sock:/var/run/docker.sock:ro \

    -v /:/hostroot:ro \

    -v ${PWD}/.htpasswd:/.htpasswd \

    -v ${PWD}/.ssl/key.pem:/.ssl/key.pem \

    -v ${PWD}/.ssl/cert.pem:/.ssl/cert.pem \

    -p 9090:9090 \

    amerkurev/doku

```

The `--env-file=.env` option allows you to specify various configuration parameters through environment variables. See the "Configuration Options" section below for details on all available settings.

Doku will be available at http://localhost:9090/. You can change `-p 9090:9090` to any port. For example, if you want to view Doku over port 8080 then you would do `-p 8080:9090`.

## Configuration Options

Doku can be configured using environment variables. You can set these either directly when running the container or through an environment file passed with `--env-file=.env`.

| Environment Variable | Description | Default |

|---------------------|-------------|---------|

| HOST | Interface address to bind the server to | 0.0.0.0 |

| PORT | Web interface port number | 9090 |

| LOG_LEVEL | Logging detail level (debug, info, warning, error, critical) | info |

| SI | Use SI units (base 1000) instead of binary units (base 1024) | true |

| BASIC_HTPASSWD | Path to the htpasswd file for basic authentication | /.htpasswd |

| ROOT_PATH | URL prefix when served behind a proxy (e.g., "/doku") | "" |

| SCAN_INTERVAL | How often to collect basic Docker usage data (in seconds) | 60 |

| SCAN_LOGFILE_INTERVAL | How frequently to check container log sizes (in seconds) | 300 |

| SCAN_BINDMOUNTS_INTERVAL | Time between bind mount scanning operations (in seconds) | 3600 |

| BINDMOUNT_IGNORE_PATTERNS | Paths matching these patterns will be excluded from bind mount scanning (semicolon-separated) (e.g., `/home/*;/tmp/*;*/.git/*`) | "" |

| SCAN_OVERLAY2_INTERVAL | How often to analyze Overlay2 storage (in seconds) | 86400 |

| DISABLE_OVERLAY2_SCAN | Disable Overlay2 storage scanning | false |

| SCAN_INTENSITY | Performance impact level: "aggressive" (highest CPU usage), "normal" (balanced), or "light" (lowest impact) | normal |

| SCAN_USE_DU | Use the faster system `du` command for disk calculations instead of slower built-in methods | true |

| UVICORN_WORKERS | Number of web server worker processes | 1 |

| DEBUG | Enable debug mode | false |

| DOCKER_HOST | Connection string for the Docker daemon | unix:///var/run/docker.sock |

| DOCKER_TLS_VERIFY | Enable TLS verification for Docker daemon connection | false |

| DOCKER_CERT_PATH | Directory containing Docker TLS certificates | null |

| DOCKER_VERSION | Docker API version to use | auto |

| DOCKER_TIMEOUT | Timeout in seconds for Docker API requests | 60 |

| DOCKER_MAX_POOL_SIZE | Maximum number of connections in the Docker API connection pool | 10 |

| DOCKER_USE_SSH_CLIENT | Use SSH for Docker daemon connection instead of HTTP/HTTPS | false |

### Example .env file

Here's an example `.env` file with some commonly adjusted settings:

```ini

PORT=9090 

LOG_LEVEL=info 

SI=true

DOCKER_TIMEOUT=200 

SCAN_INTERVAL=200 

SCAN_INTENSITY=light 

DEBUG=false

```

To use an environment file with Docker, include it when running the container:

```bash

docker run -d --name doku --env-file=.env -v /var/run/docker.sock:/var/run/docker.sock:ro -v /:/hostroot:ro -p 9090:9090 amerkurev/doku

```

This loads all the variables from your `.env` file and applies them to Doku's configuration.

## Basic Authentication

Doku supports HTTP basic authentication to secure access to the web interface. Follow these steps to enable it:

1. Create an htpasswd file with bcrypt-encrypted passwords:

```bash

htpasswd -cbB .htpasswd admin yourpassword

```

Add additional users with:

```bash

htpasswd -bB .htpasswd another_user anotherpassword

```

2. Mount the htpasswd file when running Doku:

```bash

docker run -d --name doku \

    -v /var/run/docker.sock:/var/run/docker.sock:ro \

    -v /:/hostroot:ro \

    -v ${PWD}/.htpasswd:/.htpasswd \

    -p 9090:9090 \

    amerkurev/doku

```

3. If you want to use a custom path for the htpasswd file, specify it with the `BASIC_HTPASSWD` environment variable:

```bash

docker run -d --name doku \

    -v /var/run/docker.sock:/var/run/docker.sock:ro \

    -v /:/hostroot:ro \

    -v ${PWD}/custom/path/.htpasswd:/auth/.htpasswd \

    -e BASIC_HTPASSWD=/auth/.htpasswd \

    -p 9090:9090 \

    amerkurev/doku

```

Authentication will be required for all requests to Doku once enabled.

## Supported Architectures

Doku container images are available for the following platforms:

- linux/amd64

- linux/arm64

The multi-arch images are automatically selected based on your host platform when pulling from Docker Hub.

## License

[MIT](LICENSE)