### Dockerfile for Application Initialization

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

A Dockerfile example that sets up an application by installing packages, configuring environment variables, copying default configurations, and shipping initialization scripts. It uses `set-cont-env` to define container environment variables.

```dockerfile
FROM jlesage/baseimage-gui:alpine-3.21-v4

RUN add-pkg myapp
RUN set-cont-env APP_NAME "MyApp"

# Ship default config to /defaults so init can copy it.
COPY myapp.conf /defaults/myapp.conf

# Ship the init script.
COPY rootfs/ /

COPY startapp.sh /startapp.sh
```

--------------------------------

### Example User ID Output

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

This is an example output from the `id <username>` command. The `uid` and `gid` values are used to configure the container's user and group IDs.

```text
uid=1000(myuser) gid=1000(myuser) groups=1000(myuser),4(adm),24(cdrom),27(sudo),46(plugdev),113(lpadmin)
```

--------------------------------

### Create Minimal xterm GUI Container

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

This Dockerfile demonstrates the minimum requirements for creating a GUI container. It installs xterm, sets the application name, and copies a start script.

```dockerfile
# Dockerfile – minimal xterm GUI container
FROM jlesage/baseimage-gui:alpine-3.21-v4

# Install the application.
RUN add-pkg xterm

# Set the application name (shown in the web UI title and window).
RUN set-cont-env APP_NAME "Xterm"

# Copy the start script into the image.
COPY startapp.sh /startapp.sh
RUN chmod +x /startapp.sh
```

--------------------------------

### Dockerfile for Xterm Application

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/DOCKERHUB.md

Example Dockerfile to create an image for running the xterm application. It pulls the base image, installs xterm, copies a start script, and sets the application name.

```dockerfile
FROM jlesage/baseimage-gui:alpine-3.19-v4

# Install xterm.
RUN add-pkg xterm

# Copy the start script.
COPY startapp.sh /startapp.sh

# Set the application name.
RUN set-cont-env APP_NAME "Xterm"
```

--------------------------------

### Install Packages from a Custom Mirror

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Installs a package using a specified custom mirror URL. This is useful for faster or more reliable package installations.

```dockerfile
RUN add-pkg --mirror https://dl-cdn.alpinelinux.org/alpine some-pkg
```

--------------------------------

### Install Build Dependencies, Compile, and Clean Up

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Installs build-time dependencies, clones a repository, compiles it, and then removes the build dependencies and temporary files. Use this pattern when building software from source within a Docker image.

```dockerfile
RUN \
    add-pkg --virtual build-deps build-base cmake git python3 && \
    git clone https://github.com/example/myapp.git /tmp/myapp && \
    cmake -S /tmp/myapp -B /tmp/myapp/build -DCMAKE_BUILD_TYPE=Release && \
    cmake --build /tmp/myapp/build --parallel && \
    cmake --install /tmp/myapp/build && \
    del-pkg build-deps && \
    rm -rf /tmp/myapp
```

--------------------------------

### Install Packages with `add-pkg`

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Demonstrates using the `add-pkg` helper to install runtime dependencies. The `--virtual NAME` flag allows for group removal of packages using `del-pkg`.

```dockerfile
FROM jlesage/baseimage-gui:alpine-3.21-v4

# Install a runtime dependency (stays in the image).
RUN add-pkg ffmpeg
```

--------------------------------

### Dockerfile for Baseimage GUI Application

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Example Dockerfile to build an application image using the baseimage-gui, adding packages, setting environment variables, and copying custom files.

```dockerfile
FROM jlesage/baseimage-gui:alpine-3.21-v4

RUN add-pkg myapp myworker
RUN set-cont-env APP_NAME "MyApp"

COPY rootfs/ /
COPY startapp.sh /startapp.sh
```

--------------------------------

### Configure Container with Public Environment Variables

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

This example shows how to run a container with numerous public environment variables to customize its behavior, including user identity, display settings, application behavior, networking, optional features, security, and debugging.

