In this tutorial we'll learn how to install and configure Homer on AlmaLinux 10 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 AlmaLinux 10 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 AlmaLinux 10
Step 1: Update Server Packages
Regularly updating our server ensures stability and security.
sudo dnf update -y
sudo dnf upgrade -y
Step 2: Install Docker and Docker Compose
Homer runs best using Docker for clean, isolated deployment.
sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io
Enable and start Docker:
sudo systemctl enable --now docker
Check Docker status:
sudo systemctl status docker
Step 3: Create Homer Folder Structure
sudo mkdir -p /opt/homer/assets
sudo chown -R $USER:$USER /opt/homer
Step 4: 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 5: Create Default Config File
We need the config file to customize the dashboard.
mkdir assets
vi /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 6: Allow Firewall Access (If Required)
sudo firewall-cmd --permanent --add-port={80,443}/tcp
sudo firewall-cmd --reload
Configure SELinux (If enabled)
sudo setsebool -P httpd_can_network_connect 1
Step 7: Configure Nginx Reverse Proxy
Install Nginx:
sudo dnf install -y nginx
sudo systemctl enable --now nginx
Create an Nginx config file:
sudo nano /etc/nginx/conf.d/homer.conf
Add:
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://127.0.0.1:8080;
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;
}
}
Replace example.com with your domain name.
Test and reload Nginx:
sudo nginx -t
sudo systemctl reload nginx
From now on, Homer opens without specifying port 8080.
Step 8: Secure Homer with Password Authentication (Basic Auth)
This adds a login prompt before anyone can access the dashboard.
Install the htpasswd tool:
sudo dnf install -y httpd-tools
Create the password file (replace admin with preferred username):
sudo htpasswd -c /etc/nginx/.htpasswd admin
To add more users later:
sudo htpasswd /etc/nginx/.htpasswd username
Edit the Nginx config to enable authentication:
sudo nano /etc/nginx/conf.d/homer.conf
Update the location block:
location / {
auth_basic "Protected Dashboard";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://127.0.0.1:8080;
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;
}
Test and reload:
sudo nginx -t
sudo systemctl reload nginx
Now the dashboard is protected by credentials.
Step 9: Enable HTTPS with SSL Certificate
Install Certbot:
sudo dnf install -y certbot python3-certbot-nginx
Run SSL auto-configuration (requires domain DNS pointed to server):
sudo certbot --nginx -d example.com
Certbot configures SSL automatically.
Step 10: Access Homer
Navigate to your browser and access:
https://example.com
Step 11: 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 AlmaLinux 10 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.
