EP 22 - Homarr 1.0 Install/Upgrade

This episode is an update to episode 13 AND 14 due to Homarr's source code being redone.

What we will cover

!

This episode is good for FRESH INSTALLS AND those who are UPGRADING from the old Homarr Dashboard

1. Creating a new VM for the new Homarr Dashboard
2. How to create an API key for Proxmox usage stats.
3. How to install the new 1.0 Homarr dashboard
4. How to upgrade from the old dashboard to the new dashboard.
5. How to add trusted certificates to your dashboard
6. How to edit old Proxmox intergrations
7. How to create new Proxmox intergrations in the Homarr Dashboard

Getting started

Fresh Install Users

Create a new Ubuntu Server VM in Proxmox with the following:

1. OS: Ubuntu Server
2. 2gb of ram
3. 2 vcores,
4. 32gb of storage.

During install ensure you enable SSH!

On your new VM we need to install Docker and Homarr with the following commands:

SSH into your NEW homarr VM using the following command:

ssh <username>@<VM_ipaddress>

Adding the GPG keys and Docker repo:

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

Install the Latest Package:

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Ensure Docker is running after Install, you will get a response like this.

sudo docker run hello-world

If Docker hello fails do the following

if you do not get a response try

systemctl status docker.service

If that shows failed messages, try the following

sudo systemctl daemon-reload

sudo systemctl restart docker

Then try to see its status once again:

systemctl status docker.service

   

Install Docker Compose

Install Docker Compose with:

sudo apt install docker-compose

Verify that docker compose is installed

docker compose version

Install Homarr

Then create a docker compose file:

nano docker-compose.yml

Copy the following file config in there for your Homarr docker compose file.

#---------------------------------------------------------------------#
#     Homarr - A simple, yet powerful dashboard for your server.      #
#---------------------------------------------------------------------#
services:
  homarr:
    container_name: homarr
    image: ghcr.io/homarr-labs/homarr:latest
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # Optional, only if you want docker integration
      - ./homarr/appdata:/appdata
    environment:
      - SECRET_ENCRYPTION_KEY=51564af476c9eecd2efb30ed980a4b2e768efb7a558676859e2e1fbd04ce15a0
    ports:
      - '7575:7575'

To get out of the above editor you will do the following: To exit: ctrl + X

To confirm save: y

To confirm the file name you are saving to: enter

Then run the following to start it:

sudo docker compose up -d

Then to login to your machine you will type the following into your browser to access the panel:

ip_address:7575

Creating a Proxmox API Key

make new API key

1. Navigate to the Proxmox portal, click on Datacenter
2. Expand Permissions, click on Groups
3. Click the Create button

1. Name the group something informative, like api-users

1. Click on the Permissions "folder"
2. Click Add -> Group Permission

• Path: /
• Group: group from Step 4 above
• Role: PVEAuditor
• Propagate: Checked

1. Expand Permissions, click on Users
2. Click the Add button
   • User name: something informative like api
   • Realm: Proxmox VE authentication server
   • Password: create a secure password for the user
   • Confirm Password: re-enter the password
   • Group: group from Step 4 above

1. Expand Permissions, click on API Tokens
2. Click the Add button
   • User: user from Step 8 above
   • Token ID: something informative like the application or purpose like homarr
   • Privilege Separation: unchecked

1. Copy the Secret that is shown below because it is only shown once

1. Go back to the "Permissions" menu
2. Click Add -> API Token Permission

- Path: /
- API Token: select the API token created in Step 10
- Role: PVE Auditor
- Propagate: Checked

Adding your Certificate

Now we need to grab the Proxmox certificate.

1. Select the node where your Homarr Dashboard is located.
2. Select Certificates
3. Select the pve-root-ca.pem certificate
4. Click View certificate

Next we need to copy the contents to a notepad and then save the file as certificate_name.crt

Pasting it into Notepad

Saving it as a .crt file name

Now go over to your Homarr dashboard and on the top right click / your username bubble / Manage

Next go to: 1. Tools 2. Certificates 3. (top right) select add certificate 4. Add your saved certifcate 5. Click add.

showing the certificate added

You should now see a valid certificate

Adding Proxmox Stats Integration

Now we can go over to the Apps page and create a new app (this must be done before adding the integration)

Click new app

1. Now you can give it whatever name you want.
2. Search for the icon related to what you are connecting (in our case Proxmox)
3. grab the IP(URL) address of the Proxmox Node we want to see stats from.
4. Click create

Now go to the integrations tab: 1. New integration 2. Search and select Proxmox

This is where people struggle because this is the major change from the old Homarr panel

We are going to go grab the correct information from Proxmox for the username, token ID, API key, and realm.

Over on Proxmox:

1. Go to the data center at the top
2. Go to API Token
3. We will see the username
4. We will see the Token name

Go back over to Homarr and fill out that respective information in the username and token ID field. Remember you also need to paste your API key you created under the (make a new API key) section.

Lastly we just need to get the realm.

Your realms are found under datacenter / realms. We are going ot be using PVE so our real will be PVE.

like so:

Then test connection and connect.

Click the Homarr logo at the top left to go back to your main dashboard OR (Boards on the far right, then select your dashboard from there)