```shell
docker run --rm \
  -p 5800:5800 \
  -p 5900:5900 \
  -v /path/to/config:/config \
  # User/group identity
  -e USER_ID=1000 \
  -e GROUP_ID=1000 \
  -e SUP_GROUP_IDS=44,video \
  -e UMASK=0022 \
  # Display
  -e DISPLAY_WIDTH=1920 \
  -e DISPLAY_HEIGHT=1080 \
  -e DARK_MODE=1 \
  # Application behavior
  -e KEEP_APP_RUNNING=1 \
  -e APP_NICENESS=0 \
  -e LANG=en_US.UTF-8 \
  -e TZ=America/New_York \
  # Networking
  -e WEB_LISTENING_PORT=5800 \
  -e VNC_LISTENING_PORT=5900 \
  -e WEB_LOCALHOST_ONLY=0 \
  -e VNC_LOCALHOST_ONLY=0 \
  # Optional features (all disabled by default)
  -e WEB_AUDIO=1 \
  -e WEB_FILE_MANAGER=1 \
  -e WEB_FILE_MANAGER_ALLOWED_PATHS=AUTO \
  -e WEB_NOTIFICATION=1 \
  -e WEB_TERMINAL=1 \
  -e WEB_TERMINAL_SHELL_PATH=/bin/sh \
  # Security
  -e SECURE_CONNECTION=1 \
  -e SECURE_CONNECTION_VNC_METHOD=SSL \
  -e VNC_PASSWORD=mypass \
  -e WEB_AUTHENTICATION=1 \
  -e WEB_AUTHENTICATION_USERNAME=admin \
  -e WEB_AUTHENTICATION_PASSWORD=secret \
  -e WEB_AUTHENTICATION_TOKEN_VALIDITY_TIME=24 \
  # Debugging
  -e CONTAINER_DEBUG=1 \
  -e ENABLE_CJK_FONT=1 \
  my-app-image
```

--------------------------------

### Start Script for Xterm Application

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/DOCKERHUB.md

Shell script to be executed when the container starts. It uses 'exec' to replace the shell process with the xterm process.

```shell
#!/bin/sh
exec /usr/bin/xterm
```

--------------------------------

### Install and Configure Locales in Dockerfile

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Add these instructions to your Dockerfile to set the container's locale, for example, to en_US.UTF-8. This is useful if the default POSIX locale causes issues with your application.

```dockerfile
RUN \
    add-pkg locales && \
    sed-patch 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/' /etc/locale.gen && \
    locale-gen
ENV LANG=en_US.UTF-8
```

--------------------------------

### Make Script Executable

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/DOCKERHUB.md

Command to make the start script executable within the Docker build context.

```shell
chmod +x startapp.sh
```

--------------------------------

### Configure Log Rotation for Application Logs

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Create a configuration file in /etc/cont-logrotate.d to enable rotation for a specific log file, such as myapp.log. This example sets a minimum size of 1MB before rotation.

```text
/config/log/myapp.log {
    minsize 1M
}
```

--------------------------------

### Run Container with Web Authentication Enabled

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Start a Docker container with web authentication enabled, configuring a single user via environment variables. Requires SECURE_CONNECTION=1.

```shell
# Quick single-user setup via environment variables.
docker run --rm \
  -p 5800:5800 \
  -v /srv/myapp/config:/config \
  -e SECURE_CONNECTION=1 \
  -e WEB_AUTHENTICATION=1 \
  -e WEB_AUTHENTICATION_USERNAME=admin \
  -e WEB_AUTHENTICATION_PASSWORD=s3cr3t \
  -e WEB_AUTHENTICATION_TOKEN_VALIDITY_TIME=48 \
  my-app-image
```

--------------------------------

### Install Adwaita Theme for Qt Dark Mode

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

For Qt applications, install the adwaita-qt package to enable dark mode. This snippet also shows how to set the application name and configure dark mode environment variables.

```dockerfile
FROM jlesage/baseimage-gui:ubuntu-24.04-v4

# Qt5/Qt6 dark mode requires the adwaita-qt package.
RUN add-pkg myqtapp adwaita-qt

RUN set-cont-env APP_NAME "My Qt App"

# DARK_MODE=1 at runtime will set:
#   GTK_THEME=Adwaita:dark        (GTK3/GTK4)
#   GTK2_RC_FILES=.../Dark/gtkrc  (GTK2)
#   QT_STYLE_OVERRIDE=Adwaita-Dark (Qt5/Qt6)

COPY startapp.sh /startapp.sh
```

