Docker h5ai

A Docker image for h5ai, a modern HTTP web server indexer.

Built on top of Angie 1.11+ (Alpine) and PHP 8.4 with s6-overlay for process management.

---

Features

• PHP 8.4 & Angie 1.11+ (Alpine-based, lightweight and secure).
• Basic Authentication (built-in wrapper protecting both the directory indexing page and direct static file downloads).
• Hardened Security Headers (X-Frame-Options, X-Content-Type-Options, X-XSS-Protection enabled).
• Proper UNIX Signal Handling (Graceful shutdowns under Docker).
• s6-overlay Process Management (Auto-restart of services on failure).

---

Usage

Basic Usage

Mount the directory you want to share to /share:

docker container run -d -p 80:80 \
  -v /path/to/sharing-file:/share \
  pad92/docker-h5ai

With Basic Authentication

To secure the index page and all files under /share, define the username and password using the ENV_U and ENV_P environment variables:

docker container run -d -p 80:80 \
  -e ENV_U=admin \
  -e ENV_P=mysecretpassword \
  -v /path/to/sharing-file:/share \
  pad92/docker-h5ai

With h5ai Info Page Password (Administration)

To secure the h5ai diagnostic/info page (located at /_h5ai/public/index.php), define the password using the H5AI_ADMIN_PASSWORD environment variable. The container will automatically generate the required SHA-512 hash and update options.json at startup:

docker container run -d -p 80:80 \
  -e H5AI_ADMIN_PASSWORD=myadminpassword \
  -v /path/to/sharing-file:/share \
  pad92/docker-h5ai

Note

If H5AI_ADMIN_PASSWORD is not defined (or empty), a cryptographically secure random 32-character password is automatically generated at boot, written to the startup logs, and hashed in options.json to keep the info page secure by default.

With Custom h5ai Options

To override the default options.json file, mount your custom file into /usr/share/h5ai/_h5ai/private/conf/options.json:

docker container run -d -p 80:80 \
  -v /path/to/sharing-file:/share \
  -v $PWD/options.json:/usr/share/h5ai/_h5ai/private/conf/options.json \
  pad92/docker-h5ai

Cache Paths (Thumbnails & Metadata)

The application caches generated thumbnails and metadata in the following paths within the container:

• Public Cache (Thumbnails cache): /usr/share/h5ai/_h5ai/public/cache/
• Private Cache: /usr/share/h5ai/_h5ai/private/cache/

To persist these thumbnails across container restarts or recreations, mount volumes to these paths:

docker container run -d -p 80:80 \
  -v /path/to/sharing-file:/share \
  -v /path/to/public-cache:/usr/share/h5ai/_h5ai/public/cache \
  -v /path/to/private-cache:/usr/share/h5ai/_h5ai/private/cache \
  pad92/docker-h5ai

Note

Upon container startup, an s6-overlay initialization task automatically ensures that the cache directories have the correct ownership (angie:www-data) and permissions (755) so that the PHP process can write to them.

---

Docker Compose Example

Create a docker-compose.yml file:

services:
  h5ai:
    image: pad92/docker-h5ai
    ports:
      - "8888:80"
    environment:
      - ENV_U=admin
      - ENV_P=mysecretpassword
      - H5AI_ADMIN_PASSWORD=myadminpassword
    volumes:
      - /path/to/sharing-file:/share:ro
    restart: unless-stopped

Then start the container:

docker compose up -d

---

Development

A Makefile is provided to help with local development, testing, and security scans:

• Build the image:

  make build

• Run functional tests (spins up containers and verifies authentication behaviors):

  make test

• Vulnerability scan (uses Trivy to scan the local image):

  make trivy

• Clean local containers and images:

  make clean

---

Changelog

See CHANGELOG.md for a detailed history of changes.