On the top right click the pencil icon to edit your dashboard (it won't look like ours below)

Now you will notice all your icons have three dots on the top right and your board is now editable.

There will be a + icon on the top right, click that and then select new item.

Under the items we need to select (System Health Monitoring) and click add to board

Now on our dashboard page we will see that new section with no data, click the three dots on the right and click edit item.

From the integrations drop down menu select the integration we just created, and click save changes.

Now you can see we have the Proxmox stats on our dashboard!

The fresh install tutorial is now over

Upgrade path for old users

Create a new Homarr VM

Create a new Ubuntu Server VM in Proxmox with the following:

1. OS: Ubuntu Server
2. 2gb of ram
3. 2 vcores,
4. 32gb of storage.

During install ensure you enable SSH!

On your new VM we need to install Docker and Homarr with the following commands:

SSH into your NEW homarr VM using the following command:

ssh <username>@<VM_ipaddress>

Adding the GPG keys and Docker repo:

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

Install the Latest Package:

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Ensure Docker is running after Install, you will get a response like this.

sudo docker run hello-world

If Docker hello fails do the following

if you do not get a response try

systemctl status docker.service

If that shows failed messages, try the following

sudo systemctl daemon-reload

sudo systemctl restart docker

Then try to see its status once again:

systemctl status docker.service

   

Install Docker Compose

Install Docker Compose with:

sudo apt install docker-compose

Verify that docker compose is installed

docker compose version

Install Homarr

Then create a docker compose file:

nano docker-compose.yml

Copy the following file config in there for your Homarr docker compose file.

#---------------------------------------------------------------------#
#     Homarr - A simple, yet powerful dashboard for your server.      #
#---------------------------------------------------------------------#
services:
  homarr:
    container_name: homarr
    image: ghcr.io/homarr-labs/homarr:latest
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # Optional, only if you want docker integration
      - ./homarr/appdata:/appdata
    environment:
      - SECRET_ENCRYPTION_KEY=51564af476c9eecd2efb30ed980a4b2e768efb7a558676859e2e1fbd04ce15a0
    ports:
      - '7575:7575'

To get out of the above editor you will do the following: To exit: ctrl + X

To confirm save: y

To confirm the file name you are saving to: enter

Then run the following to start it:

sudo docker compose up -d

Then to login to your machine you will type the following into your browser to access the panel:

ip_address:7575

Exporting your old dashboard

login to your OLD Homarr Dashboard, click the username top right, clicked manage, under settings go to tools, migrate to 1.0

here is how you get to that menu:

Select export data (copy your encryption key to your notes!!!!) and ensure you also select keep on the top right of your browser if it tries to block it.

Going over to your fresh VM you just created, click (import from Homarr before 1.0)

After selecting your .zip file you will be presented with the screen below. We are not changing ANY of the settings, simply click (confirm import and continue)

Now paste that encryption key so Homarr and unzip your old dashboard.

We wont be changing any of the settings here but you can turn off (send anonymous analytics) if you want.

You will be presented with the following screen, we are going to select (go to default-large board)

You may then be prompted to login, you will do this with the credentials of your old dashboard (because now its really your new dashboard)

Now we are going to select (configure server-wide home dashboard) this is where we will set the default dashboard when you login.

Find your old dashboards, click the three dots, then select (set as your home board)

Now you have your dashboard back!

Adding your Certificate

Now we need to grab the Proxmox certificate.

1. Select the node where your Homarr Dashboard is located.
2. Select Certificates
3. Select the pve-root-ca.pem certificate
4. Click View certificate

Next we need to copy the contents to a notepad and then save the file as certificate_name.crt

Pasting it into Notepad

Saving it as a .crt file name

Now go over to your Homarr dashboard and on the top right click / your username bubble / Manage

Next go to: 1. Tools 2. Certificates 3. (top right) select add certificate 4. Add your saved certifcate 5. Click add.

showing the certificate added

You should now see a valid certificate

Adding Proxmox Stats Integration

Now we can go over to the Apps page and create a new app (this must be done before adding the integration)

Click new app

1. Now you can give it whatever name you want.
2. Search for the icon related to what you are connecting (in our case Proxmox)
3. grab the IP(URL) address of the Proxmox Node we want to see stats from.
4. Click create

Now go to the integrations tab: 1. New integration 2. Search and select Proxmox

This is where people struggle because this is the major change from the old Homarr panel

We are going to go grab the correct information from Proxmox for the username, token ID, API key, and realm.

Over on Proxmox:

1. Go to the data center at the top
2. Go to API Token
3. We will see the username
4. We will see the Token name

Go back over to Homarr and fill out that respective information in the username and token ID field. Remember you also need to paste your API key you created under the (make a new API key) section.

Lastly we just need to get the realm.

Your realms are found under datacenter / realms. We are going ot be using PVE so our real will be PVE.

like so:

Then test connection and connect.

Click the Homarr logo at the top left to go back to your main dashboard OR (Boards on the far right, then select your dashboard from there)

On the top right click the pencil icon to edit your dashboard (it won't look like ours below)

Now you will notice all your icons have three dots on the top right and your board is now editable.

There will be a + icon on the top right, click that and then select new item.

Under the items we need to select (System Health Monitoring) and click add to board

Now on our dashboard page we will see that new section with no data, click the three dots on the right and click edit item.

From the integrations drop down menu select the integration we just created, and click save changes.

Now you can see we have the Proxmox stats on our dashboard!

Follow Us on Social Media

YouTube

Discord

Reddit

Rumble