--------------------------------

### Install Application Icon

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Add this command to your Dockerfile to specify the URL of your master icon. The master icon should be a square PNG image with a size of at least 512x512.

```dockerfile
# Generate and install favicons.
RUN \
    APP_ICON_URL=https://github.com/jlesage/docker-templates/raw/master/jlesage/images/generic-app-icon.png && \
    install_app_icon.sh "$APP_ICON_URL"
```

--------------------------------

### Execute obxprop to Get Window Properties

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Run this command inside a running container to inspect window properties. This is useful for identifying properties like Name, Class, and Title to configure window management.

```shell
docker exec <container name> obxprop | grep "^_OB_APP"
```

--------------------------------

### Get User and Group IDs

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Use this command on the host to find the UID and GID for the user owning a data volume. These IDs are used to configure the container to avoid permission issues.

```shell
id <username>
```

--------------------------------

### Enable GPU Acceleration in Docker Container

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Expose the host DRI device to the container for hardware-accelerated OpenGL rendering. Requires open-source kernel drivers. Ensure Mesa drivers are installed inside the image.

```shell
docker run --rm \
  -p 5800:5800 \
  --device /dev/dri \
  -e USER_ID=1000 \
  -e GROUP_ID=1000 \
  my-app-image
```

```shell
# The init system checks permissions and reports status in the container log:
# docker logs myapp | grep "GPU\|dri"
#   [ OK ]   the device /dev/dri/card0 has proper permissions.
#   [ OK ]   the container can write to device /dev/dri/card0.
#   [ OK ]   a GPU node has been found.
#   [ OK ]   a render node has been found.

# Install Mesa drivers inside the image to use hardware acceleration.
# In your Dockerfile:
# RUN add-pkg mesa-dri-gallium libva-intel-driver   # Alpine
# RUN add-pkg mesa-va-drivers                        # Debian/Ubuntu
```

--------------------------------

### Add and Remove Packages with Virtual Dependencies

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Use `add-pkg` and `del-pkg` to manage packages, especially for build dependencies. The `--virtual` flag allows temporary installation of a package group that can be later removed entirely.

```dockerfile
RUN \
    add-pkg --virtual build-dependencies build-base cmake git && \
    git clone https://myproject.com/myproject.git && \
    make -C myproject && \
    make -C myproject install && \
    del-pkg build-dependencies
```

--------------------------------

### Check Boolean Environment Variables

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Use `is-bool-val-true` to evaluate environment variables that represent boolean values. It supports common true values like '1', 'true', 'y', 'yes', 'enabled', 'on'. The example shows how to enable debug mode.

```shell
if is-bool-val-true "${CONTAINER_DEBUG:-0}"; then
    # Debug enabled, do something...
fi
```

--------------------------------

### NGINX Configuration for URL Path Routing

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Configure NGINX to route requests to different applications based on the URL path. This setup handles specific paths and redirects, ensuring correct proxying to the Docker container.

```nginx
map $http_upgrade $connection_upgrade {
	default upgrade;
	''      close;
}

upstream docker-myapp {
	# If the reverse proxy server is not running on the same machine as the
	# Docker container, use the IP of the Docker host here.
	# Make sure to adjust the port according to how port 5800 of the
	# container has been mapped on the host.
	server 127.0.0.1:5800;
}

server {
	[...] 

	location = /myapp {return 301 $scheme://$http_host/myapp/;} 
	location /myapp/ {
		proxy_pass http://docker-myapp/; 
		proxy_http_version 1.1;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection $connection_upgrade;
		proxy_buffering off;
		proxy_read_timeout 86400s;
		proxy_send_timeout 86400s;
		# Uncomment the following line if your Nginx server runs on a port that
		# differs from the one seen by external clients.
		#port_in_redirect off;
	}
}
```

--------------------------------

### Initialize Application Configuration and Ownership

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Sets up application directories, copies default configuration, patches it using sed-patch, and ensures the application user has ownership of the configuration directory. This script is intended for use in `/etc/cont-init.d/`.

