docker-h5ai

What is h5ai

h5ai is a modern file indexer for HTTP web servers with focus on your files. Directories are displayed in a appealing way and browsing them is enhanced by different views, a breadcrumb and a tree overview. Initially h5ai was an acronym for HTML5 Apache Index but now it supports other web servers too.

What this project provided for

I hope this project would be useful for those who uses Docker for building their server.

Features

Core packages

I choose Alpine Linux as a base image to make it a light-weight service. And I do choose Nginx-Alpine to get the benefits from some tweaks of Nginx version.

So this is composed of,

Alpine Linux 3.19
Nginx 1.27.0
PHP 8.2.20

with,

h5ai 0.30.0

And to gather all of these into one together I use supervisor that manages all of these processes.

All functions work

h5ai supports extensional functions such as showing thumnails of audio and video, caching for better speed, etc. This image activates all of those functions.

PHP 8 JIT enabled

JIT compiler that is introduced in PHP 8 is enabled by default.

Supports multiple architectures

It builds from Github Actions for supporting multiple architectures such as AMD64(x86_64) and ARM64, ARMv7, ARMv6.

So that you can use this on most computers supporting Docker.

How can I use this

First of all, it assumes that you have installed Docker on your system.

Pulling the Docker image

Pull the image from docker hub with the following command.

docker pull awesometic/h5ai

Basic usage

This is how it can be a service, in the other word, a container.

You can run it using the following command.

docker run -it --rm \
-p 80:80 \
-v /shared/dir:/h5ai \
-v /config/dir:/config \
-e PUID=$UID \
-e PGID=$GID \
-e TZ=Asia/Seoul \
awesometic/h5ai

The --rm option in the command is added to remove the executed container since this is an example usage.

Basically, two directories should be mapped to the host PC.

/h5ai: This will be where the shared files located.
/config: This will be where stores configurations of h5ai and Nginx settings.

And you should set proper PUID and PGID. If those not set up, the default UID, GID, the number 911, will be used for the /config directory. Not setting PUID/PGID will not significantly affect its operations, but setting up the proper number is still recommended.

Or you can handle some directories that has special permissions using these PUID/PGID.

If you want to run this image as a daemon, use -d option. See the following command.

docker run -d --name=h5ai \
-p 80:80 \
-v /shared/dir:/h5ai \
-v /config/dir:/config \
-e PUID=$UID \
-e PGID=$GID \
-e TZ=Asia/Seoul \
awesometic/h5ai

If you want to run this image permanently, so to speak, to keep it runs after rebooting the server, you can use --restart unless-stopped option. See the following command.

docker run -d --name=h5ai \
-p 80:80 \
-v /shared/dir:/h5ai \
-v /config/dir:/config \
-e PUID=$UID \
-e PGID=$GID \
-e TZ=Asia/Seoul \
--restart unless-stopped \
awesometic/h5ai

Keep in safe from anonymous

If you want to login when visiting the hosted h5ai website so that implement protection from accessing anonymous users, add HTPASSWD environments like the below.

docker run -it --name=h5ai \
-p 80:80 \
-v /shared/dir:/h5ai \
-v /config/dir:/config \
-e PUID=$UID \
-e PGID=$GID \
-e TZ=Asia/Seoul \
-e HTPASSWD=true \
-e HTPASSWD_USER=awesometic \
awesometic/h5ai

Then only the user set by HTPASSWD_USER, awesometic can access this h5ai website with these options.

Be aware of that the HTPASSWD environment variable must be true for authentication.

And aware of this too that you have to run in interaction mode by adding -it to set a password for the newly created user for the first time.

Or, you can set the password for Htpasswd by passing an environment variable. In this case, you shouldn't have to use -it option because it is not needed at all.

Use it as a real-time service

Consequently, if you want to run this image as a real-time service, check the following command.

docker run -d --name=h5ai \
-p 80:80 \
-v /shared/dir:/h5ai \
-v /config/dir:/config \
-e PUID=$UID \
-e PGID=$GID \
-e TZ=Asia/Seoul \
-e HTPASSWD=true \
-e HTPASSWD_USER=awesometic \
-e HTPASSWD_PW=awesometic \
--restart unless-stopped \
awesometic/h5ai

Visit your website

To do the test drive, when the container runs then just let your browser browses:

http://localhost/

After all, you can see the directories you shared.

Caution when update

If the new h5ai version releases, I overwrite all the updated files to the corresponded directories on the project folder. In this sequence, some customized files by you will be replaced into the new one.

So it is highly recommended to make back up files of your edits before update the Docker image.

To prevent an unexpected accident, I put minimal protection into my init.sh script. This checks if the current private/conf/options.json file is outdated from the current about to be run. If the current options.json is older than the newly loaded one, the script makes its backup file under the /config directory. See the followings.

awesometic@awesometic-nas:docker/h5ai $ ll
total 32K
-rwxr-xr-x 1 root root  12K Jul 10  2019 20190710_165345_options.json.bak
-rwxr-xr-x 1 root root  12K Feb  3 14:46 20210203_144624_options.json.bak
drwxr-xr-x 3 root root 4.0K Feb  3 14:46 h5ai
drwxr-xr-x 2 root root 4.0K Dec 14  2018 nginx

But since I don't know how much the users edit their h5ai files like layout or style, it won't make backups for all of the h5ai related files. So it depends on your caution.

If you have any good idea, please let me know. 😀

Use with HTTPS (SSL)

It is highly recommended to use this web service with HTTPS for data encryption. Without SSL, the attackers can see your data streams even if you set the htpasswd to authenticate to the web page.

In this image, it is not provide any HTTPS related settings but you can set HTTPS with another web server. The most frequently used thing for HTTPS is a reverse proxy server, which can be set easiliy with a docker image called SWAG from LinuxServer.io.

TODOs

Easy access to options.json
Access permission using htpasswd
Setup PUID/PGID to better handle the permissions
Expose Nginx, PHP log files to the host

License

This project comes with MIT license. Please see the license file.

binge8/docker-h5ai