awesometic/h5ai-ng repository overview

⁠h5ai-ng

English · 한국어⁠ · Español⁠ · 日本語⁠ · 简体中文⁠

h5ai-ng is a file index for Apache httpd, lighttpd and nginx. Visitors browse folders, preview images, video, audio and text, filter by name and download a whole selection as one archive. Your files stay where they are.

It is a maintained fork of h5ai⁠ by Lars Jung, which stopped releasing in 2021.

The original site⁠ describes h5ai like this:

⁠Why h5ai-ng

• Read-only, no database. It replaces the server's plain directory listing and never writes to your files.
• Current PHP. Runs on PHP 8.3 and later; the Docker image ships PHP 8.5.
• No third-party requests. The fonts ship with the interface, so a page load stays on your server.
• Your h5ai setup carries over. options.json, URLs and the default and comity icon themes keep working.

⁠h5ai, docker-h5ai and h5ai-ng

⁠Is h5ai still maintained?

The original h5ai has had no release since 0.30.0 in January 2021. h5ai-ng is its maintained fork, with releases since 0.31.0 in November 2026, and requires PHP 8.3 or later. options.json, URLs and the default and comity icon themes keep working. Other files you changed in _h5ai, such as types.json, a theme or a translation, need to be copied back when you switch to h5ai-ng.

⁠Which Docker image should I use for h5ai?

Use awesometic/h5ai-ng. It is published for linux/amd64, linux/arm64, linux/arm/v7 and linux/arm/v6, with the tools for thumbnails, archive downloads and folder sizes already installed. The older awesometic/h5ai image still runs but gets no updates, including security fixes. To switch, back up /config and change the image name in your docker run command or Compose file; with docker run, remove the old container first. See Moving from docker-h5ai⁠.

⁠Can I run h5ai-ng without Docker?

Yes. Each release⁠ has a zip. Unpack it into the web root of Apache httpd, lighttpd or nginx running PHP 8.3 or later, add /_h5ai/public/index.php as the last directory index and block /_h5ai/private/, which holds options.json and its password hash. See Install on your own server⁠.

⁠Quick start with Docker

docker run -d --name h5ai -p 80:80 \
  -v /path/to/files:/h5ai \
  -v /path/to/config:/config \
  -e PUID=1000 -e PGID=1000 -e TZ=Europe/Berlin \
  --restart unless-stopped \
  awesometic/h5ai-ng

Open http://localhost/. Images are published for linux/amd64, linux/arm64, linux/arm/v7 and linux/arm/v6.

The image ships what the optional features need: image, video and PDF thumbnails, tar and zip downloads and folder sizes. Log in to its info page (/_h5ai/public/index.php) and every check passes:

docker logs h5ai shows nginx requests and errors and PHP errors. With /logs mounted, they are also written to nginx/access.log, nginx/error.log and php/error.log there. The files rotate every LOG_ROTATE_INTERVAL_DAYS days after midnight in TZ, are compressed one rotation later and are deleted LOG_RETENTION_DAYS days after rotation. Both values range from 1 to 36500, and retention must be at least the interval. Root owns the files and the LOG_READ_GID group can only read them. Mount /logs read-write, give each container its own folder and keep /logs/.state, which holds the rotation schedule across recreations.

The image serves plain HTTP. Put a reverse proxy with TLS in front of it, especially with HTPASSWD.

To use another host port, change the first number of -p, for example -p 8080:80. Hard links and symlinks within /h5ai work as they are; a symlink that points outside /h5ai needs its target mounted at the same path, for example -v /mnt/media:/mnt/media:ro.

To serve h5ai under a path such as /share/, let the reverse proxy strip the path and name it in X-Forwarded-Prefix:

location /share/ {
    proxy_pass http://127.0.0.1:8080/;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Prefix /share;
    proxy_redirect / /share/;
}

A /config/nginx/h5ai.conf saved before 0.31.1 ignores that header; see Moving from docker-h5ai⁠ for how to get the current default.

⁠Install on your own server

1. Download h5ai-<version>.zip from Releases⁠, or build it (see below). Do not copy files from src; they must be built first.

2. Unpack it into your web root, so that _h5ai sits next to your files.