```shell
# rootfs/etc/cont-init.d/50-myapp-init.sh
#!/bin/sh

set -e
set -u

# Create required runtime directories under /config (persisted volume).
mkdir -p /config/log /config/data /config/cache

# Copy default config if not already present.
[ -f /config/myapp.conf ] || cp /defaults/myapp.conf /config/myapp.conf

# Patch the config based on environment variables.
sed-patch "s|^data_dir=.*|data_dir=/config/data|" /config/myapp.conf

# Take ownership so the app user can write to it.
take-ownership /config

echo "myapp initialization complete."
```

--------------------------------

### Define a Service with Run, Params, and Respawn

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Configure a background service by specifying the executable in 'run', its arguments in 'params', and enabling automatic restarts with an empty 'respawn' file.

```shell
#!/bin/sh
exec /usr/bin/myworker --config /config/worker.conf
```

```shell
#!/bin/sh
# $1 = PID of myworker
kill -0 "$1" 2>/dev/null && \
    [ -S /var/run/myworker.sock ]
```

```shell
#!/bin/sh
EXIT_CODE="$1"
echo "myworker exited with code ${EXIT_CODE}"
```

--------------------------------

### Configure Main Window Selection (Openbox)

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Create this XML file in the container to define criteria for matching the main application window. It allows specifying properties like Type and Name for window management.

```xml
<Type>normal</Type>
<Name>My Application</Name>
```

--------------------------------

### Initialize Application with Boolean Environment Variable Checks

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Initializes application settings based on boolean environment variables. It uses `is-bool-val-true` and `is-bool-val-false` to uniformly evaluate common true/false values.

```shell
#!/bin/sh
# /etc/cont-init.d/50-myapp.sh

set -e
set -u

# Branch on a public environment variable.
if is-bool-val-true "${DARK_MODE:-0}"; then
    export MYAPP_THEME="dark"
else
    export MYAPP_THEME="light"
fi

# Guard against optional feature.
if is-bool-val-false "${WEB_AUDIO:-0}"; then
    echo "Audio not enabled; skipping audio device setup."
    exit 0
fi

# Nested check using an internal variable.
if is-bool-val-true "${CONTAINER_DEBUG:-0}"; then
    echo "Debug mode active – dumping environment:"
    env | sort
fi
```

--------------------------------

### Build and Run xterm Container

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Commands to build the Docker image for the xterm container and run it. Includes instructions on how to access the GUI via a web browser or VNC client.

```shell
# Build and run
docker build -t my-xterm .
docker run --rm \
  -p 5800:5800 \
  -p 5900:5900 \
  -v /path/to/config:/config \
  my-xterm

# Access via browser
open http://localhost:5800

# Access via any VNC client
# Host: localhost  Port: 5900
```

--------------------------------

### Access GUI via VNC Client

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Connect to the application's GUI using any VNC client. Ensure the container's ports are mapped to the host's ports.

```text
<HOST_IP_ADDR>:5900
```

--------------------------------

### Access GUI via Web Browser

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Access the application's GUI through a web browser. Ensure the container's ports are mapped to the host's ports.

```text
http://<HOST_IP_ADDR>:5800
```

--------------------------------

### Add User to Web Authentication

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Use this command to add a new user for web authentication. Ensure the container name is correct.

```bash
docker exec -ti <container name> webauth-user add <username>
```

--------------------------------

### Configure Log Rotation for Application Logs

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Add log rotation for application log files by placing a configuration file in `/etc/cont-logrotate.d/`. The logrotate service runs daily and activates automatically if configurations exist.

```text
# rootfs/etc/cont-logrotate.d/myapp
/config/log/myapp.log {
    minsize 1M
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}

/config/log/myapp_error.log {
    size 10M
    rotate 4
    compress
}
```

```dockerfile
FROM jlesage/baseimage-gui:alpine-3.21-v4

RUN add-pkg myapp
RUN set-cont-env APP_NAME "MyApp"

# Install the logrotate config.
COPY rootfs/ /

COPY startapp.sh /startapp.sh
```

--------------------------------

