Wiki > Homarr

Setup

Intro

Homarr is a customizable dashboard for your apps and services, with integrations for many popular apps such as Sonarr, Radarr and download clients.

The software will be configured in the /home/user/homarr directory.

You will need a port number to access Homarr. Port 20303 has been automatically generated for you, but you may use another 5 digit port between 10000 and 32767.

Installation

1. Connect to your slot through SSH

2. Create the directories needed for Homarr

    mkdir -p ~/homarr ~/homarr/appdata
   

3. Generate an encryption key. Homarr uses this to encrypt the passwords and API keys it stores. Copy the 64 character key it prints, you will need it in step 6

    openssl rand -hex 32
   

4. Create a compose file

    touch ~/homarr/docker-compose.yml
   

5. Edit the compose file

    nano ~/homarr/docker-compose.yml
   

6. Copy the following text, replacing your_encryption_key with the key you generated in step 3, and paste it into nano.

services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:latest
    ports:
      - 20303:7575
    volumes:
      - /home/user/homarr/appdata:/appdata
    environment:
      - SECRET_ENCRYPTION_KEY=your_encryption_key
    restart: unless-stopped

Save the file by pressing Ctrl+S then press Ctrl+X to exit nano

7. Start the compose file

    podman-compose -f ~/homarr/docker-compose.yml up -d
   

Accessing Homarr

You will be able to access Homarr at http://server.whatbox.ca:20303 roughly a minute after it starts. After installation, you will need to immediately access Homarr, complete the onboarding and set up your first administrator user.

When adding integrations, use the address the app is reachable at from your slot, such as http://server.whatbox.ca:port, rather than localhost.

Using SSL with a Managed App Link

If you want to access your Homarr instance with HTTPS access, add a custom app managed link named homarr with port 20303 and select Enable websockets (optional). Homarr will then be available at https://homarr.example.box.ca.

Updating Homarr

Shut down the container with

    podman-compose -f ~/homarr/docker-compose.yml down -t 300

and wait for it to shut down. Then, run

    podman-compose -f ~/homarr/docker-compose.yml pull

to download the latest program image. Then, start the container again

    podman-compose -f ~/homarr/docker-compose.yml up -d

Keep the same SECRET_ENCRYPTION_KEY when updating. If it changes, Homarr will not be able to read the passwords and API keys it has saved.

Removing Homarr

Shut down and remove the container with

    podman-compose -f ~/homarr/docker-compose.yml down -t 300

and wait for it to shut down. Then, remove the program image

    podman rmi ghcr.io/homarr-labs/homarr:latest

Finally, delete the Homarr directory. This permanently removes your Homarr boards, users and settings

    rm -rf ~/homarr