3. Add /_h5ai/public/index.php as the last directory index:

   • Apache httpd: DirectoryIndex index.html index.php /_h5ai/public/index.php
   • lighttpd: index-file.names += ("/_h5ai/public/index.php")
   • nginx: index index.html index.php /_h5ai/public/index.php;

4. Block /_h5ai/private/, which holds options.json and its password hash. The .htaccess files in _h5ai do this only on Apache httpd with AllowOverride All; Debian's packaged Apache, for one, ships AllowOverride None. Unless your web root has AllowOverride All, add the rule for your server:

   <Location "/_h5ai/private/">
       Require all denied
   </Location>
   

   Copy

   $HTTP["url"] =~ "^/_h5ai/private/" { url.access-deny = ("") }
   

   Copy

   location ^~ /_h5ai/private/ { deny all; }
   

   Copy

   The lighttpd rule needs mod_access. Then check that curl -I http://your-server/_h5ai/private/conf/options.json answers 403.

5. Let the web server user write to _h5ai/public/cache and _h5ai/private/cache. The info page shows whether it can.

PHP 8.3 or later is required. Visitors need Chrome or Edge 91, Firefox 90 or Safari 15; older browsers get a plain list.

⁠Configuration

Settings live in _h5ai/private/conf/options.json (in Docker: /config/h5ai/_h5ai/private/conf/options.json). Each option is described in the file.

/_h5ai/public/index.php opens the info page, which checks what your server supports. Its preset password is empty, so set your own: put the SHA-512 hash of it in passhash.

printf '%s' 'your password' | sha512sum    # macOS: shasum -a 512

⁠Moving from docker-h5ai

docker-h5ai⁠ users keep their volumes and variables and change only the image name.

1. Back up the config folder: cp -a /path/to/config /path/to/config.bak
2. Remove the old container and start awesometic/h5ai-ng with the same -v and -e options: docker rm -f h5ai, then the docker run command above. With Compose, change image: and run docker compose up -d.
3. Read docker logs h5ai. On the first start the container:
   • replaces /config/h5ai/_h5ai with the new version but keeps your options.json, and saves a copy of it as /config/<date>_options.json.bak;
   • blocks /_h5ai/private/ in /config/nginx/h5ai.conf and saves the old file as /config/<date>_h5ai.conf.bak. If that file was changed too much to update, the container stops and prints what to change.

Your options.json stays as it was, password included. Unless you changed those entries, it keeps the filter off and loads fonts from Google Fonts; compare it with the new defaults⁠ if you want those changes. Other files you changed in _h5ai, such as types.json, a theme or a translation, are replaced by the new version; copy them back from the backup of step 1.

The first start adds only that block to a saved h5ai.conf. To also get the current default, which keeps a mapped port in folder redirects and reads X-Forwarded-Prefix, remove the container, then the file, and run the docker run command above again:

docker rm -f h5ai
rm /path/to/config/nginx/h5ai.conf

If you changed that file, make your changes again in the new one.

To go back, remove the container, put the backup in place and start awesometic/h5ai again:

docker rm -f h5ai
mv /path/to/config /path/to/config.ng
cp -a /path/to/config.bak /path/to/config

⁠Build

Requires Node.js 24⁠. The built _h5ai folder lands in build.

npm ci
npm run build     # build/_h5ai
npm run release   # also build/h5ai-<version>.zip (needs zip)
docker build -t h5ai-ng .

Bugs and pull requests go to this repository⁠. Open pull requests from the original h5ai are reviewed here one at a time.

⁠Also from the maintainer

ToneDial⁠ gives your coding agent a character. Pick one of 7 characters or set 12 tone axes, and the local CLI applies that voice to Claude Code, Codex or Antigravity across your projects. It is still in development and needs Node 22 or later.

npm install --global tonedial

⁠License

Released under the MIT License. The full text, with the copyright notices of h5ai and h5ai-ng, is in LICENSE⁠.

⁠References

h5ai profits from other projects, all of them licensed under the MIT license too. Exceptions are some Material Design icons⁠ (CC BY 4.0) and the Ubuntu and Ubuntu Mono fonts (@fontsource/ubuntu⁠ and @fontsource/ubuntu-mono⁠ 5.3.0, Ubuntu Font Licence 1.0), which are bundled unmodified in _h5ai/public/fonts/ together with the licence.