### List Users in Web Authentication

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Use this command to list all users configured for web authentication within the container. Replace <container name> with your container's name.

```bash
docker exec <container name> webauth-user list
```

--------------------------------

### Build Docker Image

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/DOCKERHUB.md

Command to build the Docker image from the Dockerfile in the current directory.

```shell
docker build -t docker-xterm .
```

--------------------------------

### Generate Application Favicons using install_app_icon.sh

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Generate a set of favicons from a master PNG icon. Supports remote URLs or local files. Custom output directories can be specified.

```dockerfile
FROM jlesage/baseimage-gui:alpine-3.21-v4

RUN add-pkg myapp
RUN set-cont-env APP_NAME "MyApp"

# Generate favicons from a remote PNG icon.
RUN \
    APP_ICON_URL=https://example.com/myapp-icon.png && \
    install_app_icon.sh "$APP_ICON_URL"

# Or use a local file bundled in the build context.
COPY myapp-icon.png /tmp/myapp-icon.png
RUN install_app_icon.sh /tmp/myapp-icon.png

# Custom output directories (optional flags).
RUN install_app_icon.sh \
    https://example.com/myapp-icon.png \
    --icons-dir /opt/noVNC/app/images/icons \
    --html-file /opt/noVNC/index.html

COPY startapp.sh /startapp.sh
```

--------------------------------

### Run Container with Secure Connection Enabled

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Launch a Docker container with HTTPS and TLS-encrypted VNC enabled. Mounts a volume for certificates and sets environment variables to configure security settings.

```shell
# Run with HTTPS and TLS-encrypted VNC.
docker run --rm \
  -p 5800:5800 \
  -p 5900:5900 \
  -v /srv/myapp/config:/config \
  -e SECURE_CONNECTION=1 \
  -e SECURE_CONNECTION_VNC_METHOD=TLS \
  -e SECURE_CONNECTION_CERTS_CHECK_INTERVAL=60 \
  my-app-image
```

--------------------------------

### Fetch and Process Web Data

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/rootfs/opt/noVNC/login/index.html

Fetches 'webdata.json' to configure application name, logo, and dark mode settings. Throws an error if fetching or parsing fails.

```javascript
let webData = null;
await fetch('./webdata.json')
  .then(response => {
    if (!response.ok) {
      throw new Error(`Could not fetch web data: HTTP error: Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    webData = data;
  })
  .catch(error => {
    throw new Error(`Could not load web data: ${error}`);
  });
```

--------------------------------

### Run Docker Container

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/DOCKERHUB.md

Command to run the built Docker image as a container. It maps ports 5800 (web access) and 5900 (VNC access) from the host to the container.

```shell
docker run --rm -p 5800:5800 -p 5900:5900 docker-xterm
```

--------------------------------

### Set VNC Password via Clear Text File

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Configure the VNC password by providing a clear-text password file in the mounted /config directory. The file is obfuscated on startup.

```shell
# Set via file (stored in /config, survives restarts).
echo "mypass8c" > /srv/myapp/config/.vncpass_clear
docker run --rm \
  -p 5900:5900 \
  -v /srv/myapp/config:/config \
  my-app-image
```

--------------------------------

### Manage Web Authentication Users

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Commands to manage users for web authentication within a running container. Assumes a /config volume is mounted.

```shell
# Multi-user management via the webauth-user tool.
# The container must be running with a /config volume mounted.
docker exec -ti myapp webauth-user add alice
docker exec -ti myapp webauth-user update alice
docker exec    myapp webauth-user del bob
docker exec    myapp webauth-user list
```

--------------------------------

### Enable Dark Mode for Web UI and Applications

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Enable dark mode for the web UI and GTK/Qt applications using a single environment variable.

```shell
docker run --rm \
  -p 5800:5800 \
  -e DARK_MODE=1 \
  my-app-image
