HomeBox

Appearance

Migration Guide ​

This guide will help you migrate from the original version of Homebox (https://github.com/hay-kot/homebox) to our actively maintained fork.

Why Migrate? ​

Migrating to our fork ensures you benefit from:

  • Active Development: The original Homebox has been archived and is no longer maintained, while our fork receives regular updates and bug fixes.
  • Community Support: Get help and advice on our Discord server or GitHub.
  • Improved Features: Enjoy enhancements and optimizations that make Homebox even better.

Prerequisites ​

Before starting the migration, ensure you have:

  • A working installation of hay-kot/homebox.
  • Docker and Docker Compose installed on your server (this guide assumes Docker is being used).

Migration Steps ​

1. Stop the Original Homebox Instance ​

To avoid conflicts during migration, shut down your existing hay-kot/homebox instance:

bash
docker compose down

2. Backup Your Data ​

This step is critical! Before proceeding, create a backup of your data to ensure nothing is lost.

WARNING

Don't skip this step! Backing up your data is the most important part of the migration process.

Locate the data folder used by your current Homebox installation and copy its contents to a safe location on your server. If you are using a data volume, follow the instructions on Docker's website.

3. Update the Docker Compose File ​

Modify your docker-compose.yml file to point to the new Homebox fork:

  • Replace:
    ghcr.io/hay-kot/homebox:latest
    With:
    ghcr.io/sysadminsmedia/homebox:latest

  • If you're using the rootless image, replace:
    ghcr.io/hay-kot/homebox:latest-rootless
    With:
    ghcr.io/sysadminsmedia/homebox:latest-rootless

  • Update the environment variable:

    • If you're using HBOX_STORAGE_SQLITE_URL, change it to HBOX_DATABASE_SQLITE_PATH.
    • If you're using HBOX_WEB_READ_TIMEOUT, HBOX_WEB_WRITE_TIMEOUT, or HBOX_IDLE_TIMEOUT, add an s for seconds or m for minutes to the end of the integers.

4. Start the New Homebox Instance ​

Launch the new version of Homebox with the following command:

bash
docker compose up -d

Once the service is running, access the web interface and verify:

  • All your data has been successfully migrated.
  • The service is functioning as expected.

Troubleshooting ​

If you run into any issues during the migration process, don't hesitate to reach out for help: