Skip to content

Commit 88bc232

Browse files
amerkurevamerkurev
authored
New readme (#41)
1 parent 88cb01f commit 88bc232

File tree

4 files changed

+186
-65
lines changed

4 files changed

+186
-65
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@ on:
44
push:
55
branches:
66
- master
7-
- 39-create-a-new-ciyml
87
tags:
98
- '*'
109
paths-ignore:
@@ -68,5 +67,5 @@ jobs:
6867
docker buildx build --push \
6968
--build-arg CI=github --build-arg GIT_SHA=${GITHUB_SHA} --build-arg GIT_TAG=${ref} \
7069
--platform linux/amd64,linux/arm64 \
71-
-t ghcr.io/${USERNAME}/doku:${ref} \
72-
-t ${USERNAME}/doku:${ref} .
70+
-t ghcr.io/${USERNAME}/doku:${ref} -t ghcr.io/${USERNAME}/doku:latest \
71+
-t ${USERNAME}/doku:${ref} -t ${USERNAME}/doku:latest .

‎README.md‎

Lines changed: 142 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,172 @@
11
# Doku
2-
Doku is a simple, lightweight web-based application that allows you to monitor Docker disk usage in a user-friendly manner.
3-
The Doku displays the amount of disk space used by the Docker daemon, splits by images, containers, volumes, and builder cache.
4-
If you're lucky, you'll also see the sizes of log files :)
5-
6-
Doku should work for most. It has been tested with dozen of hosts.
7-
<div>
8-
9-
[![Build](https://github.com/amerkurev/doku/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/amerkurev/doku/actions/workflows/ci.yml)&nbsp;
10-
[![Coverage Status](https://coveralls.io/repos/github/amerkurev/doku/badge.svg?branch=master)](https://coveralls.io/github/amerkurev/doku?branch=master)&nbsp;
11-
[![GoReportCard](https://goreportcard.com/badge/github.com/amerkurev/doku)](https://goreportcard.com/report/github.com/amerkurev/doku)&nbsp;
12-
[![Docker Hub](https://img.shields.io/docker/automated/amerkurev/doku.svg)](https://hub.docker.com/r/amerkurev/doku/tags)&nbsp;
13-
[![Docker pulls](https://img.shields.io/docker/pulls/amerkurev/doku.svg)](https://hub.docker.com/r/amerkurev/doku)&nbsp;
2+
3+
Doku is a lightweight web application that helps you monitor Docker disk usage through a clean, intuitive interface.
4+
5+
<div markdown="1">
6+
7+
[![Build](https://github.com/amerkurev/doku/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/amerkurev/doku/actions/workflows/ci.yml)
8+
[![Coverage Status](https://coveralls.io/repos/github/amerkurev/doku/badge.svg?branch=master)](https://coveralls.io/github/amerkurev/doku?branch=master)
9+
[![Docker pulls](https://img.shields.io/docker/pulls/amerkurev/doku.svg)](https://hub.docker.com/r/amerkurev/doku)
10+
[![License](https://img.shields.io/badge/license-mit-blue.svg)](https://github.com/amerkurev/doku/blob/master/LICENSE)
1411
</div>
1512

16-
![laptop_doku](https://user-images.githubusercontent.com/28217522/235870076-a344527c-874d-41a4-bda9-749efd4ff917.svg)
13+
## Quick Start
14+
15+
For those eager to get started, here's the fastest way to run Doku:
16+
17+
```bash
18+
docker run -d -v /var/run/docker.sock:/var/run/docker.sock:ro -v /:/hostroot:ro -p 9090:9090 amerkurev/doku
19+
```
20+
21+
Then open http://localhost:9090/ in your browser. That's it!
22+
23+
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.
24+
25+
![doku_screenshot](doku.svg)
26+
27+
## Features
28+
29+
Doku monitors disk space used by:
30+
31+
- Images
32+
- Containers
33+
- Volumes
34+
- Builder cache
35+
- Overlay2 storage (typically the largest consumer of disk space)
36+
- Container logs
37+
- Bind mounts
1738

1839
## Getting Doku
1940

20-
Doku is a very small Docker container (6 MB compressed). Pull the latest release from the index:
41+
Pull the latest release from the Docker Hub:
2142

22-
docker pull amerkurev/doku:latest
43+
```bash
44+
docker pull amerkurev/doku:latest
45+
```
2346

2447
## Using Doku
2548

26-
The simplest way to use Doku is to run the Docker container. Mount the Docker Unix socket with `-v` to `/var/run/docker.sock`. Also, you need to mount the top-level directory (`/`) on the host machine in `ro` mode. Otherwise, Doku will not be able to calculate the size of the logs and bind mounts.
49+
The simplest way to use Doku is to run the Docker container. You'll need to mount two key resources:
50+
51+
1. The Docker Unix socket with `-v /var/run/docker.sock:/var/run/docker.sock:ro`
52+
2. The top-level directory (`/`) of the host machine with `-v /:/hostroot:ro`
2753

28-
docker run --name doku -d -v /var/run/docker.sock:/var/run/docker.sock:ro -v /:/hostroot:ro -p 9090:9090 amerkurev/doku
54+
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.
2955

30-
Use following configuration for docker compose:
56+
```bash
57+
docker run --name doku -d -v /var/run/docker.sock:/var/run/docker.sock:ro -v /:/hostroot:ro -p 9090:9090 amerkurev/doku
58+
```
59+
60+
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.
61+
62+
For more advanced configurations, you can add SSL certificates, authentication, and environment variables:
63+
64+
```bash
65+
docker run -d --name doku \
66+
--env-file=.env \
67+
-v /var/run/docker.sock:/var/run/docker.sock:ro \
68+
-v /:/hostroot:ro \
69+
-v $(PWD)/.htpasswd:/.htpasswd \
70+
-v $(PWD)/.ssl/key.pem:/.ssl/key.pem \
71+
-v $(PWD)/.ssl/cert.pem:/.ssl/cert.pem \
72+
-p 9090:9090 \
73+
amerkurev/doku
74+
```
75+
76+
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.
77+
78+
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`.
79+
80+
## Configuration Options
81+
82+
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`.
83+
84+
| Environment Variable | Description | Default |
85+
|---------------------|-------------|---------|
86+
| HOST | Interface address to bind the server to | 0.0.0.0 |
87+
| PORT | Web interface port number | 9090 |
88+
| LOG_LEVEL | Logging detail level (debug, info, warning, error, critical) | info |
89+
| SI | Use SI units (base 1000) instead of binary units (base 1024) | true |
90+
| BASIC_HTPASSWD | Path to the htpasswd file for basic authentication | /.htpasswd |
91+
| SCAN_INTERVAL | How often to collect basic Docker usage data (in seconds) | 60 |
92+
| SCAN_LOGFILE_INTERVAL | How frequently to check container log sizes (in seconds) | 60 |
93+
| SCAN_BINDMOUNTS_INTERVAL | Time between bind mount scanning operations (in seconds) | 3600 |
94+
| SCAN_OVERLAY2_INTERVAL | How often to analyze Overlay2 storage (in seconds) | 86400 |
95+
| SCAN_INTENSITY | Performance impact level: "aggressive" (highest CPU usage), "normal" (balanced), or "light" (lowest impact) | normal |
96+
| SCAN_USE_DU | Use the faster system `du` command for disk calculations instead of slower built-in methods | true |
97+
| UVICORN_WORKERS | Number of web server worker processes | 1 |
98+
| DEBUG | Enable detailed debug output | false |
99+
| DOCKER_HOST | Connection string for the Docker daemon | unix:///var/run/docker.sock |
100+
| DOCKER_TLS_VERIFY | Enable TLS verification for Docker daemon connection | false |
101+
| DOCKER_CERT_PATH | Directory containing Docker TLS certificates | null |
102+
| DOCKER_VERSION | Docker API version to use | auto |
103+
104+
### Example .env file
105+
106+
Here's an example `.env` file with some commonly adjusted settings:
107+
108+
```ini
109+
PORT=9090
110+
LOG_LEVEL=info
111+
SI=true
112+
SCAN_INTERVAL=120
113+
SCAN_INTENSITY=light
114+
DEBUG=false
115+
```
31116

32-
```yaml
33-
version: "3"
34-
services:
35-
doku:
36-
image: amerkurev/doku:v0.0.16
37-
ports:
38-
- 9090:9090
39-
volumes:
40-
- /var/run/docker.sock:/var/run/docker.sock:ro
41-
- /:/hostroot:ro
117+
To use an environment file with Docker, include it when running the container:
118+
119+
```bash
120+
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
42121
```
43122

44-
Doku will be available at [http://localhost:9090/](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`.
123+
This loads all the variables from your `.env` file and applies them to Doku's configuration.
45124

46-
## Basic auth
125+
## Basic Authentication
47126

48-
Doku supports basic auth for all requests. This functionality is disabled by default.
127+
Doku supports HTTP basic authentication to secure access to the web interface. Follow these steps to enable it:
49128

50-
In order to enable basic auth, user should set the typical htpasswd file with `--basic-htpasswd=<file location>` or `env BASIC_HTPASSWD=<file location>`.
129+
1. Create an htpasswd file with bcrypt-encrypted passwords:
130+
```bash
131+
htpasswd -cbB .htpasswd admin yourpassword
132+
```
51133

52-
Doku expects htpasswd file to be crypted with `bcrypt` algorithm in the following format:
134+
Add additional users with:
135+
```bash
136+
htpasswd -bB .htpasswd another_user anotherpassword
137+
```
53138

139+
2. Mount the htpasswd file when running Doku:
140+
```bash
141+
docker run -d --name doku \
142+
-v /var/run/docker.sock:/var/run/docker.sock:ro \
143+
-v /:/hostroot:ro \
144+
-v $(PWD)/.htpasswd:/.htpasswd \
145+
-p 9090:9090 \
146+
amerkurev/doku
54147
```
55-
username1:bcrypt(password1)
56-
username2:bcrypt(password2)
57-
...
148+
149+
3. If you want to use a custom path for the htpasswd file, specify it with the `BASIC_HTPASSWD` environment variable:
150+
```bash
151+
docker run -d --name doku \
152+
-v /var/run/docker.sock:/var/run/docker.sock:ro \
153+
-v /:/hostroot:ro \
154+
-v $(PWD)/custom/path/.htpasswd:/auth/.htpasswd \
155+
-e BASIC_HTPASSWD=/auth/.htpasswd \
156+
-p 9090:9090 \
157+
amerkurev/doku
58158
```
59159

60-
this can be generated with `htpasswd -nbB` command, i.e. `htpasswd -nbB test passwd`
160+
Authentication will be required for all requests to Doku once enabled.
161+
162+
## Supported Architectures
163+
164+
Doku container images are available for the following platforms:
61165

62-
## Supported architectures
63166
- linux/amd64
64-
- linux/arm/v7
65167
- linux/arm64
66168

67-
## Special thanks to
68-
69-
The following great works inspired me:
70-
- Gatus: https://github.com/TwiN/gatus
71-
- Dozzle: https://github.com/amir20/dozzle
72-
- Reproxy: https://github.com/umputun/reproxy
169+
The multi-arch images are automatically selected based on your host platform when pulling from Docker Hub.
73170

74171
## License
75172

‎app/settings.py‎

Lines changed: 39 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,10 @@ class ScanIntensity(str, Enum):
2828

2929
class Settings(BaseSettings):
3030
# general settings
31-
host: str = Field(alias='HOST', default='0.0.0.0')
32-
port: PositiveInt = Field(alias='PORT', default=9090)
31+
host: str = Field(alias='HOST', default='0.0.0.0', description='Host to listen on.')
32+
port: PositiveInt = Field(alias='PORT', default=9090, description='Port to listen on.')
3333
in_docker: bool = Field(alias='IN_DOCKER', default=False)
34-
log_level: LogLevel = Field(alias='LOG_LEVEL', default=LogLevel.INFO)
34+
log_level: LogLevel = Field(alias='LOG_LEVEL', default=LogLevel.INFO, description='Log level.')
3535
github_repo: str = Field(alias='GITHUB_REPO', default='amerkurev/doku')
3636
my_hostname: str = Field(alias='HOSTNAME', default='') # it is set by the container automatically
3737
si: bool = Field(
@@ -48,24 +48,46 @@ class Settings(BaseSettings):
4848
ssl_ciphers: str = Field(alias='SSL_CIPHERS', default='TLSv1')
4949

5050
# scan settings
51-
scan_interval: PositiveInt = Field(alias='SCAN_INTERVAL', default=60) # in seconds
52-
scan_logfile_interval: PositiveInt = Field(alias='SCAN_LOGFILE_INTERVAL', default=60) # in seconds
53-
scan_bindmounts_interval: PositiveInt = Field(alias='SCAN_BINDMOUNTS_INTERVAL', default=60 * 60) # in seconds
54-
scan_overlay2_interval: PositiveInt = Field(alias='SCAN_OVERLAY2_INTERVAL', default=60 * 60 * 24) # in seconds
55-
scan_intensity: ScanIntensity = Field(alias='SCAN_INTENSITY', default=ScanIntensity.NORMAL)
56-
scan_use_du: bool = Field(alias='SCAN_USE_DU', default=True)
57-
scan_use_ncdu: bool = Field(alias='SCAN_USE_NCDU', default=True)
58-
scan_ncdu_interval: PositiveInt = Field(alias='SCAN_NCDU_INTERVAL', default=60 * 60) # in seconds
51+
scan_interval: PositiveInt = Field(
52+
alias='SCAN_INTERVAL', default=60, description='Scan interval in seconds (docker system df).'
53+
)
54+
scan_logfile_interval: PositiveInt = Field(
55+
alias='SCAN_LOGFILE_INTERVAL', default=60, description='Scan interval in seconds (logfiles).'
56+
)
57+
scan_bindmounts_interval: PositiveInt = Field(
58+
alias='SCAN_BINDMOUNTS_INTERVAL', default=60 * 60, description='Scan interval in seconds (bindmounts).'
59+
)
60+
scan_overlay2_interval: PositiveInt = Field(
61+
alias='SCAN_OVERLAY2_INTERVAL', default=60 * 60 * 24, description='Scan interval in seconds (overlay2).'
62+
)
63+
scan_intensity: ScanIntensity = Field(
64+
alias='SCAN_INTENSITY',
65+
default=ScanIntensity.NORMAL,
66+
description='Scan intensity. Aggressive: no sleep, but CPU throttling. Normal: 1ms sleep. Light: 10ms sleep.',
67+
)
68+
scan_use_du: bool = Field(
69+
alias='SCAN_USE_DU',
70+
default=True,
71+
description="Use the `du` command to calculate disk usage. It's not recommended to disable it, as it is faster than programmatic methods.",
72+
)
5973

6074
# uvicorn settings
61-
workers: PositiveInt = Field(alias='UVICORN_WORKERS', default=1)
62-
debug: bool = Field(alias='DEBUG', default=False)
75+
workers: PositiveInt = Field(
76+
alias='UVICORN_WORKERS', default=1, description='Number of worker processes for web server.'
77+
)
78+
debug: bool = Field(alias='DEBUG', default=False, description='Enable debug mode.')
6379

6480
# docker daemon settings
65-
docker_host: str = Field(alias='DOCKER_HOST', default='unix:///var/run/docker.sock')
66-
docker_tls_verify: bool = Field(alias='DOCKER_TLS_VERIFY', default=False)
67-
docker_cert_path: str | None = Field(alias='DOCKER_CERT_PATH', default=None)
68-
docker_version: str = Field(alias='DOCKER_VERSION', default='auto')
81+
docker_host: str = Field(
82+
alias='DOCKER_HOST', default='unix:///var/run/docker.sock', description='Docker daemon host.'
83+
)
84+
docker_tls_verify: bool = Field(
85+
alias='DOCKER_TLS_VERIFY', default=False, description='Verify the Docker daemon TLS certificate.'
86+
)
87+
docker_cert_path: str | None = Field(
88+
alias='DOCKER_CERT_PATH', default=None, description='Path to Docker daemon TLS certificate.'
89+
)
90+
docker_version: str = Field(alias='DOCKER_VERSION', default='auto', description='Docker daemon API version.')
6991
docker_timeout: PositiveInt = Field(alias='DOCKER_TIMEOUT', default=docker.DEFAULT_TIMEOUT_SECONDS)
7092
docker_max_pool_size: PositiveInt = Field(alias='DOCKER_MAX_POOL_SIZE', default=docker.DEFAULT_MAX_POOL_SIZE)
7193
docker_use_ssh_client: bool = Field(alias='DOCKER_USE_SSH_CLIENT', default=False)

‎doku.svg‎

Lines changed: 3 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)