```

--------------------------------

### Run Docker Container with Read-Only Filesystem

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Enable read-only root filesystem for a Docker container to enhance security and reliability. Mount /tmp as a tmpfs to allow ephemeral data storage.

```bash
docker run --read-only --tmpfs /tmp -v /path/on/host:/config <your_image>
```

--------------------------------

### Log Monitor Notification Configuration

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Set up notification details for the log monitor, including title, description, log level, source file, and target destinations.

```shell
MyApp Error
```

```shell
ERROR
```

```shell
log:/config/log/myapp.log
```

```shell
stdout
web-notif
```

--------------------------------

### Set HOME Environment Variable

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Set the HOME environment variable in the startapp.sh script if your application requires it. This is useful if the application writes to the home directory and you want to map it to a host directory like /config.

```shell
export HOME=/config
```

--------------------------------

### Run Docker Container with Read-Only Filesystem

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Enhance security by running the container with an immutable root filesystem. Only `/tmp` (tmpfs) and `/config` (volume) are writable. Docker Compose configuration is also provided.

```shell
docker run --rm \
  -p 5800:5800 \
  -p 5900:5900 \
  --read-only \
  --tmpfs /tmp \
  -v /srv/myapp/config:/config \
  -e USER_ID=1000 \
  -e GROUP_ID=1000 \
  my-app-image
```

```yaml
# docker-compose.yml
services:
  myapp:
    image: my-app-image
    ports:
      - "5800:5800"
      - "5900:5900"
    read_only: true
    tmpfs:
      - /tmp
    volumes:
      - ./config:/config
    environment:
      - USER_ID=1000
      - GROUP_ID=1000
      - SECURE_CONNECTION=1
      - WEB_AUTHENTICATION=1
      - WEB_AUTHENTICATION_USERNAME=admin
      - WEB_AUTHENTICATION_PASSWORD=secret
```

--------------------------------

### Patch Configuration with Standard Sed Options

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Applies a sed replacement to a configuration file, supporting standard sed options like -n. Use this for targeted modifications within configuration files.

```dockerfile
RUN sed-patch -n 's/old_value/new_value/gp' /etc/myapp/config.ini
```

--------------------------------

### Update User in Web Authentication

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Use this command to update an existing user's credentials for web authentication. Replace <container name> and <username> accordingly.

```bash
docker exec -ti <container name> webauth-user update <username>
```

--------------------------------

### Redirect Service Output to Log Files

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Redirect standard output and standard error of a service to different log files. This is advisable if a program's output is too verbose for the container log.

```shell
#!/bin/sh
exec /usr/bin/my_service > /config/log/my_service_out.log 2> /config/log/my_service_err.log
```

--------------------------------

### Recursively Set Directory Ownership

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

The `take-ownership` helper recursively sets the user and group ID for a directory and its contents. It handles potential failures with network shares by performing a write test. Default IDs are taken from `USER_ID` and `GROUP_ID` environment variables.

```shell
take-ownership /config
```

```shell
take-ownership /config 99 100
```

--------------------------------

### Set Internal Environment Variables at Build Time

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

This Dockerfile illustrates how to set internal environment variables using `set-cont-env` during the image build process. These variables are stored in `/etc/cont-env.d/` and are available at container startup.

```dockerfile
FROM jlesage/baseimage-gui:alpine-3.21-v4

RUN add-pkg myapp

# Set internal variables at build time.
RUN set-cont-env APP_NAME "My Application"
RUN set-cont-env APP_VERSION "1.2.3"
RUN set-cont-env DOCKER_IMAGE_VERSION "1.0.0"

# Executable variable: value is captured from the script's stdout at startup.
COPY get_home_dir.sh /etc/cont-env.d/HOME
RUN chmod +x /etc/cont-env.d/HOME
# get_home_dir.sh: #!/bin/sh \n echo /config
# Exit 100 to leave the variable unset:
# #!/bin/sh \n exit 100

COPY startapp.sh /startapp.sh
```

--------------------------------

### Copy RootFS Files to Container

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Use this Dockerfile command to copy all files from the rootfs directory in your source tree into the container, mirroring the container's file structure.

```dockerfile
COPY rootfs/ /

```

--------------------------------

### Configure Log Monitor Target for Slack

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Define a target for log monitor notifications to send messages to Slack using a webhook. Includes a debouncing interval to limit notification frequency.

```shell
#!/bin/sh
TITLE="$1"
MSG="$2"
LEVEL="$3"
curl -s -X POST https://hooks.slack.com/services/XXXXX \
     -H 'Content-type: application/json' \
     --data "{\"text\":\[$LEVEL] $TITLE: $MSG\"}"
