├── rootfs ├── etc │ ├── machine-id │ └── cont-init.d │ │ └── 55-qdirstat.sh └── startapp.sh ├── src └── qdirstat │ ├── use_default_shell.patch │ ├── log_path.patch │ ├── fix_systemfilechecker_include.patch │ ├── disable_trash.patch │ ├── disable_file_manager.patch │ ├── fix_allperms.patch │ └── build.sh ├── .github ├── ISSUE_TEMPLATE │ ├── config.yml │ ├── feature-request.yml │ └── bug-report.yml ├── FUNDING.yml └── workflows │ └── build-image.yml ├── LICENSE ├── Dockerfile ├── DOCKERHUB.md ├── appdefs.yml └── README.md /rootfs/etc/machine-id: -------------------------------------------------------------------------------- 1 | /config/machine-id -------------------------------------------------------------------------------- /src/qdirstat/use_default_shell.patch: -------------------------------------------------------------------------------- 1 | --- a/src/StdCleanup.cpp 2 | +++ b/src/StdCleanup.cpp 3 | @@ -135,7 +135,6 @@ 4 | cleanup->setWorksForDotEntry( true ); 5 | cleanup->setRefreshPolicy( Cleanup::RefreshThis ); 6 | cleanup->setRecurse( true ); 7 | - cleanup->setShell( "/bin/bash" ); 8 | 9 | return cleanup; 10 | } 11 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | blank_issues_enabled: false 2 | contact_links: 3 | - name: Ask a question, discuss 4 | url: https://github.com/jlesage/docker-qdirstat/discussions 5 | about: Get help using this Docker container. 6 | - name: Documentation 7 | url: https://github.com/jlesage/docker-qdirstat#readme 8 | about: Documentation about this Docker container. 9 | -------------------------------------------------------------------------------- /src/qdirstat/log_path.patch: -------------------------------------------------------------------------------- 1 | --- a/src/main.cpp 2 | +++ b/src/main.cpp 3 | @@ -79,7 +79,7 @@ bool commandLineSwitch( const QString & longName, 4 | 5 | int main( int argc, char *argv[] ) 6 | { 7 | - Logger logger( "/tmp/qdirstat-$USER", "qdirstat.log" ); 8 | + Logger logger( "/config/log", "qdirstat.log" ); 9 | logVersion(); 10 | 11 | // Set org/app name for QSettings 12 | -------------------------------------------------------------------------------- /rootfs/etc/cont-init.d/55-qdirstat.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | set -e # Exit immediately if a command exits with a non-zero status. 4 | set -u # Treat unset variables as an error. 5 | 6 | # Make sure mandatory directories exist. 7 | mkdir -p /config/log 8 | 9 | # Generate machine id. 10 | if [ ! -f /config/machine-id ]; then 11 | echo "generating machine-id..." 12 | cat /proc/sys/kernel/random/uuid | tr -d '-' > /config/machine-id 13 | fi 14 | 15 | # vim:ft=sh:ts=4:sw=4:et:sts=4 16 | -------------------------------------------------------------------------------- /rootfs/startapp.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | export HOME=/config 3 | 4 | # Added to avoid the following error message: 5 | # MESA-LOADER: failed to open swrast: Error loading shared library 6 | # /usr/lib/xorg/modules/dri/swrast_dri.so: No such file or directory 7 | # (search paths /usr/lib/xorg/modules/dri, suffix _dri) 8 | # We could instead install `mesa-dri-gallium`, but this increases the image 9 | # size a lot. 10 | export QT_QPA_PLATFORM=xcb 11 | export QT_XCB_GL_INTEGRATION=none 12 | 13 | cd /storage 14 | exec /usr/bin/qdirstat 15 | # vim:ft=sh:ts=4:sw=4:et:sts=4 16 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature-request.yml: -------------------------------------------------------------------------------- 1 | name: Feature request 2 | description: Suggest an idea for this project. 3 | title: "[Feature request] Provide a short description of the feature here" 4 | labels: ["enhancement"] 5 | body: 6 | - type: markdown 7 | attributes: 8 | value: | 9 | Thank you for suggesting an idea to make this project better. 10 | - type: textarea 11 | attributes: 12 | label: Idea 13 | description: | 14 | Please describe the desired behavior, pitch your idea, or suggest improvements. 15 | validations: 16 | required: true 17 | -------------------------------------------------------------------------------- /src/qdirstat/fix_systemfilechecker_include.patch: -------------------------------------------------------------------------------- 1 | This fixes the following compilation error, caused by missing include for `uid_t`. 2 | ``` 3 | SystemFileChecker.cpp:43:25: error: out-of-line definition of 'isSystemUid' does not match any declaration in 'QDirStat::SystemFileChecker' 4 | bool SystemFileChecker::isSystemUid( uid_t uid ) 5 | ^~~~~~~~~~~ 6 | ``` 7 | --- a/src/SystemFileChecker.h 2024-01-14 09:58:46.757911588 -0500 8 | +++ b/src/SystemFileChecker.h 2024-01-14 09:59:01.625941559 -0500 9 | @@ -10,6 +10,7 @@ 10 | #ifndef SystemFileChecker_h 11 | #define SystemFileChecker_h 12 | 13 | +#include // uid_t 14 | 15 | #include 16 | 17 | -------------------------------------------------------------------------------- /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | # These are supported funding model platforms 2 | 3 | github: jlesage 4 | patreon: # Replace with a single Patreon username 5 | open_collective: # Replace with a single Open Collective username 6 | ko_fi: # Replace with a single Ko-fi username 7 | tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel 8 | community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry 9 | liberapay: # Replace with a single Liberapay username 10 | issuehunt: # Replace with a single IssueHunt username 11 | otechie: # Replace with a single Otechie username 12 | custom: ["https://paypal.me/JocelynLeSage", "https://www.tesla.com/referral/jocelyn4590"] 13 | -------------------------------------------------------------------------------- /src/qdirstat/disable_trash.patch: -------------------------------------------------------------------------------- 1 | --- a/src/MainWindow.cpp 2 | +++ b/src/MainWindow.cpp 3 | @@ -307,7 +307,11 @@ 4 | bool pseudoDirSelected = selectedItems.containsPseudoDir(); 5 | bool pkgSelected = selectedItems.containsPkg(); 6 | 7 | +#ifdef ENABLE_TRASH 8 | _ui->actionMoveToTrash->setEnabled( sel && ! pseudoDirSelected && ! pkgSelected && ! reading ); 9 | +#else 10 | + _ui->actionMoveToTrash->setEnabled( false ); 11 | +#endif 12 | _ui->actionRefreshSelected->setEnabled( selSize == 1 && ! sel->isExcluded() && ! sel->isMountPoint() && ! pkgView ); 13 | _ui->actionContinueReadingAtMountPoint->setEnabled( oneDirSelected && sel->isMountPoint() ); 14 | _ui->actionReadExcludedDirectory->setEnabled ( oneDirSelected && sel->isExcluded() ); 15 | -------------------------------------------------------------------------------- /src/qdirstat/disable_file_manager.patch: -------------------------------------------------------------------------------- 1 | --- a/src/StdCleanup.cpp 2 | +++ b/src/StdCleanup.cpp 3 | @@ -47,9 +47,15 @@ Cleanup * StdCleanup::openFileManagerHere( QObject * parent ) 4 | QObject::tr( "Open &File Manager Here" ), 5 | parent ); 6 | CHECK_NEW( cleanup ); 7 | +#ifdef ENABLE_FILE_MANAGER 8 | cleanup->setWorksForDir ( true ); 9 | cleanup->setWorksForFile ( true ); 10 | cleanup->setWorksForDotEntry( true ); 11 | +#else 12 | + cleanup->setWorksForDir ( false ); 13 | + cleanup->setWorksForFile ( false ); 14 | + cleanup->setWorksForDotEntry( false ); 15 | +#endif 16 | cleanup->setRefreshPolicy( Cleanup::NoRefresh ); 17 | cleanup->setIcon( ":/icons/file-manager.png" ); 18 | cleanup->setShortcut( Qt::CTRL + Qt::Key_F ); 19 | -------------------------------------------------------------------------------- /src/qdirstat/fix_allperms.patch: -------------------------------------------------------------------------------- 1 | --- a/src/FileInfo.cpp 2019-07-22 08:46:55.000000000 -0400 2 | +++ b/src/FileInfo.cpp 2020-01-24 21:03:47.505790088 -0500 3 | @@ -31,6 +31,11 @@ 4 | 5 | #define FRAGMENT_SIZE 2048 6 | 7 | +/* for musl */ 8 | +#ifndef ALLPERMS 9 | +#define ALLPERMS (S_ISUID|S_ISGID|S_ISVTX|S_IRWXU|S_IRWXG|S_IRWXO)/* 07777 */ 10 | +#endif 11 | + 12 | using namespace QDirStat; 13 | 14 | 15 | --- a/src/FormatUtil.cpp 2019-07-22 08:46:55.000000000 -0400 16 | +++ b/src/FormatUtil.cpp 2020-01-24 21:03:47.505790088 -0500 17 | @@ -31,6 +31,11 @@ 18 | 19 | #include "FormatUtil.h" 20 | 21 | +/* for musl */ 22 | +#ifndef ALLPERMS 23 | +#define ALLPERMS (S_ISUID|S_ISGID|S_ISVTX|S_IRWXU|S_IRWXG|S_IRWXO)/* 07777 */ 24 | +#endif 25 | + 26 | using namespace QDirStat; 27 | 28 | 29 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 Jocelyn Le Sage 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /src/qdirstat/build.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | set -e # Exit immediately if a command exits with a non-zero status. 4 | set -u # Treat unset variables as an error. 5 | 6 | # Set same default compilation flags as abuild. 7 | export CFLAGS="-Os -fomit-frame-pointer" 8 | export CXXFLAGS="$CFLAGS" 9 | export CPPFLAGS="$CFLAGS" 10 | export LDFLAGS="-Wl,--strip-all -Wl,--as-needed" 11 | 12 | export CC=xx-clang 13 | export CXX=xx-clang++ 14 | 15 | function log { 16 | echo ">>> $*" 17 | } 18 | 19 | QDIRSTAT_URL="$1" 20 | 21 | if [ -z "$QDIRSTAT_URL" ]; then 22 | log "ERROR: QDirStat URL missing." 23 | exit 1 24 | fi 25 | 26 | # 27 | # Install required packages. 28 | # 29 | apk --no-cache add \ 30 | curl \ 31 | clang \ 32 | make \ 33 | patch \ 34 | qtchooser \ 35 | qt5-qtbase-dev \ 36 | 37 | xx-apk --no-cache --no-scripts add \ 38 | musl-dev \ 39 | gcc \ 40 | g++ \ 41 | qt5-qtbase-dev \ 42 | 43 | # 44 | # Download sources. 45 | # 46 | 47 | log "Downloading QDirStat package..." 48 | mkdir /tmp/qdirstat 49 | curl -# -L -f ${QDIRSTAT_URL} | tar xz --strip 1 -C /tmp/qdirstat 50 | 51 | # 52 | # Compile QDirStat. 53 | # 54 | 55 | log "Patching QDirStat..." 56 | patch -d /tmp/qdirstat -p1 < /build/log_path.patch 57 | patch -d /tmp/qdirstat -p1 < /build/use_default_shell.patch 58 | patch -d /tmp/qdirstat -p1 < /build/disable_trash.patch 59 | patch -d /tmp/qdirstat -p1 < /build/disable_file_manager.patch 60 | patch -d /tmp/qdirstat -p1 < /build/fix_allperms.patch 61 | patch -d /tmp/qdirstat -p1 < /build/fix_systemfilechecker_include.patch 62 | 63 | log "Configuring QDirStat..." 64 | sed -i 's/$${CROSS_COMPILE}clang/xx-clang/g' /usr/lib/qt5/mkspecs/common/clang.conf 65 | ( 66 | cd /tmp/qdirstat && \ 67 | qmake -spec linux-clang && \ 68 | cd /tmp/qdirstat/src && \ 69 | qmake src.pro -spec linux-clang 70 | ) 71 | sed -i "s| /usr/lib/libQt5| $(xx-info sysroot)usr/lib/libQt5|g" /tmp/qdirstat/src/Makefile 72 | sed -i "s|LFLAGS = .*|LFLAGS = $LDFLAGS|" /tmp/qdirstat/src/Makefile 73 | 74 | log "Compiling QDirStat..." 75 | make -C /tmp/qdirstat -j$(nproc) 76 | 77 | log "Installing QDirStat..." 78 | make INSTALL_ROOT=/tmp/qdirstat-install -C /tmp/qdirstat install 79 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | # 2 | # qdirstat Dockerfile 3 | # 4 | # https://github.com/jlesage/docker-qdirstat 5 | # 6 | 7 | # Docker image version is provided via build arg. 8 | ARG DOCKER_IMAGE_VERSION= 9 | 10 | # Define software versions. 11 | ARG QDIRSTAT_VERSION=1.9 12 | 13 | # Define software download URLs. 14 | ARG QDIRSTAT_URL=https://github.com/shundhammer/qdirstat/archive/${QDIRSTAT_VERSION}.tar.gz 15 | 16 | # Get Dockerfile cross-compilation helpers. 17 | FROM --platform=$BUILDPLATFORM tonistiigi/xx AS xx 18 | 19 | # Build QDirStat. 20 | FROM --platform=$BUILDPLATFORM alpine:3.16 AS qdirstat 21 | ARG TARGETPLATFORM 22 | ARG QDIRSTAT_URL 23 | COPY --from=xx / / 24 | COPY src/qdirstat /build 25 | RUN /build/build.sh "$QDIRSTAT_URL" 26 | RUN xx-verify /tmp/qdirstat-install/usr/bin/qdirstat 27 | 28 | # Pull base image. 29 | FROM jlesage/baseimage-gui:alpine-3.16-v4.10.5 30 | 31 | ARG QDIRSTAT_VERSION 32 | ARG DOCKER_IMAGE_VERSION 33 | 34 | # Define working directory. 35 | WORKDIR /tmp 36 | 37 | # Install dependencies. 38 | RUN add-pkg \ 39 | qt5-qtbase-x11 \ 40 | adwaita-qt \ 41 | mesa-gl \ 42 | # A font is needed. 43 | font-croscore \ 44 | # Tools used by the app 45 | git \ 46 | make \ 47 | xterm 48 | 49 | # Generate and install favicons. 50 | RUN \ 51 | APP_ICON_URL=https://github.com/jlesage/docker-templates/raw/master/jlesage/images/qdirstat-icon.png && \ 52 | install_app_icon.sh "$APP_ICON_URL" 53 | 54 | # Add files. 55 | COPY rootfs/ / 56 | COPY --from=qdirstat /tmp/qdirstat-install/usr/bin/qdirstat /usr/bin/ 57 | 58 | # Set internal environment variables. 59 | RUN \ 60 | set-cont-env APP_NAME "QDirStat" && \ 61 | set-cont-env APP_VERSION "$QDIRSTAT_VERSION" && \ 62 | set-cont-env DOCKER_IMAGE_VERSION "$DOCKER_IMAGE_VERSION" && \ 63 | true 64 | 65 | # Define mountable directories. 66 | VOLUME ["/storage"] 67 | 68 | # Metadata. 69 | LABEL \ 70 | org.label-schema.name="qdirstat" \ 71 | org.label-schema.description="Docker container for QDirStat" \ 72 | org.label-schema.version="${DOCKER_IMAGE_VERSION:-unknown}" \ 73 | org.label-schema.vcs-url="https://github.com/jlesage/docker-qdirstat" \ 74 | org.label-schema.schema-version="1.0" 75 | -------------------------------------------------------------------------------- /DOCKERHUB.md: -------------------------------------------------------------------------------- 1 | # Docker container for QDirStat 2 | [![Release](https://img.shields.io/github/release/jlesage/docker-qdirstat.svg?logo=github&style=for-the-badge)](https://github.com/jlesage/docker-qdirstat/releases/latest) 3 | [![Docker Image Size](https://img.shields.io/docker/image-size/jlesage/qdirstat/latest?logo=docker&style=for-the-badge)](https://hub.docker.com/r/jlesage/qdirstat/tags) 4 | [![Docker Pulls](https://img.shields.io/docker/pulls/jlesage/qdirstat?label=Pulls&logo=docker&style=for-the-badge)](https://hub.docker.com/r/jlesage/qdirstat) 5 | [![Docker Stars](https://img.shields.io/docker/stars/jlesage/qdirstat?label=Stars&logo=docker&style=for-the-badge)](https://hub.docker.com/r/jlesage/qdirstat) 6 | [![Build Status](https://img.shields.io/github/actions/workflow/status/jlesage/docker-qdirstat/build-image.yml?logo=github&branch=master&style=for-the-badge)](https://github.com/jlesage/docker-qdirstat/actions/workflows/build-image.yml) 7 | [![Source](https://img.shields.io/badge/Source-GitHub-blue?logo=github&style=for-the-badge)](https://github.com/jlesage/docker-qdirstat) 8 | [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg?style=for-the-badge)](https://paypal.me/JocelynLeSage) 9 | 10 | This is a Docker container for [QDirStat](https://github.com/shundhammer/qdirstat). 11 | 12 | The graphical user interface (GUI) of the application can be accessed through a 13 | modern web browser, requiring no installation or configuration on the client 14 | 15 | > This Docker container is entirely unofficial and not made by the creators of QDirStat. 16 | 17 | --- 18 | 19 | [![QDirStat logo](https://images.weserv.nl/?url=raw.githubusercontent.com/jlesage/docker-templates/master/jlesage/images/qdirstat-icon.png&w=110)](https://github.com/shundhammer/qdirstat)[![QDirStat](https://images.placeholders.dev/?width=256&height=110&fontFamily=monospace&fontWeight=400&fontSize=52&text=QDirStat&bgColor=rgba(0,0,0,0.0)&textColor=rgba(121,121,121,1))](https://github.com/shundhammer/qdirstat) 20 | 21 | QDirStat is a graphical application to show where your disk space has gone and 22 | to help you to clean it up. 23 | 24 | --- 25 | 26 | ## Quick Start 27 | 28 | **NOTE**: 29 | The Docker command provided in this quick start is an example, and parameters 30 | should be adjusted to suit your needs. 31 | 32 | Launch the QDirStat docker container with the following command: 33 | ```shell 34 | docker run -d \ 35 | --name=qdirstat \ 36 | -p 5800:5800 \ 37 | -v /docker/appdata/qdirstat:/config:rw \ 38 | -v /home/user:/storage:ro \ 39 | jlesage/qdirstat 40 | ``` 41 | 42 | Where: 43 | 44 | - `/docker/appdata/qdirstat`: Stores the application's configuration, state, logs, and any files requiring persistency. 45 | - `/home/user`: Contains files from the host that need to be accessible to the application. 46 | 47 | Access the QDirStat GUI by browsing to `http://your-host-ip:5800`. 48 | Files from the host appear under the `/storage` folder in the container. 49 | 50 | ## Documentation 51 | 52 | Full documentation is available at https://github.com/jlesage/docker-qdirstat. 53 | 54 | ## Support or Contact 55 | 56 | Having troubles with the container or have questions? Please 57 | [create a new issue](https://github.com/jlesage/docker-qdirstat/issues). 58 | 59 | For other Dockerized applications, visit https://jlesage.github.io/docker-apps. 60 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug-report.yml: -------------------------------------------------------------------------------- 1 | name: Bug report 2 | description: File a bug report. 3 | title: "[Bug] Provide a short description of the bug here" 4 | labels: ["bug"] 5 | body: 6 | - type: markdown 7 | attributes: 8 | value: | 9 | Thanks for taking the time to fill out this bug report! 10 | - type: textarea 11 | attributes: 12 | label: Current Behavior 13 | description: A concise description of what you're experiencing. 14 | validations: 15 | required: true 16 | - type: textarea 17 | attributes: 18 | label: Expected Behavior 19 | description: A concise description of what you expected to happen. 20 | validations: 21 | required: false 22 | - type: textarea 23 | attributes: 24 | label: Steps To Reproduce 25 | description: Steps to reproduce the behavior. 26 | validations: 27 | required: false 28 | - type: textarea 29 | attributes: 30 | label: Environment 31 | description: | 32 | Provide details about the host running the container. 33 | Examples: 34 | - Operating system (e.g. Ubuntu, Windows, TrueNAS, openmediavault, unRAID, etc). 35 | - Version of the operating system. 36 | - CPU architecture (x86-64, arm, arm64, etc). 37 | - Model of the device, if applicable (e.g. Raspberry Pi 4B, Synology DS418, QNAP TS-364, etc). 38 | - The Docker version (output of `docker version`). 39 | - Anything else specific to your environment. Examples: 40 | - Network share (NFS, CIFS) mapped to the container. 41 | - Docker running in LXC container. 42 | - etc. 43 | - If applicable, how the UI provided by the container is access: 44 | - Browser (Chrome, Firefox, Edge, etc). 45 | - Version of the browser. 46 | - OS of the browser. 47 | - Is the container accessed through a reverse proxy. 48 | - etc. 49 | value: | 50 | - OS: 51 | - OS version: 52 | - CPU: 53 | - Docker version: 54 | - Device model: 55 | - Browser/OS: 56 | validations: 57 | required: false 58 | - type: textarea 59 | attributes: 60 | label: Container creation 61 | description: | 62 | How did you create the container ? 63 | Examples: 64 | - The `docker run` command used. 65 | - The compose file used. 66 | - Screenshots of the management tool UI (e.g. Portainer, unRAID, etc) showing container settings. 67 | validations: 68 | required: true 69 | - type: textarea 70 | attributes: 71 | label: Container log 72 | description: Please copy/paste the output of `docker logs `. 73 | render: text 74 | validations: 75 | required: true 76 | - type: textarea 77 | attributes: 78 | label: Container inspect 79 | description: | 80 | If the container is running, please provide the output of `docker inspect `. 81 | **Attention**: If you defined passwords, secrets or any sensitive information via environment variables, make sure to remove them from the output. 82 | render: text 83 | validations: 84 | required: false 85 | - type: textarea 86 | attributes: 87 | label: Anything else? 88 | description: | 89 | Anything that will give more context about the issue you are encountering. 90 | 91 | Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in. 92 | validations: 93 | required: false 94 | -------------------------------------------------------------------------------- /.github/workflows/build-image.yml: -------------------------------------------------------------------------------- 1 | name: Docker image CI/CD 2 | 3 | concurrency: 4 | group: ${{ github.workflow }}-${{ github.ref }} 5 | cancel-in-progress: true 6 | 7 | env: 8 | DOCKER_IMAGE_NAME: jlesage/qdirstat 9 | PLATFORMS: linux/amd64,linux/386,linux/arm/v6,linux/arm/v7,linux/arm64/v8 10 | 11 | on: 12 | push: 13 | branches: '*' 14 | tags: 15 | - v[0-9][0-9].[0-9][0-9].[0-9]+ 16 | - v[0-9][0-9].[0-9][0-9].[0-9]+-pre.[0-9]+ 17 | pull_request: 18 | 19 | jobs: 20 | build: 21 | name: Build image 22 | runs-on: ubuntu-22.04 23 | 24 | steps: 25 | - name: Free disk space 26 | uses: jlumbroso/free-disk-space@main 27 | with: 28 | tool-cache: true 29 | android: true 30 | dotnet: true 31 | haskell: true 32 | large-packages: true 33 | docker-images: true 34 | swap-storage: false 35 | 36 | - name: Prepare 37 | id: prep 38 | run: | 39 | # Determine the Docker container version. 40 | VERSION=unknown 41 | if [[ $GITHUB_REF =~ refs/tags/* ]]; then 42 | # Git tag pushed: use tag as the version. 43 | VERSION=${GITHUB_REF#refs/tags/} 44 | elif [[ $GITHUB_REF =~ refs/heads/* ]]; then 45 | # Git commit pushed: use the commit SHA as the version. 46 | VERSION=${GITHUB_SHA::8} 47 | elif [[ $GITHUB_REF =~ refs/pull/* ]]; then 48 | # Pull request: use PR number as the version. 49 | VERSION=pr-${{ github.event.number }} 50 | else 51 | echo "::error::Unexpected GITHUB_REF: $GITHUB_REF" 52 | exit 1 53 | fi 54 | # Determine the version to put in container label. 55 | LABEL_VERSION=${VERSION} 56 | if [[ $GITHUB_REF =~ refs/tags/* ]]; then 57 | # Do not include the starting 'v' of the version. 58 | LABEL_VERSION=${VERSION:1} 59 | fi 60 | # Determine the Docker container tags. 61 | TAGS="${{ env.DOCKER_IMAGE_NAME }}:${VERSION}" 62 | if [[ $GITHUB_REF =~ refs/tags/* ]]; then 63 | TAGS="$TAGS,${{ env.DOCKER_IMAGE_NAME }}:latest" 64 | fi 65 | TAGS="$TAGS,$(echo $TAGS | tr ',' '\n' | sed 's|^|ghcr.io/|' | tr '\n' ',')" 66 | # Determine the release type. 67 | if [[ $GITHUB_REF =~ refs/tags/* ]]; then 68 | IS_RELEASE=yes 69 | if [[ $GITHUB_REF =~ -pre\.[0-9]+ ]]; then 70 | RELEASE_TYPE="pre" 71 | else 72 | RELEASE_TYPE="standard" 73 | fi 74 | else 75 | IS_RELEASE=no 76 | RELEASE_TYPE="n/a" 77 | fi 78 | # Print results. 79 | echo "::group::Results" 80 | echo "Github reference: $GITHUB_REF" 81 | echo "Release: $IS_RELEASE" 82 | echo "Release type: $RELEASE_TYPE" 83 | echo "Docker container version: $VERSION" 84 | echo "Docker container version label: $LABEL_VERSION" 85 | echo "Docker container tag(s): $TAGS" 86 | echo "::endgroup::" 87 | # Export outputs. 88 | echo "is_release=${IS_RELEASE}" >> $GITHUB_OUTPUT 89 | echo "release_type=${RELEASE_TYPE}" >> $GITHUB_OUTPUT 90 | echo "version=${VERSION}" >> $GITHUB_OUTPUT 91 | echo "label_version=${LABEL_VERSION}" >> $GITHUB_OUTPUT 92 | echo "tags=${TAGS}" >> $GITHUB_OUTPUT 93 | #echo "build_date=$(date -u +'%Y-%m-%dT%H:%M:%SZ')" >> $GITHUB_OUTPUT 94 | 95 | - name: Setup QEMU 96 | uses: docker/setup-qemu-action@v3 97 | with: 98 | platforms: arm,arm64,ppc64le,mips64,s390x 99 | 100 | - name: Setup Docker Buildx 101 | uses: docker/setup-buildx-action@v3 102 | 103 | - name: Login to DockerHub 104 | if: ${{ steps.prep.outputs.is_release == 'yes' }} 105 | uses: docker/login-action@v3 106 | with: 107 | username: ${{ secrets.DOCKERHUB_USERNAME }} 108 | password: ${{ secrets.DOCKERHUB_PASSWORD }} 109 | 110 | - name: Login to GitHub Container Registry 111 | if: ${{ steps.prep.outputs.is_release == 'yes' }} 112 | uses: docker/login-action@v3 113 | with: 114 | registry: ghcr.io 115 | username: ${{ github.repository_owner }} 116 | password: ${{ secrets.GITHUB_TOKEN }} 117 | 118 | - name: Build and push 119 | uses: docker/build-push-action@v6 120 | with: 121 | push: ${{ steps.prep.outputs.is_release == 'yes' }} 122 | provenance: false 123 | platforms: ${{ env.PLATFORMS }} 124 | tags: ${{ steps.prep.outputs.tags }} 125 | build-args: | 126 | DOCKER_IMAGE_VERSION=${{ steps.prep.outputs.label_version }} 127 | cache-from: type=gha,scope=${{ env.DOCKER_IMAGE_NAME }} 128 | cache-to: type=gha,mode=max,scope=${{ env.DOCKER_IMAGE_NAME }} 129 | 130 | - name: Inspect 131 | if: ${{ steps.prep.outputs.is_release == 'yes' }} 132 | run: | 133 | docker buildx imagetools inspect ${{ env.DOCKER_IMAGE_NAME }}:${{ steps.prep.outputs.version }} 134 | 135 | - name: Checkout 136 | uses: actions/checkout@v4 137 | if: ${{ steps.prep.outputs.release_type == 'standard' }} 138 | 139 | - name: Dockerhub description 140 | if: ${{ steps.prep.outputs.release_type == 'standard' }} 141 | uses: peter-evans/dockerhub-description@v4 142 | with: 143 | username: ${{ secrets.DOCKERHUB_USERNAME }} 144 | password: ${{ secrets.DOCKERHUB_PASSWORD }} 145 | repository: ${{ env.DOCKER_IMAGE_NAME }} 146 | readme-filepath: DOCKERHUB.md 147 | 148 | notification: 149 | name: Notification 150 | needs: [ build ] 151 | runs-on: ubuntu-22.04 152 | if: ${{ always() && github.event_name != 'pull_request' }} 153 | 154 | steps: 155 | - name: Pushover notification 156 | uses: desiderati/github-action-pushover@v1 157 | with: 158 | job-status: ${{ needs.build.result }} 159 | pushover-api-token: ${{ secrets.PUSHOVER_API_TOKEN }} 160 | pushover-user-key: ${{ secrets.PUSHOVER_USER_KEY }} 161 | -------------------------------------------------------------------------------- /appdefs.yml: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | # 4 | # Definitions for MediaInfo docker container. 5 | # 6 | # This file is used as data source to generate README.md and unRAID template files 7 | # from Jinja2 templates. 8 | # 9 | 10 | app: 11 | id: 15 12 | name: qdirstat 13 | friendly_name: QDirStat 14 | gui_type: x11 15 | base_os: alpine 16 | project: 17 | description: |- 18 | QDirStat is a graphical application to show where your disk space has gone and 19 | to help you to clean it up. 20 | url: https://github.com/shundhammer/qdirstat 21 | unraid: 22 | support_url: https://forums.unraid.net/topic/72787-support-qdirstat/ 23 | category: "Tools:" 24 | documentation: 25 | sections: 26 | - title: Cleaning Functionalities 27 | level: 2 28 | content: |- 29 | In order to use the cleaning functionalities provided by {{ app.friendly_name }}, 30 | the `/storage` directory must be mapped with the read/write permissions. 31 | 32 | For example, the `docker run` command would include the following parameter: 33 | ``` 34 | -v /home/user:/storage:rw 35 | ``` 36 | changelog: 37 | - version: 25.12.3 38 | date: 2025-12-22 39 | changes: 40 | - 'Updated baseimage to version 4.10.5, which brings the following changes:' 41 | - '2:Fixed key combinations in some Linux applications broken by the Command key remapping.' 42 | - version: 25.12.2 43 | date: 2025-12-20 44 | changes: 45 | - 'Updated baseimage to version 4.10.4, which brings the following changes:' 46 | - '2:Web audio is now automatically re-enabled upon first user interaction.' 47 | - '2:Improved robustness of GPU devices detection.' 48 | - '2:Command key on Mac devices has been remapped to better match Linux application interactions.' 49 | - version: 25.12.1 50 | date: 2025-12-08 51 | changes: 52 | - 'Updated baseimage to version 4.10.3, which brings the following changes:' 53 | - '2:Added hardware acceleration support for the X server.' 54 | - '2:Added seamless clipboard synchronization for Chromium-based browsers.' 55 | - '2:Added web notification service to forward desktop notifications to the browser.' 56 | - '2:Added the ability to restrict web and VNC connections from localhost only.' 57 | - '2:Added web server support for TLS 1.3.' 58 | - '2:Removed web server support of static Diffie-Hellman parameters file (no longer needed in modern TLS configurations and ECDHE).' 59 | - version: 25.07.2 60 | date: 2025-07-28 61 | changes: 62 | - 'Updated baseimage to version 4.9.0.' 63 | - version: 25.07.1 64 | date: 2025-07-05 65 | changes: 66 | - 'Updated baseimage to version 4.8.2, which brings the following changes:' 67 | - '2:Fixed automatic reconnect of the web interface when web authentication is enabled.' 68 | - '2:Fixed some resources that could not be accessed behind a reverse proxy based on URL path.' 69 | - version: 25.06.2 70 | date: 2025-06-25 71 | changes: 72 | - 'Updated baseimage to version 4.8.1, which brings the following changes:' 73 | - '2:Fixed crash with some binaries on systems using old kernel.' 74 | - version: 25.06.1 75 | date: 2025-06-23 76 | changes: 77 | - 'Updated baseimage to version 4.8.0, which brings the following changes:' 78 | - '2:Added automatic reconnect support of the web interface.' 79 | - '2:Added web file manager.' 80 | - '2:Updated noVNC to version 1.6.0.' 81 | - '2:Updated web UI components (Bootstrap).' 82 | - '2:Do not ask VNC password when accessing the web interface and web authentication is enabled.' 83 | - version: 25.02.1 84 | date: 2025-02-09 85 | changes: 86 | - 'Updated baseimage to version 4.7.1, which brings the following changes (since last used version):' 87 | - '2:Added environment variable that allows configuring the web authentication token lifetime.' 88 | - '2:Fixed compatibility issues that were introduced with support of GTK4 applications.' 89 | - '2:Increased the default service ready timeout from 5 seconds to 10 seconds and allow runtime adjustment via environment variable.' 90 | - '2:Rebuild against latest distro images to get security fixes.' 91 | - version: 24.12.1 92 | date: 2024-12-07 93 | changes: 94 | - 'Updated baseimage to version 4.6.7, which brings the following changes:' 95 | - '2:Fixed web audio feature with URL path-based reverse proxy.' 96 | - '2:Fixed TLS secure connection method for VNC that was preventing web access.' 97 | - '2:Fixed CJK font installation.' 98 | - '2:Rebuild against latest distro images to get security fixes.' 99 | - version: 24.09.1 100 | date: 2024-09-29 101 | changes: 102 | - 'Updated baseimage to version 4.6.4, which brings the following changes:' 103 | - '2:Fixed web authentication feature with URL path-based reverse proxy.' 104 | - '2:Rebuild against latest distro images to get security fixes.' 105 | - version: 24.07.2 106 | date: 2024-07-05 107 | changes: 108 | - 'Fixed issue where QDirStat would not start under some architectures.' 109 | - version: 24.07.1 110 | date: 2024-07-03 111 | changes: 112 | - 'Updated baseimage to version 4.6.3, which brings the following changes:' 113 | - '2:Audio support through web browser.' 114 | - '2:Web authentication support.' 115 | - '2:Better support of GTK4 applications.' 116 | - '2:Updated noVNC to version 1.5.0.' 117 | - '2:Updated web UI components (Bootstrap, Font Awesome).' 118 | - '2:When connecting, the control bar is now temporarily shown only once.' 119 | - '2:During package mirror setup, make sure to keep permissions of copied files.' 120 | - version: 24.01.1 121 | date: 2024-01-14 122 | changes: 123 | - 'Updated QDirStat to version 1.9.' 124 | - 'Updated baseimage to version 4.5.3, which brings the following changes:' 125 | - '2:Disabled fullscreen support when page is loaded into an iFrame.' 126 | - '2:Rebuilt against latest distro images to get security fixes.' 127 | - version: 23.11.2 128 | date: 2023-11-19 129 | changes: 130 | - 'Updated baseimage to version 4.5.2, which brings the following changes:' 131 | - '2:Fixed issue that would cause the helper that takes ownership of a directory to fail when using a very high user or group ID.' 132 | - version: 23.11.1 133 | date: 2023-11-10 134 | changes: 135 | - 'Updated baseimage to version 4.5.1, which brings the following changes:' 136 | - '2:Mirror for packages installation can be set via the `PACKAGES_MIRROR` environment variable.' 137 | - '2:Improved the way the `take-ownership` script is working.' 138 | - '2:Readiness and minimum running time checks should not be done for a service defined with an interval.' 139 | - '2:Raise an error when a synched service fails to start.' 140 | - '2:Minimum running time check of a service was using an incorrect way to verify if process is still alive.' 141 | - '2:Fixed installation of CJK font.' 142 | - version: 23.06.1 143 | date: 2023-06-08 144 | changes: 145 | - 'Updated baseimage to version 4.4.2, which brings the following changes:' 146 | - '2:Rebuilt against latest distro images to get security fixes.' 147 | - '2:Updated X server to version 1.20.14.' 148 | - version: 23.04.1 149 | date: 2023-04-30 150 | changes: 151 | - 'Updated baseimage to version 4.4.1, which brings the following changes:' 152 | - '2:Updated TigerVNC to version 1.13.1.' 153 | - version: 23.03.1 154 | date: 2023-03-05 155 | changes: 156 | - 'Updated baseimage to version 4.4.0, which brings the following changes:' 157 | - '2:Updated components providing access to application''s UI over web.' 158 | - '2:Improved web UI usage with touch devices.' 159 | - '2:Fixed issue with initialization of Linux users and groups when the `GROUP_ID` is also part of `SUP_GROUP_IDS`.' 160 | - '2:Limit the maximum number of opened files on system having a very large, unlimited value. This prevents unnecessary waste of CPU resources and time for applications trying to close all possible file descriptors.' 161 | - version: 23.02.2 162 | date: 2023-02-08 163 | changes: 164 | - 'Updated baseimage to version 4.3.4, which brings the following changes:' 165 | - '2:Fixed error message from openbox about missing Fontconfig cache directory.' 166 | - 'Do not use the OCI Docker image format yet to keep better compatibility (e.g with older docker clients).' 167 | - version: 23.02.1 168 | date: 2023-02-04 169 | changes: 170 | - 'Updated baseimage to version 4.3.3, which brings robustness related enhancements.' 171 | - version: 23.01.1 172 | date: 2023-01-04 173 | changes: 174 | - 'Update of the baseimage to version 4.3.1 brings the following changes:' 175 | - '2:Control menu can be moved to the right side of the screen.' 176 | - '2:Automatic focus of the clipboard text box when opening the control menu.' 177 | - '2:Automatic close of the control menu when clicking into the application.' 178 | - '2:Rotation of the internal web server log files.' 179 | - version: 22.12.2 180 | date: 2022-12-11 181 | changes: 182 | - 'Implemented workaround for issue seen with Synology devices where container would not start after an image update. The problem is caused by Synology explicitly setting all environment variables and keeping values from the old version.' 183 | - version: 22.12.1 184 | date: 2022-12-08 185 | changes: 186 | - 'Fixed QDirStat not starting on ARM devices due to missing library.' 187 | - 'Updated baseimage to version `4.2.1`, which brings multiple internal enhancements.' 188 | - version: 22.10.1 189 | date: 2022-10-24 190 | changes: 191 | - 'Versioning scheme of the Docker image changed to `YY.MM.SEQUENCE`.' 192 | - 'Update of the baseimage to version 4.1.1 brings the following new features:' 193 | - '2:Multi-arch image support.' 194 | - '2:Support for dark mode.' 195 | - '2:Support for remote window resize.' 196 | - '2:Updated the web UI with a new, simplified and less intrusive look.' 197 | - version: 1.5.0 198 | date: 2022-06-30 199 | changes: 200 | - 'Updated QDirStat to version 1.8.1' 201 | - 'Now using baseimage version 3.5.8, based on Alpine Linux 3.14, which brings the following changes:' 202 | - '2:Updated installed packages to get latest security fixes.' 203 | - version: 1.4.0 204 | date: 2021-08-28 205 | changes: 206 | - 'Updated QDirStat to version 1.8.' 207 | - version: 1.3.1 208 | date: 2021-04-13 209 | changes: 210 | - 'Now using baseimage version 3.5.7, which brings the following change:' 211 | - '2:Updated installed packages to get latest security fixes.' 212 | - version: 1.3.0 213 | date: 2021-04-06 214 | changes: 215 | - 'Updated QDirStat to version 1.7.1.' 216 | - version: 1.2.0 217 | date: 2020-08-05 218 | changes: 219 | - 'Upgraded QDirStat to version 1.7.' 220 | - 'Now using baseimage v3.5.6, based on Alpine 12, which brings the following changes:' 221 | - '2:Upgraded glibc to version 2.31 on Alpine Linux images with glibc integrated.' 222 | - '2:Updated installed packages to get latest security fixes.' 223 | - '2:Adjusted the log monitor target for recent versions of YAD.' 224 | - version: 1.1.1 225 | date: 2020-02-15 226 | changes: 227 | - 'Upgraded QDirStat to version 1.6.1.' 228 | - version: 1.1.0 229 | date: 2020-01-24 230 | changes: 231 | - 'Upgraded QDirStat to version 1.6.' 232 | - 'Now using baseimage v3.5.3, which brings the following changes:' 233 | - '2:Updated installed packages to get latest security fixes.' 234 | - '2:Make sure the tzdata is installed.' 235 | - version: 1.0.2 236 | date: 2019-04-24 237 | changes: 238 | - 'Now using baseimage v3.5.2, which brings the following changes:' 239 | - '2:Updated installed packages to get latest security fixes.' 240 | - '2:Fixed issue where the container could have a zombie process.' 241 | - '2:Fixed issue where the password would not be submitted when pressing the enter key in the password modal.' 242 | - '2:Use relative path for favicon ressources to be more friendly with reverse proxy senarios.' 243 | - version: 1.0.1 244 | date: 2018-09-18 245 | changes: 246 | - 'Now using baseimage v3.5.1, which brings the following changes:' 247 | - '2:Updated installed packages to get latest security fixes.' 248 | - version: 1.0.0 249 | date: 2018-07-12 250 | changes: 251 | - 'Initial release.' 252 | 253 | container: 254 | storage_permissions: ro 255 | 256 | # Environment variables. 257 | environment_variables: [] 258 | 259 | # Volumes 260 | volumes: [] 261 | 262 | # Network ports 263 | ports: [] 264 | 265 | # Devices 266 | devices: [] 267 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Docker container for QDirStat 2 | [![Release](https://img.shields.io/github/release/jlesage/docker-qdirstat.svg?logo=github&style=for-the-badge)](https://github.com/jlesage/docker-qdirstat/releases/latest) 3 | [![Docker Image Size](https://img.shields.io/docker/image-size/jlesage/qdirstat/latest?logo=docker&style=for-the-badge)](https://hub.docker.com/r/jlesage/qdirstat/tags) 4 | [![Docker Pulls](https://img.shields.io/docker/pulls/jlesage/qdirstat?label=Pulls&logo=docker&style=for-the-badge)](https://hub.docker.com/r/jlesage/qdirstat) 5 | [![Docker Stars](https://img.shields.io/docker/stars/jlesage/qdirstat?label=Stars&logo=docker&style=for-the-badge)](https://hub.docker.com/r/jlesage/qdirstat) 6 | [![Build Status](https://img.shields.io/github/actions/workflow/status/jlesage/docker-qdirstat/build-image.yml?logo=github&branch=master&style=for-the-badge)](https://github.com/jlesage/docker-qdirstat/actions/workflows/build-image.yml) 7 | [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg?style=for-the-badge)](https://paypal.me/JocelynLeSage) 8 | 9 | This project provides a Docker container for [QDirStat](https://github.com/shundhammer/qdirstat). 10 | 11 | The graphical user interface (GUI) of the application can be accessed through a 12 | modern web browser, requiring no installation or configuration on the client 13 | side, or via any VNC client. 14 | 15 | > [!NOTE] 16 | > This Docker container is entirely unofficial and not made by the creators of QDirStat. 17 | 18 | --- 19 | 20 | [![QDirStat logo](https://images.weserv.nl/?url=raw.githubusercontent.com/jlesage/docker-templates/master/jlesage/images/qdirstat-icon.png&w=110)](https://github.com/shundhammer/qdirstat)[![QDirStat](https://images.placeholders.dev/?width=256&height=110&fontFamily=monospace&fontWeight=400&fontSize=52&text=QDirStat&bgColor=rgba(0,0,0,0.0)&textColor=rgba(121,121,121,1))](https://github.com/shundhammer/qdirstat) 21 | 22 | QDirStat is a graphical application to show where your disk space has gone and 23 | to help you to clean it up. 24 | 25 | --- 26 | 27 | ## Table of Contents 28 | 29 | * [Quick Start](#quick-start) 30 | * [Usage](#usage) 31 | * [Environment Variables](#environment-variables) 32 | * [Deployment Considerations](#deployment-considerations) 33 | * [Data Volumes](#data-volumes) 34 | * [Ports](#ports) 35 | * [Changing Parameters of a Running Container](#changing-parameters-of-a-running-container) 36 | * [Docker Compose File](#docker-compose-file) 37 | * [Docker Image Versioning and Tags](#docker-image-versioning-and-tags) 38 | * [Docker Image Update](#docker-image-update) 39 | * [Synology](#synology) 40 | * [unRAID](#unraid) 41 | * [User/Group IDs](#usergroup-ids) 42 | * [Accessing the GUI](#accessing-the-gui) 43 | * [Security](#security) 44 | * [SSVNC](#ssvnc) 45 | * [Certificates](#certificates) 46 | * [VNC Password](#vnc-password) 47 | * [Web Authentication](#web-authentication) 48 | * [Configuring Users Credentials](#configuring-users-credentials) 49 | * [Reverse Proxy](#reverse-proxy) 50 | * [Routing Based on Hostname](#routing-based-on-hostname) 51 | * [Routing Based on URL Path](#routing-based-on-url-path) 52 | * [Web Control Panel](#web-control-panel) 53 | * [Automatic Clipboard Sync](#automatic-clipboard-sync) 54 | * [Web Audio](#web-audio) 55 | * [Web File Manager](#web-file-manager) 56 | * [Web Notifications](#web-notifications) 57 | * [GPU Acceleration Support](#gpu-acceleration-support) 58 | * [Shell Access](#shell-access) 59 | * [Cleaning Functionalities](#cleaning-functionalities) 60 | * [Support or Contact](#support-or-contact) 61 | 62 | ## Quick Start 63 | 64 | > [!IMPORTANT] 65 | > The Docker command provided in this quick start is an example, and parameters 66 | > should be adjusted to suit your needs. 67 | 68 | Launch the QDirStat docker container with the following command: 69 | 70 | ```shell 71 | docker run -d \ 72 | --name=qdirstat \ 73 | -p 5800:5800 \ 74 | -v /docker/appdata/qdirstat:/config:rw \ 75 | -v /home/user:/storage:ro \ 76 | jlesage/qdirstat 77 | ``` 78 | 79 | Where: 80 | 81 | - `/docker/appdata/qdirstat`: Stores the application's configuration, state, logs, and any files requiring persistency. 82 | - `/home/user`: Contains files from the host that need to be accessible to the application. 83 | 84 | Access the QDirStat GUI by browsing to `http://your-host-ip:5800`. 85 | Files from the host appear under the `/storage` folder in the container. 86 | 87 | ## Usage 88 | 89 | ```shell 90 | docker run [-d] \ 91 | --name=qdirstat \ 92 | [-e =]... \ 93 | [-v :[:PERMISSIONS]]... \ 94 | [-p :]... \ 95 | jlesage/qdirstat 96 | ``` 97 | 98 | | Parameter | Description | 99 | |-----------|-------------| 100 | | -d | Runs the container in the background. If not set, the container runs in the foreground. | 101 | | -e | Passes an environment variable to the container. See [Environment Variables](#environment-variables) for details. | 102 | | -v | Sets a volume mapping to share a folder or file between the host and the container. See [Data Volumes](#data-volumes) for details. | 103 | | -p | Sets a network port mapping to expose an internal container port to the host). See [Ports](#ports) for details. | 104 | 105 | ### Environment Variables 106 | 107 | To customize the container's behavior, you can pass environment variables using 108 | the `-e` parameter in the format `=`. 109 | 110 | | Variable | Description | Default | 111 | |----------------|----------------------------------------------|---------| 112 | |`USER_ID`| ID of the user the application runs as. See [User/Group IDs](#usergroup-ids) for details. | `1000` | 113 | |`GROUP_ID`| ID of the group the application runs as. See [User/Group IDs](#usergroup-ids) for details. | `1000` | 114 | |`SUP_GROUP_IDS`| Comma-separated list of supplementary group IDs for the application. | (no value) | 115 | |`UMASK`| Mask controlling permissions for newly created files and folders, specified in octal notation. By default, `0022` ensures files and folders are readable by all but writable only by the owner. See the umask calculator at http://wintelguy.com/umask-calc.pl. | `0022` | 116 | |`LANG`| Sets the [locale](https://en.wikipedia.org/wiki/Locale_(computer_software)), defining the application's language, if supported. Format is `language[_territory][.codeset]`, where language is an [ISO 639 language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes), territory is an [ISO 3166 country code](https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes), and codeset is a character set, like `UTF-8`. For example, Australian English using UTF-8 is `en_AU.UTF-8`. | `en_US.UTF-8` | 117 | |`TZ`| [TimeZone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) used by the container. The timezone can also be set by mapping `/etc/localtime` between the host and the container. | `Etc/UTC` | 118 | |`KEEP_APP_RUNNING`| When set to `1`, the application is automatically restarted if it crashes or terminates. | `0` | 119 | |`APP_NICENESS`| Priority at which the application runs. A niceness value of -20 is the highest, 19 is the lowest and 0 the default. **NOTE**: A negative niceness (priority increase) requires additional permissions. The container must be run with the Docker option `--cap-add=SYS_NICE`. | `0` | 120 | |`INSTALL_PACKAGES`| Space-separated list of packages to install during container startup. List of available packages can be found at https://pkgs.alpinelinux.org. | (no value) | 121 | |`PACKAGES_MIRROR`| Mirror of the repository to use when installing packages. List of mirrors is available at https://mirrors.alpinelinux.org. | (no value) | 122 | |`CONTAINER_DEBUG`| When set to `1`, enables debug logging. | `0` | 123 | |`DISPLAY_WIDTH`| Width (in pixels) of the application's window. | `1920` | 124 | |`DISPLAY_HEIGHT`| Height (in pixels) of the application's window. | `1080` | 125 | |`DARK_MODE`| When set to `1`, enables dark mode for the application. See Dark Mode](#dark-mode) for details. | `0` | 126 | |`WEB_AUDIO`| When set to `1`, enables audio support, allowing audio produced by the application to play through the browser. See [Web Audio](#web-audio) for details. | `0` | 127 | |`WEB_FILE_MANAGER`| When set to `1`, enables the web file manager, allowing interaction with files inside the container through the web browser, supporting operations like renaming, deleting, uploading, and downloading. See [Web File Manager](#web-file-manager) for details. | `0` | 128 | |`WEB_FILE_MANAGER_ALLOWED_PATHS`| Comma-separated list of paths within the container that the file manager can access. By default, the container's entire filesystem is not accessible, and this variable specifies allowed paths. If set to `AUTO`, commonly used folders and those mapped to the container are automatically allowed. The value `ALL` allows access to all paths (no restrictions). See [Web File Manager](#web-file-manager) for details. | `AUTO` | 129 | |`WEB_FILE_MANAGER_DENIED_PATHS`| Comma-separated list of paths within the container that the file manager cannot access. A denied path takes precedence over an allowed path. See [Web File Manager](#web-file-manager) for details. | (no value) | 130 | |`WEB_NOTIFICATION`| When set to `1`, enables the web notification service, allowing the browser to display desktop notifications from the application. Requires the container to be configured with secure web access (HTTPS). See [Web Notifications](#web-notifications) for details. | `0` | 131 | |`WEB_AUTHENTICATION`| When set to `1`, protects the application's GUI with a login page when accessed via a web browser. Access is granted only with valid credentials. Requires the container to be configured with secure web access (HTTPS). See [Web Authentication](#web-authentication) for details. | `0` | 132 | |`WEB_AUTHENTICATION_TOKEN_VALIDITY_TIME`| Lifetime of a token, in hours. A token is assigned to the user after successful login. As long as the token is valid, the user can access the application's GUI without logging in again. Once the token expires, the login page is displayed again. | `24` | 133 | |`WEB_AUTHENTICATION_USERNAME`| Optional username for web authentication. Provides a quick and easy way to configure credentials for a single user. For more secure configuration or multiple users, see the [Web Authentication](#web-authentication) section. | (no value) | 134 | |`WEB_AUTHENTICATION_PASSWORD`| Optional password for web authentication. Provides a quick and easy way to configure credentials for a single user. For more secure configuration or multiple users, see the [Web Authentication](#web-authentication) section. | (no value) | 135 | |`SECURE_CONNECTION`| When set to `1`, uses an encrypted connection to access the application's GUI (via web browser or VNC client). See [Security](#security) for details. | `0` | 136 | |`SECURE_CONNECTION_VNC_METHOD`| Method used for encrypted VNC connections. Possible values are `SSL` or `TLS`. See [Security](#security) for details. | `SSL` | 137 | |`SECURE_CONNECTION_CERTS_CHECK_INTERVAL`| Interval, in seconds, at which the system checks if web or VNC certificates have changed. When a change is detected, affected services are automatically restarted. A value of `0` disables the check. | `60` | 138 | |`WEB_LOCALHOST_ONLY`| When set to `1`, allows web connections only from localhost (127.0.0.1 and ::1). | `0` | 139 | |`VNC_LOCALHOST_ONLY`| When set to `1`, allows VNC connections only from localhost (127.0.0.1 and ::1). | `0` | 140 | |`WEB_LISTENING_PORT`| Port used by the web server to serve the application's GUI. This port is internal to the container and typically does not need to be changed. By default, a container uses the default bridge network, requiring each internal port to be mapped to an external port (using the `-p` or `--publish` argument). If another network type is used, changing this port may prevent conflicts with other services/containers. **NOTE**: A value of `-1` disables HTTP/HTTPS access to the application's GUI. | `5800` | 141 | |`VNC_LISTENING_PORT`| Port used by the VNC server to serve the application's GUI. This port is internal to the container and typically does not need to be changed. By default, a container uses the default bridge network, requiring each internal port to be mapped to an external port (using the `-p` or `--publish` argument). If another network type is used, changing this port may prevent conflicts with other services/containers. **NOTE**: A value of `-1` disables VNC access to the application's GUI. | `5900` | 142 | |`VNC_PASSWORD`| Password required to connect to the application's GUI. See the [VNC Password](#vnc-password) section for details. | (no value) | 143 | |`ENABLE_CJK_FONT`| When set to `1`, installs the open-source font `WenQuanYi Zen Hei`, supporting a wide range of Chinese/Japanese/Korean characters. | `0` | 144 | 145 | #### Deployment Considerations 146 | 147 | Many tools used to manage Docker containers extract environment variables 148 | defined by the Docker image to create or deploy the container. 149 | 150 | For example, this behavior is seen in: 151 | - The Docker application on Synology NAS 152 | - The Container Station on QNAP NAS 153 | - Portainer 154 | - etc. 155 | 156 | While this is useful for users to adjust environment variable values to suit 157 | their needs, keeping all of them can be confusing and even risky. 158 | 159 | A good practice is to set or retain only the variables necessary for the 160 | container to function as desired in your setup. If a variable is left at its 161 | default value, it can be removed. Keep in mind that all environment variables 162 | are optional; none are required for the container to start. 163 | 164 | Removing unneeded environment variables offers several benefits: 165 | 166 | - Prevents retaining variables no longer used by the container. Over time, 167 | with image updates, some variables may become obsolete. 168 | - Allows the Docker image to update or fix default values. With image updates, 169 | default values may change to address issues or support new features. 170 | - Avoids changes to variables that could disrupt the container's 171 | functionality. Some undocumented variables, like `PATH` or `ENV`, are 172 | required but not meant to be modified by users, yet container management 173 | tools may expose them. 174 | - Addresses a bug in Container Station on QNAP and the Docker application on 175 | Synology, where variables without values may not be allowed. This behavior 176 | is incorrect, as variables without values are valid. Removing unneeded 177 | variables prevents deployment issues on these devices. 178 | 179 | ### Data Volumes 180 | 181 | The following table describes the data volumes used by the container. Volume 182 | mappings are set using the `-v` parameter with a value in the format 183 | `:[:PERMISSIONS]`. 184 | 185 | | Container path | Permissions | Description | 186 | |-----------------|-------------|-------------| 187 | |`/config`| rw | Stores the application's configuration, state, logs, and any files requiring persistency. | 188 | |`/storage`| ro | Contains files from the host that need to be accessible to the application. | 189 | 190 | ### Ports 191 | 192 | The following table lists the ports used by the container. 193 | 194 | When using the default bridge network, ports can be mapped to the host using the 195 | `-p` parameter with value in the format `:`. The 196 | internal container port may not be changeable, but you can use any port on the 197 | host side. 198 | 199 | See the Docker [Docker Container Networking](https://docs.docker.com/config/containers/container-networking) 200 | documentation for details. 201 | 202 | | Port | Protocol | Mapping to Host | Description | 203 | |------|----------|-----------------|-------------| 204 | | 5800 | TCP | Optional | Port to access the application's GUI via the web interface. Mapping to the host is optional if web access is not needed. For non-default bridge networks, the port can be changed with the `WEB_LISTENING_PORT` environment variable. | 205 | | 5900 | TCP | Optional | Port to access the application's GUI via the VNC protocol. Mapping to the host is optional if VNC access is not needed. For non-default bridge networks, the port can be changed with the `VNC_LISTENING_PORT` environment variable. | 206 | 207 | ### Changing Parameters of a Running Container 208 | 209 | Environment variables, volume mappings, and port mappings are specified when 210 | creating the container. To modify these parameters for an existing container, 211 | follow these steps: 212 | 213 | 1. Stop the container (if it is running): 214 | ```shell 215 | docker stop qdirstat 216 | ``` 217 | 218 | 2. Remove the container: 219 | ```shell 220 | docker rm qdirstat 221 | ``` 222 | 223 | 3. Recreate and start the container using the `docker run` command, adjusting 224 | parameters as needed. 225 | 226 | > [!NOTE] 227 | > Since all application data is saved under the `/config` container folder, 228 | > destroying and recreating the container does not result in data loss, and the 229 | > application resumes with the same state, provided the `/config` folder 230 | > mapping remains unchanged. 231 | 232 | ### Docker Compose File 233 | 234 | Below is an example `docker-compose.yml` file for use with 235 | [Docker Compose](https://docs.docker.com/compose/overview/). 236 | 237 | Adjust the configuration to suit your needs. Only mandatory settings are 238 | included in this example. 239 | 240 | ```yaml 241 | version: '3' 242 | services: 243 | qdirstat: 244 | image: jlesage/qdirstat 245 | ports: 246 | - "5800:5800" 247 | volumes: 248 | - "/docker/appdata/qdirstat:/config:rw" 249 | - "/home/user:/storage:ro" 250 | ``` 251 | 252 | ## Docker Image Versioning and Tags 253 | 254 | Each release of a Docker image is versioned, and each version as its own image 255 | tag. Before October 2022, the versioning scheme followed 256 | [semantic versioning](https://semver.org). 257 | 258 | Since then, the versioning scheme has shifted to 259 | [calendar versioning](https://calver.org) with the format `YY.MM.SEQUENCE`, 260 | where: 261 | - `YY` is the zero-padded year (relative to year 2000). 262 | - `MM` is the zero-padded month. 263 | - `SEQUENCE` is the incremental release number within the month (first release 264 | is 1, second is 2, etc). 265 | 266 | View all available tags on [Docker Hub] or check the [Releases] page for version 267 | details. 268 | 269 | [Releases]: https://github.com/jlesage/docker-qdirstat/releases 270 | [Docker Hub]: https://hub.docker.com/r/jlesage/qdirstat/tags 271 | 272 | ## Docker Image Update 273 | 274 | The Docker image is regularly updated to incorporate new features, fix issues, 275 | or integrate newer versions of the containerized application. Several methods 276 | can be used to update the Docker image. 277 | 278 | If your system provides a built-in method for updating containers, this should 279 | be your primary approach. 280 | 281 | Alternatively, you can use [Watchtower], a container-based solution for 282 | automating Docker image updates. Watchtower seamlessly handles updates when a 283 | new image is available. 284 | 285 | To manually update the Docker image, follow these steps: 286 | 287 | 1. Fetch the latest image: 288 | ```shell 289 | docker pull jlesage/qdirstat 290 | ``` 291 | 292 | 2. Stop the container: 293 | ```shell 294 | docker stop qdirstat 295 | ``` 296 | 297 | 3. Remove the container: 298 | ```shell 299 | docker rm qdirstat 300 | ``` 301 | 302 | 4. Recreate and start the container using the `docker run` command, with the 303 | same parameters used during initial deployment. 304 | 305 | [Watchtower]: https://github.com/containrrr/watchtower 306 | 307 | ### Synology 308 | 309 | For Synology NAS users, follow these steps to update a container image: 310 | 311 | 1. Open the *Docker* application. 312 | 2. Click *Registry* in the left pane. 313 | 3. In the search bar, type the name of the container (`jlesage/qdirstat`). 314 | 4. Select the image, click *Download*, and choose the `latest` tag. 315 | 5. Wait for the download to complete. A notification will appear once done. 316 | 6. Click *Container* in the left pane. 317 | 7. Select your QDirStat container. 318 | 8. Stop it by clicking *Action* -> *Stop*. 319 | 9. Clear the container by clicking *Action* -> *Reset* (or *Action* -> 320 | *Clear* if you don't have the latest *Docker* application). This removes 321 | the container while keeping its configuration. 322 | 10. Start the container again by clicking *Action* -> *Start*. **NOTE**: The 323 | container may temporarily disappear from the list while it is recreated. 324 | 325 | ### unRAID 326 | 327 | For unRAID users, update a container image with these steps: 328 | 329 | 1. Select the *Docker* tab. 330 | 2. Click the *Check for Updates* button at the bottom of the page. 331 | 3. Click the *apply update* link of the container to be updated. 332 | 333 | ## User/Group IDs 334 | 335 | When mapping data volumes (using the `-v` flag of the `docker run` command), 336 | permission issues may arise between the host and the container. Files and 337 | folders in a data volume are owned by a user, which may differ from the user 338 | running the application. Depending on permissions, this could prevent the 339 | container from accessing the shared volume. 340 | 341 | To avoid this, specify the user the application should run as using the 342 | `USER_ID` and `GROUP_ID` environment variables. 343 | 344 | To find the appropriate IDs, run the following command on the host for the user 345 | owning the data volume: 346 | 347 | ```shell 348 | id 349 | ``` 350 | 351 | This produces output like: 352 | 353 | ``` 354 | uid=1000(myuser) gid=1000(myuser) groups=1000(myuser),4(adm),24(cdrom),27(sudo),46(plugdev),113(lpadmin) 355 | ``` 356 | 357 | Use the `uid` (user ID) and `gid` (group ID) values to configure the container. 358 | 359 | ## Accessing the GUI 360 | 361 | Assuming the container's ports are mapped to the same host's ports, access the 362 | application's GUI as follows: 363 | 364 | - Via a web browser: 365 | 366 | ```text 367 | http://:5800 368 | ``` 369 | 370 | - Via any VNC client: 371 | 372 | ```text 373 | :5900 374 | ``` 375 | 376 | ## Security 377 | 378 | By default, access to the application's GUI uses an unencrypted connection (HTTP 379 | or VNC). 380 | 381 | A secure connection can be enabled via the `SECURE_CONNECTION` environment 382 | variable. See the [Environment Variables](#environment-variables) section for 383 | details on configuring environment variables. 384 | 385 | When enabled, the GUI is accessed over HTTPS when using a browser, with all HTTP 386 | accesses redirected to HTTPS. 387 | 388 | For VNC clients, the connection can be secured using on of two methods, 389 | configured via the `SECURE_CONNECTION_VNC_METHOD` environment variable: 390 | 391 | - `SSL`: An SSL tunnel is used to transport the VNC connection. Few VNC 392 | clients supports this method; [SSVNC] is one that does. 393 | - `TLS`: A VNC security type negotiated during the VNC handshake. It uses TLS 394 | to establish a secure connection. Clients may optionally validate the 395 | server’s certificate. Valid certificates must be provided for this 396 | validation to succeed. See [Certificates](#certificates) for details. 397 | [TigerVNC] is a client that supports TLS encryption. 398 | 399 | [TigerVNC]: https://tigervnc.org 400 | 401 | ### SSVNC 402 | 403 | [SSVNC] is a VNC viewer that adds encryption to VNC connections by using an 404 | SSL tunnel to transport the VNC traffic. 405 | 406 | While the Linux version of [SSVNC] works well, the Windows version has issues. 407 | At the time of writing, the latest version `1.0.30` fails with the error: 408 | 409 | ```text 410 | ReadExact: Socket error while reading 411 | ``` 412 | 413 | For convenience, an unofficial, working version is provided here: 414 | 415 | https://github.com/jlesage/docker-baseimage-gui/raw/master/tools/ssvnc_windows_only-1.0.30-r1.zip 416 | 417 | This version upgrades the bundled `stunnel` to version `5.49`, resolving the 418 | connection issues. 419 | 420 | [SSVNC]: http://www.karlrunge.com/x11vnc/ssvnc.html 421 | 422 | ### Certificates 423 | 424 | The following certificate files are required by the container. If missing, 425 | self-signed certificates are generated and used. All files are PEM-encoded x509 426 | certificates. 427 | 428 | | Container Path | Purpose | Content | 429 | |---------------------------------|----------------------------|---------| 430 | |`/config/certs/vnc-server.pem` |VNC connection encryption. |VNC server's private key and certificate, bundled with any root and intermediate certificates.| 431 | |`/config/certs/web-privkey.pem` |HTTPS connection encryption.|Web server's private key.| 432 | |`/config/certs/web-fullchain.pem`|HTTPS connection encryption.|Web server's certificate, bundled with any root and intermediate certificates.| 433 | 434 | > [!TIP] 435 | > To avoid certificate validity warnings or errors in browsers or VNC clients, 436 | > provide your own valid certificates. 437 | 438 | > [!NOTE] 439 | > Certificate files are monitored, and relevant services are restarted when 440 | > changes are detected. 441 | 442 | ### VNC Password 443 | 444 | To restrict access to your application, set a password using one of two methods: 445 | - Via the `VNC_PASSWORD` environment variable. 446 | - Via a `.vncpass_clear` file at the root of the `/config` volume, containing 447 | the password in clear text. During container startup, the content is 448 | obfuscated and moved to `.vncpass`. 449 | 450 | The security of the VNC password depends on: 451 | - The communication channel (encrypted or unencrypted). 452 | - The security of host access. 453 | 454 | When using a VNC password, configure the container with secure web access 455 | (HTTPS) to prevent sending the password in clear text over an unencrypted 456 | channel. 457 | 458 | Unauthorized users with sufficient host privileges can retrieve the password by: 459 | 460 | - Viewing the `VNC_PASSWORD` environment variable via `docker inspect`. By 461 | default, the `docker` command requires root access, but it can be configured 462 | to allow users in a specific group. 463 | - Decrypting the `/config/.vncpass` file, which requires root or `USER_ID` 464 | permissions. 465 | 466 | > [!CAUTION] 467 | > VNC password is limited to 8 characters. This limitation comes from the Remote 468 | > Framebuffer Protocol [RFC](https://tools.ietf.org/html/rfc6143) (see section 469 | > [7.2.2](https://tools.ietf.org/html/rfc6143#section-7.2.2)). 470 | 471 | ### Web Authentication 472 | 473 | Access to the application's GUI via a web browser can be protected with a login 474 | page. When enabled, users must provide valid credentials to gain access. 475 | 476 | Enable web authentication by setting the `WEB_AUTHENTICATION` environment 477 | variable to `1`. See the [Environment Variables](#environment-variables) section 478 | for details on configuring environment variables. 479 | 480 | > [!IMPORTANT] 481 | > Web authentication requires the container to be configured with secure web 482 | > access (HTTPS). See [Security](#security) for details. 483 | 484 | #### Configuring Users Credentials 485 | 486 | User credentials can be configured in two ways: 487 | 488 | 1. Via container environment variables. 489 | 2. Via a password database. 490 | 491 | Container environment variables provide a quick way to configure a single user. 492 | Set the username and password using: 493 | - `WEB_AUTHENTICATION_USERNAME` 494 | - `WEB_AUTHENTICATION_PASSWORD` 495 | 496 | See the [Environment Variables](#environment-variables) section for details on 497 | configuring environment variables. 498 | 499 | For a more secure method or to configure multiple users, use a password database 500 | at `/config/webauth-htpasswd` within the container. This file uses the Apache 501 | HTTP server's htpasswd format, storing bcrypt-hashed passwords. 502 | 503 | Manage users with the `webauth-user` tool: 504 | - Add a user: `docker exec -ti webauth-user add ` 505 | - Update a user: `docker exec -ti webauth-user update ` 506 | - Remove a user: `docker exec webauth-user del ` 507 | - List users: `docker exec webauth-user list` 508 | 509 | ## Reverse Proxy 510 | 511 | The following sections provide NGINX configurations for setting up a reverse 512 | proxy to this container. 513 | 514 | A reverse proxy server can route HTTP requests based on the hostname or URL 515 | path. 516 | 517 | ### Routing Based on Hostname 518 | 519 | In this scenario, each hostname is routed to a different application or 520 | container. 521 | 522 | For example, if the reverse proxy server runs on the same machine as this 523 | container, it would proxy all HTTP requests for `qdirstat.domain.tld` to 524 | the container at `127.0.0.1:5800`. 525 | 526 | Here are the relevant configuration elements to add to the NGINX configuration: 527 | 528 | ```nginx 529 | map $http_upgrade $connection_upgrade { 530 | default upgrade; 531 | '' close; 532 | } 533 | 534 | upstream docker-qdirstat { 535 | # If the reverse proxy server is not running on the same machine as the 536 | # Docker container, use the IP of the Docker host here. 537 | # Make sure to adjust the port according to how port 5800 of the 538 | # container has been mapped on the host. 539 | server 127.0.0.1:5800; 540 | } 541 | 542 | server { 543 | [...] 544 | 545 | server_name qdirstat.domain.tld; 546 | 547 | location / { 548 | proxy_pass http://docker-qdirstat; 549 | } 550 | 551 | location /websockify { 552 | proxy_pass http://docker-qdirstat; 553 | proxy_http_version 1.1; 554 | proxy_set_header Upgrade $http_upgrade; 555 | proxy_set_header Connection $connection_upgrade; 556 | proxy_read_timeout 86400; 557 | } 558 | } 559 | 560 | ``` 561 | 562 | ### Routing Based on URL Path 563 | 564 | In this scenario, the same hostname is used, but different URL paths route to 565 | different applications or containers. For example, if the reverse proxy server 566 | runs on the same machine as this container, it would proxy all HTTP requests for 567 | `server.domain.tld/filebot` to the container at `127.0.0.1:5800`. 568 | 569 | Here are the relevant configuration elements to add to the NGINX configuration: 570 | 571 | ```nginx 572 | map $http_upgrade $connection_upgrade { 573 | default upgrade; 574 | '' close; 575 | } 576 | 577 | upstream docker-qdirstat { 578 | # If the reverse proxy server is not running on the same machine as the 579 | # Docker container, use the IP of the Docker host here. 580 | # Make sure to adjust the port according to how port 5800 of the 581 | # container has been mapped on the host. 582 | server 127.0.0.1:5800; 583 | } 584 | 585 | server { 586 | [...] 587 | 588 | location = /qdirstat {return 301 $scheme://$http_host/qdirstat/;} 589 | location /qdirstat/ { 590 | proxy_pass http://docker-qdirstat/; 591 | # Uncomment the following line if your Nginx server runs on a port that 592 | # differs from the one seen by external clients. 593 | #port_in_redirect off; 594 | location ~ ^/qdirstat/(websockify(-.*)?) { 595 | proxy_pass http://docker-qdirstat/$1; 596 | proxy_http_version 1.1; 597 | proxy_set_header Upgrade $http_upgrade; 598 | proxy_set_header Connection $connection_upgrade; 599 | proxy_read_timeout 86400; 600 | } 601 | } 602 | } 603 | 604 | ``` 605 | 606 | ## Web Control Panel 607 | 608 | The control panel is available whenever the application GUI is accessed through 609 | a web browser. Click the small three-dots tab on the left edge of the browser 610 | window to open it. 611 | 612 | ![Web Control Panel](https://images.weserv.nl/?url=raw.githubusercontent.com/jlesage/docker-templates/master/jlesage/images/control-panel.png&w=500) 613 | 614 | | Control | Action / Purpose | 615 | |---------|------------------| 616 | | **X** icon | Closes the control panel. | 617 | | **Logout** icon | Logs out from the web interface. Visible only when [web authentication](#web-authentication) is enabled. | 618 | | **Keyboard** icon | Toggle the on-screen keyboard. Visible only on touch devices. | 619 | | **Fullscreen** icon | Toggle fullscreen mode for the browser window. | 620 | | **Hand** icon| Allows dragging/moving the application window. Visible only when **Scaling Mode** is *None* and **Clip to Window** is enabled. 621 | | **Folder** icon | Opens the intgegrated file browser. Visible only when the [file manager](#web-file-manager) is enabled. | 622 | | **Clipboard** text box| Mirrors the application’s clipboard. Any text typed or pasted here is sent to the application, and text copied inside the application automatically appears here. Hidden when [automatic clipboard synchronization](#automatic-clipboard-sync) is active. | 623 | | **Clear** button | Clears the clipboard. Hidden when [automatic clipboard synchronization](#automatic-clipboard-sync) is active. | 624 | | **Audio** icon | Mutes or unmutes audio streaming from the container. Visible only when [audio support](#web-audio) is enabled. | 625 | | **Volume** slider| Controls the playback volume of the audio streaming from the container. Visible only when [audio support](#web-audio) is enabled. | 626 | | **Clip to Window** toggle | Only applies when **Scaling Mode** is *None*. When disabled, scrollbars appear if the application window is larger than the browser window. When enabled, no scrollbars are shown and the hand icon is used to pan. | 627 | | **Scaling Mode** dropdown | Controls how the application window is scaled to fit the browser. **None** – no scaling, the application window keeps its original size. **Local Scaling** – the image is scaled in the browser (application window size unchanged). **Remote Scaling** – the application window inside the container is automatically resized to match the browser window size. | 628 | | **Quality** slider | Adjusts image quality. Moving the slider left reduces bandwidth at the cost of visual quality. | 629 | | **Compression** slider | Adjusts compression level applied to screen updates. Moving the slider right increases compression, which lowers bandwidth but raises CPU usage. | 630 | | **Logging** dropdown | Sets the verbosity level of the web interface logs shown in the browser console. | 631 | | **Application version** label | Displays the version of QDirStat integrated into Docker image. | 632 | | **Docker image** version label | Displays the version of the Docker image currently running. | 633 | 634 | ## Automatic Clipboard Sync 635 | 636 | When the container is accessed through a web browser, automatic clipboard 637 | synchronization enables seamless sharing of clipboard contents between the host 638 | system and the application running inside the container. This makes it possible 639 | to copy and paste text or data directly between the two environments without 640 | manual transfer steps. 641 | 642 | This functionality is not available when using VNC clients and is supported only 643 | in browsers based on the Chromium engine, such as Google Chrome and Microsoft 644 | Edge. 645 | 646 | Clipboard synchronization operates transparently once permission has been 647 | granted by the browser. Depending on browser implementation, a prompt may appear 648 | the first time clipboard access is requested. 649 | 650 | > [!IMPORTANT] 651 | > Web browsers only allow access to the clipboard in secure contexts (HTTPS). 652 | > This means the container must be configured with secure web access. See 653 | > [Security](#security) for details. 654 | 655 | > [!TIP] 656 | > If automatic clipboard synchronization is not available, text can still be 657 | > copied and pasted using the clipboard of the 658 | > [control panel](#web-control-panel), which provides manual clipboard access 659 | > between the host and the container. 660 | 661 | ## Web Audio 662 | 663 | The container supports streaming audio from the application, played through the 664 | user's web browser. Audio is not supported for VNC clients. 665 | 666 | Audio is streamed with the following specification: 667 | 668 | * Raw PCM format 669 | * 2 channels 670 | * 16-bit sample depth 671 | * 44.1kHz sample rate 672 | 673 | Enable web audio by setting `WEB_AUDIO` to `1`. See the 674 | [Environment Variables](#environment-variables) section for details on 675 | configuring environment variables. 676 | 677 | Control of the audio stream (mute, unmute and volume) is done via the 678 | [control panel](#web-control-panel). 679 | 680 | ## Web File Manager 681 | 682 | The container includes a simple file manager for interacting with container 683 | files through a web browser, supporting operations like renaming, deleting, 684 | uploading, and downloading. 685 | 686 | Enable the file manager by setting `WEB_FILE_MANAGER` to `1`. See the 687 | [Environment Variables](#environment-variables) section for details on 688 | configuring environment variables. 689 | 690 | Open the file manager by clicking the folder icon of the 691 | [control panel](#web-control-panel) 692 | 693 | By default, the container's entire filesystem is not accessible. The 694 | `WEB_FILE_MANAGER_ALLOWED_PATHS` environment variable is a comma-separated list 695 | that specifies which paths within the container are allowed to be accessed. When 696 | set to `AUTO` (the default), it automatically includes commonly used folders and 697 | any folders mapped to the container. 698 | 699 | The `WEB_FILE_MANAGER_DENIED_PATHS` environment variable defines which paths are 700 | explicitly denied access by the file manager. A denied path takes precedence 701 | over an allowed one. 702 | 703 | ## Web Notifications 704 | 705 | The container includes support for notifications sent through the web browser. 706 | Any desktop notification generated by QDirStat is forwarded to the 707 | browser, which then displays it as a native notification on the user's system. 708 | 709 | Enable the web notification service by setting `WEB_NOTIFICATION` to `1`. See 710 | the [Environment Variables](#environment-variables) section for details on 711 | configuring environment variables. 712 | 713 | > [!IMPORTANT] 714 | > Web browsers only allow notifications in secure contexts (HTTPS). This means 715 | > the container must be configured with secure web access. See 716 | > [Security](#security) for details. 717 | 718 | ## GPU Acceleration Support 719 | 720 | This container supports hardware-accelerated rendering of the application's 721 | graphical user interface. When enabled, the X server running inside the 722 | container can use the host GPU, providing improved rendering performance and 723 | full hardware acceleration for OpenGL via the GLX extension. 724 | 725 | This feature requires open-source kernel drivers on the host system, such as 726 | `amdgpu` for AMD GPUs, `i915` for Intel GPUs, or `nouveau` for NVIDIA GPUs, to 727 | support the Direct Rendering Infrastructure (DRI3) and Generic Buffer Management 728 | (GBM). Proprietary drivers, such as NVIDIA's, are not supported. 729 | 730 | To enable GPU acceleration, the host must have compatible open-source kernel 731 | drivers installed, and the GPU device `/dev/dri` must be exposed to the 732 | container. For example, this is done by adding the `--device /dev/dri` 733 | argument to the `docker run` command. 734 | ## Shell Access 735 | 736 | To access the shell of a running container, execute the following command: 737 | 738 | ```shell 739 | docker exec -ti CONTAINER sh 740 | ``` 741 | 742 | Where `CONTAINER` is the ID or the name of the container used during its 743 | creation. 744 | 745 | ## Cleaning Functionalities 746 | 747 | In order to use the cleaning functionalities provided by QDirStat, 748 | the `/storage` directory must be mapped with the read/write permissions. 749 | 750 | For example, the `docker run` command would include the following parameter: 751 | ``` 752 | -v /home/user:/storage:rw 753 | ``` 754 | 755 | ## Support or Contact 756 | 757 | Having troubles with the container or have questions? Please 758 | [create a new issue](https://github.com/jlesage/docker-qdirstat/issues). 759 | 760 | For other Dockerized applications, visit https://jlesage.github.io/docker-apps. 761 | --------------------------------------------------------------------------------