Installation

There are two main ways to run the application.

1. As a Docker container.
2. Using the correct executable for your platform by downloading it from the Releases.

Configuration Options

The application can be configured using environment variables. You can find a list of all available options in the configuration section.

Docker

The following instructions assume Docker is already installed on your system. See (Docker's official installation guide)

The official image is ghcr.io/sysadminsmedia/homebox:latest. For each image there are two tags, respectively the regular tag and $TAG-rootless, which uses a non-root image.

Docker Run

Great for testing out the application, but not recommended for stable use. Checkout the docker-compose below for the recommended deployment.

# If using the rootless image, ensure data
# folder has correct permissions
$ mkdir -p /path/to/data/folder
$ chown 65532:65532 -R /path/to/data/folder
# ---------------------------------------
# Run the image
$ docker run -d \
  --name homebox \
  --restart unless-stopped \
  --publish 3100:7745 \
  --env TZ=Europe/Bucharest \
  --env HBOX_OPTIONS_ALLOW_ANALYTICS=false \
  --volume /path/to/data/folder/:/data \
  ghcr.io/sysadminsmedia/homebox:latest
# ghcr.io/sysadminsmedia/homebox:latest-rootless

Docker Compose

1. Create a docker-compose.yml file.

services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:latest
#   image: ghcr.io/sysadminsmedia/homebox:latest-rootless
    container_name: homebox
    restart: always
    environment:
    - HBOX_LOG_LEVEL=info
    - HBOX_LOG_FORMAT=text
    - HBOX_WEB_MAX_FILE_UPLOAD=10
    # Please consider allowing analytics to help us improve Homebox (basic computer information, no personal data)
    - HBOX_OPTIONS_ALLOW_ANALYTICS=false
    volumes:
      - homebox-data:/data/
    ports:
      - 3100:7745

volumes:
   homebox-data:
     driver: local

INFO

If you use the rootless image, and instead of using named volumes you would prefer using a hostMount directly (e.g., volumes: [ /path/to/data/folder:/data ]) you need to chown the chosen directory in advance to the 65532 user (as shown in the Docker example above).

WARNING

If you have previously set up docker compose with the HBOX_WEB_READ_TIMEOUT, HBOX_WEB_WRITE_TIMEOUT, or HBOX_IDLE_TIMEOUT options, and you were previously using the hay-kot image, please note that you will have to add an s for seconds or m for minutes to the end of the integers. A dependency update removed the defaultation to seconds and it now requires an explicit duration time.

2. While in the same folder as docker-compose.yml, start the container by running:

docker compose up --detach

3. Navigate to http://server.local.ip.address:3100/ to access the web interface. (replace with the right IP address).

You can learn more about Docker by reading the official Docker documentation.

Windows

1. Download the appropriate release for your CPU architecture from the releases page on GitHub.
2. Extract the archive.
3. Run homebox.exe. This will start the server on port 7745.
4. You can test it by accessing http://localhost:7745.

Linux

1. Download the appropriate release for your CPU architecture from the releases page on GitHub.
2. Extract the archive.
3. Run the homebox executable.
4. The web interface will be accessible on port 7745 by default. Access the page by navigating to http://server.local.ip.address:7745/ (replace with the right ip address)

macOS

1. Download the appropriate release for your CPU architecture from the releases page on GitHub. (Use homebox_Darwin_x86_64.tar.gz for Intel-based macs and homebox_Darwin_arm64.tar.gz for Apple Silicon)
2. Extract the archive.
3. Run the homebox executable.
4. The web interface will be accessible on port 7745 by default. Access the page by navigating to http://local.ip.address:7745/ (replace with the right ip address)