```

```shell
300
```

--------------------------------

### Perform Cleanup Tasks During Container Shutdown

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

A script designed to run during container shutdown, performing cleanup tasks such as flushing write-behind caches and removing stale lock files. Place this script in `/etc/cont-finish.d/`.

```shell
# rootfs/etc/cont-finish.d/50-myapp-cleanup.sh
#!/bin/sh

set -e
set -u

echo "myapp: flushing write-behind cache..."
sync

echo "myapp: removing stale lock files..."
rm -f /config/run/myapp.lock

echo "myapp: shutdown cleanup done."
```

--------------------------------

### Apply Multiple Patches with sed-patch

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Applies multiple sed patch expressions to a configuration file using the -e option. This is useful for making several related changes to a single file.

```dockerfile
RUN sed-patch \
    -e 's/DEBUG=false/DEBUG=true/' \
    -e 's/LOG_LEVEL=info/LOG_LEVEL=debug/' \
    /etc/myapp/settings.conf
```

--------------------------------

### Set VNC Password via Environment Variable

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Configure the VNC password for a Docker container using the VNC_PASSWORD environment variable. The password is limited to 8 characters.

```shell
# Set via environment variable.
docker run --rm \
  -p 5900:5900 \
  -e VNC_PASSWORD=mypass8c \
  my-app-image
```

--------------------------------

### Configure Log Monitor Notification Filter

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Define a filter for the log monitor to match specific log lines. This script is invoked with the log line as its first argument; an exit code of 0 indicates a match.

```shell
#!/bin/sh
# Invoked with the log line as $1. Exit 0 = match.
echo "$1" | grep -qi "error\|exception\|fatal"
```

```shell
# Dynamic description: print the matched line.
echo "Log line: $1"
```

--------------------------------

### Set Directory Ownership Recursively

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Recursively sets ownership of a directory and its contents to the container's user. It handles network-mounted volumes by falling back to a write-access test if chown fails.

```shell
#!/bin/sh
# /etc/cont-init.d/50-myapp.sh

set -e
set -u

# Use USER_ID / GROUP_ID from the environment (the default).
take-ownership /config

# Explicitly provide UID and GID (useful for supplementary directories).
take-ownership /data 99 100

# Use inside a Dockerfile's COPY + init pattern.
# All files dropped into /config will be owned by the app user at runtime.
```

--------------------------------

### Update UI Elements with Web Data

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/rootfs/opt/noVNC/login/index.html

Updates the page title, application name fields, and logo properties using data fetched from 'webdata.json'. Enables dark mode if specified in the data.

```javascript
// Update page title.
document.title = 'Login - ' + webData.applicationName;

// Update application name fields.
Array.from(document.getElementsByName('appName'))
  .forEach(el => el.innerText = webData.applicationName);

// Update logo image properties.
document.getElementById('appLogo').alt = webData.applicationName + 'logo';
document.getElementById('appLogo').title = webData.applicationName;

