In this tutorial we'll learn how to install and configure Homer on Ubuntu 24.04 server.
What is Homer?
Homer is a lightweight, customizable homepage dashboard designed for teams and self-hosters who want a clean way to organize and access their services, tools, and applications from one central place. It runs as a static web application and can be hosted easily on any server, including a VPS or home lab setup.
Homer uses a single config.yml file for configuration, making it simple for us to add services, group them, apply themes, add icons, and personalize the interface without writing any code. It supports search, service grouping, custom logos, themes, bookmarks, and status indicators for services.
Prerequisites
Before we begin, ensure we have the following:
- An Ubuntu 24.04 dedicate server or KVM VPS.
- Basic Linux Command Line Knowledge.
- A domain name, pointing A record to server IP.
How to Install and Configure Homer on Ubuntu 24.04
Run these commands first to prepare the server:
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget git
If this is a fresh server, allow firewall for web access:
sudo apt install -y ufw
sudo ufw allow OpenSSH
sudo ufw allow 80,443/tcp
sudo ufw enable
Step 1: Install Docker on Ubuntu 24.04
Add Docker's official GPG key:
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 \
$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
Install Docker
sudo apt-get install docker-ce -y
Verify
docker --version
docker compose version
Log out and log back in so docker works without sudo.
Step 2: Create Homer Folder Structure
sudo mkdir -p /opt/homer/assets
sudo chown -R $USER:$USER /opt/homer
Step 3: Create Docker Compose File
Create Docker compose file:
nano /opt/homer/docker-compose.yml
Paste the following:
services:
homer:
image: b4bz/homer:latest
container_name: homer
restart: unless-stopped
ports:
- "8080:8080"
volumes:
- /opt/homer/assets:/www/assets
Save the file (CTRL+O, ENTER, CTRL+X).
Start Homer
cd /opt/homer
docker compose up -d
Step 4: Create Default Config File
We need the config file to customize the dashboard.
mkdir assets
nano /opt/homer/assets/config.yml
Example section to add a service card:
title: "Home"
subtitle: "Welcome"
logo: "logo.png"
theme: "default"
links:
- name: "Github"
icon: "fab fa-github"
url: "https://github.com/"
services:
- name: "General"
icon: "fas fa-server"
items:
- name: "Homer"
logo: "https://raw.githubusercontent.com/bastienwirtz/homer/main/public/logo.png"
subtitle: "Dashboard"
tag: "app"
url: "http://localhost:8080"
target: "_self"
- name: "Our Tools"
items:
- name: "Portainer"
url: "http://SERVER-IP:9000"
logo: "https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/portainer.png"
subtitle: "Docker Management"
target: "_self"
Save and refresh your dashboard page. No restart needed.
Step 5: Access Homer with Domain + HTTPS
If we want a domain like home.example.com, use Nginx Reverse Proxy:
Install Nginx:
sudo apt install -y nginx
Add Basic Auth with Host Nginx
Install htpasswd tool
sudo apt install -y apache2-utils
Create the password file
sudo htpasswd -c /etc/nginx/.htpasswd admin
Enter password when asked.
To add more users later (without overwriting):
sudo htpasswd /etc/nginx/.htpasswd anotheruser
Create config:
sudo nano /etc/nginx/sites-available/homer
Add:
server {
server_name home.example.com;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
auth_basic "Restricted Area";
auth_basic_user_file /etc/nginx/.htpasswd;
}
}
Replace home.example.com with your domain name.
Enable:
sudo ln -s /etc/nginx/sites-available/homer /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
Install SSL:
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d home.example.com
Step 6: Access Homer
Navigate to your browser and access:
https://home.example.com
You will see sample dashboard that we have added in config.yml file.
Step 7: Managing Homer
Stop container:
docker-compose down
Update to latest version:
docker-compose pull
docker-compose up -d
View logs:
docker logs -f homer
Conclusion
Setting up Homer on Ubuntu 24.04 is a smart way to build a clean and organized dashboard for our services. With Docker, the installation and updates remain simple, and the configuration stays fully under our control. Once configured, Homer makes our workflow faster by placing all important tools and apps in one beautifully designed interface.
