Skip to main content

Homarr

Homarr is a browser-based dashboard that integrates a wide variety of applications. With Homarr, you can access and control everything in one convenient location.

For more information about this app, follow this link.

Homarr is currently deployed as a BETA application on our servers. This means it cannot be installed from the UCP until we have concluded it to be stable on our infrastructure.

In the meantime, Homarr can be installed via SSH. Once we officially support Homarr, it needs to be re-installed from the UCP to show up on the Apps tab.

If you have feedback or need support regarding a beta application, we have a Beta Testing section on our Discord.

Initial Setup

  • Log in to your Ultra service via SSH
  • Once connected, initiate the installation of Homarr by executing the following command: 
app-homarr install -p '<your-password>'
  • If the installation was successful, you should see the below output in your SSH terminal
{"data": {"url": "https://homarr-ultradocs.hostname.usbx.me", "username": "ultradocs", "password": "kmRWdeCZnifj39gC598MXng3Hj7GyQwt", "version": "0.15.2", "port": 12345}, "result": true}
  • Take note of the URL in the above output, this is how you access the Homarr webUI.

Configuration

  • After the installation, access the webUI of Homarr by copying the URL from the installation procedure, and paste it into your browser.
  • You will be presented with a login form, log in with your Ultra service username and the password that you previously set during the installation.

  • Once you have successfully logged in, you will see your Homarr dashboard.
  • To add an application, click the Enter Edit Mode button in the top right corner.
    • While in edit mode, you can move the existing tiles by dragging them across the screen, or you can edit them by pressing the cog icon in the top right corner of the specific tile.
  • Next, to add an application, click the Add Tile icon in the top right corner.

  • A window will appear, where you can select what kind of tile you want to add. In this guide.
  • To add an application integration tile, click the Apps button.

  • After clicking the Apps button in the previous step, you will be presented with a new window where you need to enter the connection details for the application you want to add. We will use qBittorrent as an example, but the procedure is more or less the same for any other application.
  • The General and Integration tabs are the bare minimum that needs to be configured, the rest of the tabs are optional.

When adding the Internal & External address, make sure to not end the URL with /, as this could break the integration. Only use the main domain of your server.

Most applications use the internal address format of https://username.hostname.usbx.me/appname. Though some require the http://hostname-direct.usbx.me:PORT format. Make sure to replace username, hostname, and port with your specific details.

  • Let's begin with the General tab, enter the following:
    • App name: Name your application
    • Internal address: https://username.hostname.usbx.me/qbittorrent
    • External address: https://username.hostname.usbx.me/qbittorrent
  • Be sure to replace username and hostname with the specific details for your service.
  • Next, go to the Integration tab.

Some applications will require an API Key to authenticate instead of a username and password. For example, the *arr suite of applications will require an API Key, which most often can be found in Settings > General of the application you are integrating with Homarr. To integrate Plex, you will need to fetch your X-Plex-Token, instructions can be found here.

  • Under the Integration tab, begin by selecting qBittorrent from the Integration configuration drop-down menu.
  • In the Username field, enter your Ultra service username.
  • In the Password field, enter your qBittorrent password, which can be found on the UCP.
  • Lastly, click the Save button.

  • Do not forget to exit the tile edit mode by pressing the Exit and Save button in the top right corner of the Homarr dashboard.
  • You should now see a qBittorrent tile added on your Homarr dashboard. To add more app integration tiles, simply repeat the above procedure.

Set Dark/Light Theme

By default, Homarr will install with a light theme. To toggle between a dark and light theme, you need to access the application at container level. To achieve this, we have added an option to the install/upgrade command of Homarr. For example, to toggle a dark or light theme, follow the instructions provided below.

  • Connect to your Ultra service via SSH
  • Execute an install/upgrade action for Homarr:
    • Set dark theme: app-homarr upgrade --color-theme='dark'
    • Set light theme: app-homarr upgrade --color-theme='light'
Back to top