// Enable dark mode.
if (webData.darkMode) {
  document.documentElement.classList.add("dark");
  document.documentElement.setAttribute('data-bs-theme', 'dark');
}
```

--------------------------------

### Remove User from Web Authentication

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Use this command to remove a user from the web authentication system. Ensure the container name is correct.

```bash
docker exec <container name> webauth-user del <username>
```

--------------------------------

### Patch SSH Configuration Safely

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Safely patches the SSH configuration file by uncommenting PermitRootLogin. This command fails the build if the pattern is not found, preventing silent misconfigurations.

```dockerfile
RUN sed-patch 's/^#\(PermitRootLogin\)/\1/' /etc/ssh/sshd_config
```

--------------------------------

### Handle Login Form Submission

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/rootfs/opt/noVNC/login/index.html

Validates the login form. If invalid, it prevents default submission and hides the status message. If valid, it disables the submit button and shows a spinner.

```javascript
// Handle submit event.
const form = document.forms['loginForm'];
form.addEventListener('submit', (event) => {
  if (!form.checkValidity()) {
    var loginStatus = document.getElementById('loginStatus');
    loginStatus.classList.add("d-none");
    event.preventDefault();
    event.stopPropagation();
  } else {
    // Disable the button and show the spinner.
    loginButton.disabled = true;
    loginButtonLabel.classList.add("d-none");
    loginButtonSpinner.classList.remove("d-none");
  }
  form.classList.add('was-validated');
});
```

--------------------------------

### Remove a Specific Package

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Removes a specified package and cleans up its dependencies. Use this to reduce image size by removing unnecessary packages.

```dockerfile
RUN del-pkg unneeded-pkg
```

--------------------------------

### Configure NGINX Reverse Proxy for Docker Container

Source: https://context7.com/jlesage/docker-baseimage-gui/llms.txt

Route web traffic to the container using NGINX, supporting hostname-based and path-based routing. WebSocket upgrade headers are essential for noVNC.

```nginx
# Hostname-based routing: myapp.example.com → container at 127.0.0.1:5800
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

upstream docker-myapp {
    server 127.0.0.1:5800;
}

server {
    listen 443 ssl;
    server_name myapp.example.com;

    ssl_certificate     /etc/ssl/certs/fullchain.pem;
    ssl_certificate_key /etc/ssl/private/privkey.pem;

    location / {
        proxy_pass             http://docker-myapp;
        proxy_http_version     1.1;
        proxy_set_header       Upgrade $http_upgrade;
        proxy_set_header       Connection $connection_upgrade;
        proxy_buffering        off;
        proxy_read_timeout     86400s;
        proxy_send_timeout     86400s;
    }
}

# Path-based routing: example.com/myapp/ → container at 127.0.0.1:5800
server {
    listen 443 ssl;
    server_name example.com;

    location = /myapp { return 301 $scheme://$http_host/myapp/; }
    location /myapp/ {
        proxy_pass         http://docker-myapp/;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection $connection_upgrade;
        proxy_buffering    off;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}
```

--------------------------------

### Modify Files Safely with sed-patch

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

The `sed-patch` helper modifies files using `sed` expressions and fails the build if no changes are made, ensuring that the intended file modification occurred. The `-i` option is automatically included.

```shell
sed-patch 's/Replace this/By this/' /etc/myfile
```

--------------------------------

### Display Login Status Message

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/rootfs/opt/noVNC/login/index.html

Checks for a 'login_result' cookie and displays an 'Incorrect username or password' message if invalid credentials are detected. Removes the cookie afterwards.

```javascript
// Show login status message if needed.
var loginResult = Cookies.get('login_result');
if (loginResult === 'INVALID_CREDENTIALS') {
  var loginStatus = document.getElementById('loginStatus');
  loginStatus.innerText = "Incorrect username or password.";
  loginStatus.classList.remove("d-none");
}
Cookies.remove('login_result', { path: 'login' });
```

--------------------------------

### NGINX Configuration for Hostname Routing

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Configure NGINX to route requests to different applications based on the hostname. Ensure the upstream server address and port are correctly mapped from the Docker container.

```nginx
map $http_upgrade $connection_upgrade {
	default upgrade;
	''      close;
}

upstream docker-myapp {
	# If the reverse proxy server is not running on the same machine as the
	# Docker container, use the IP of the Docker host here.
	# Make sure to adjust the port according to how port 5800 of the
	# container has been mapped on the host.
	server 127.0.0.1:5800;
}

server {
	[...] 

	server_name myapp.domain.tld;

	location / {
		proxy_pass http://docker-myapp;
		proxy_http_version 1.1;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection $connection_upgrade;
		proxy_buffering off;
		proxy_read_timeout 86400s;
		proxy_send_timeout 86400s;
	}
}
```

--------------------------------

### Set Internal Environment Variables in Dockerfile

Source: https://github.com/jlesage/docker-baseimage-gui/blob/master/README.md

Use `set-cont-env` within a `Dockerfile` to define internal environment variables. These variables are stored in files under `/etc/cont-env.d`, making them available during container runtime.

```dockerfile
RUN set-cont-env APP_NAME "Xterm"
```