Author	Nejat Hakan
eMail	nejat.hakan@outlook.de
PayPal Me	https://paypal.me/nejathakan

Personal Dashboard - Homer

Introduction to Homer

Welcome to the world of self-hosted personal dashboards! In this comprehensive guide, we will delve into Homer, an incredibly popular, simple, and elegant static dashboard application. Our goal is to provide you, as university students eager to learn, with a deep understanding of Homer, from its basic setup to advanced customizations. By the end of this guide, you'll not only understand Homer thoroughly but will also have built and customized your own functional dashboard.

What is Homer?

Homer is a free and open-source, static HTML/JS & YAML configured dashboard. Think of it as a super-fast, highly customizable homepage for all your web services, applications, and important links, whether they are hosted locally on your network (your "homelab") or are external websites you frequently visit. Being "static" means that once Homer is configured, it generates HTML, CSS, and JavaScript files that can be served by any simple web server. This makes it incredibly lightweight, fast, and easy to deploy, typically using Docker.

The "YAML configured" part is crucial. YAML (YAML Ain't Markup Language) is a human-readable data serialization standard. Homer uses a config.yml file where you define all aspects of your dashboard – its title, the services you want to link to, their icons, how they are grouped, and the theme. This approach makes configuration straightforward and version-controllable (you can track changes to your config.yml using tools like Git).

Why Use a Personal Dashboard?

In an increasingly digital world, we interact with a multitude of web services daily. These might include:

Self-hosted applications: Plex for media, Nextcloud for files, Home Assistant for smart home control, Pi-hole for ad-blocking, and various development tools.
Network devices: Router admin pages, NAS interfaces, modem status pages.
Frequently visited websites: University portals, email, news sites, documentation, search engines.
Cloud services: Cloud storage dashboards, project management tools.

Keeping track of all these URLs, especially those with complex local IP addresses or specific ports, can be cumbersome. Bookmarks help, but a dedicated dashboard offers several advantages:

Centralization: A single, visually organized page to access everything.
Accessibility: Easily accessible from any device on your network (or even the internet, if configured securely).
Customization: Tailor the look and feel to your preferences and needs.
Efficiency: Save time by having all your important links in one place, often with status indicators.
Visual Appeal: A well-designed dashboard is simply pleasant to use.

For students, especially those in technical fields, a personal dashboard can be an invaluable tool for organizing access to development environments, research tools, university resources, and personal projects. It can also be a fantastic entry point into the world of self-hosting and understanding web technologies.

Homer's Key Features

Homer stands out due to its simplicity and focused feature set:

Lightweight and Fast: Being static, it loads almost instantly.
Easy Configuration: Uses a single YAML file (config.yml) for all settings.
Docker-Friendly: Officially supported Docker image makes deployment a breeze.
Customizable:
- Add services with names, subtitles, icons (Font Awesome, Material Design Icons, or custom image URLs), and URLs.
- Group services logically.
- Multiple built-in themes and support for custom themes via CSS.
- Custom background images.
- Customizable layout options (columns, search bar visibility).
Connectivity Check: Optionally, Homer can ping services to indicate if they are online.
Search/Filtering: Quickly find services on your dashboard.
Internationalization (i18n): Support for multiple languages.
Responsive Design: Works well on desktops, tablets, and mobile phones.
No Database Required: Simplifies setup and maintenance.

Alternatives to Homer

While Homer is excellent for its simplicity, it's good to be aware of alternatives, each with different strengths:

Heimdall Application Dashboard: More feature-rich, with built-in integrations for many popular applications (e.g., showing live stats from Sonarr/Radarr). It's PHP-based and requires a web server with PHP. More dynamic than Homer.
Organizr: Aims to be an "all-in-one" HTPC/Homelab server organizer. It's also PHP-based and offers more features like user management, SSO, and deeper integrations. Can be more complex to set up.
Dashy: Highly customizable, visually rich, and feature-packed. Offers status checking, widgets, themes, and configuration via UI or YAML. Node.js based.
Flame: Another simple and clean dashboard, similar in spirit to Homer. Configuration via Docker environment variables or a UI after setup. Go-based.
SUI (Startpage User Interface): A very minimalistic startpage.

The choice often comes down to your specific needs. If you want something dead simple, fast, and easy to configure with YAML for basic link aggregation, Homer is an outstanding choice. If you need more dynamic content, integrations, or user management, one of the alternatives might be more suitable. For this guide, we are focusing on Homer's elegant simplicity.

Workshop - Exploring the Homer Demo

Before we dive into installing Homer ourselves, let's explore the official demo. This will give you a feel for what a Homer dashboard looks like and how it functions.

Project Goal:
Familiarize yourself with the Homer interface and its typical features by interacting with the official demo.

Steps:

Access the Demo:
- Open your web browser (e.g., Chrome, Firefox, Safari, Edge).
- Navigate to the official Homer demo page. A quick web search for "Homer dashboard demo" should lead you to it, or you can often find a link on their GitHub repository (search "bastienwirtz homer github"). A common demo link might be https://homer-demo.netlify.app/.
Initial Observation:
- Notice the overall layout: title, subtitle, search bar (if enabled), and service cards.
- Observe how services are grouped. In the demo, you might see groups like "Applications," "Network," etc.
Interact with Services:
- Hover over different service cards. Notice any tooltips or changes in appearance.
- Click on a few service links. Since this is a demo, some links might be placeholders and not lead to actual services, or they might lead to the respective project pages. The key is to see how the linking mechanism works.
Test the Search Bar:
- If a search bar is present, try typing the name of a service or a keyword.
- Observe how the dashboard filters the displayed services to match your search query. This is very useful for dashboards with many items.
Examine Service Details:
- Look closely at individual service cards. Note the elements:
  - Icon: See the variety of icons used.
  - Name: The primary identifier for the service.
  - Subtitle/Tag: Additional descriptive text or tags.
  - Status Indicator: Some services might have a small dot or indicator. If connectivity check is enabled and working, this would show if the service is online (green) or offline (red). The demo might not have live connectivity checks for external services.
Responsive Design (Optional):
- If you are on a desktop browser, try resizing the browser window to be narrower, like a mobile phone screen.
- Notice how the layout adapts. Service cards might reflow into fewer columns or a single column. This demonstrates Homer's responsiveness.
- Alternatively, you can use your browser's Developer Tools (usually F12) to emulate different mobile devices.
Reflect on What You See:
- Think about how you might use such a dashboard for your own services and links.
- Consider what kind of services you would add and how you would group them.
- This exploration provides a visual target for what we will build in the subsequent sections.

By completing this workshop, you've gained a practical first look at Homer's user interface and core functionality. This visual understanding will be beneficial as we proceed to install and configure your very own Homer instance.

1. Basic Setup and Configuration

This section will guide you through the fundamental steps of getting Homer up and running. We'll cover the prerequisites, installation using Docker (the most common and recommended method), understanding the basic structure of its configuration file, and performing initial customizations to create a simple, functional dashboard.

Prerequisites for Homer Installation

Before we jump into installing Homer, let's ensure you have the necessary tools and foundational knowledge. Homer itself is lightweight, but its typical deployment method relies on Docker.

Understanding Docker and Docker Compose

What is Docker?
Docker is an open platform for developing, shipping, and running applications. It enables you to separate your applications from your infrastructure so you can deliver software quickly. At its core, Docker uses containers.
- Images: A Docker image is a lightweight, standalone, executable package that includes everything needed to run a piece of software, including the code, runtime, libraries, environment variables, and configuration files. Think of it as a blueprint or a template.
- Containers: A container is a runnable instance of an image. You can create, start, stop, move, or delete containers using Docker API or CLI. Containers isolate applications from one another and from the underlying infrastructure. This means a Homer container will run in its own isolated environment, not interfering with other software on your system, and all its dependencies are self-contained.
Why use Docker for Homer?
- Simplicity: Instead of manually installing a web server, configuring it, and deploying Homer's files, you just run the official Homer Docker image.
- Consistency: Homer will run the same way regardless of your operating system (Linux, macOS, Windows) as long as Docker is installed.
- Isolation: Homer and its dependencies are self-contained, preventing conflicts.
- Portability: Easy to move your Homer setup to another machine with Docker.
- Updates: Updating Homer is often as simple as pulling the new image and restarting the container.
What is Docker Compose?
Docker Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file (typically docker-compose.yml) to configure your application's services. Then, with a single command, you create and start all the services from your configuration. While Homer can be run with a single docker run command, using Docker Compose is highly recommended for a more manageable and declarative setup, especially when you want to persist configuration or manage network settings easily. It allows you to define:
- The image to use (e.g., b4bz/homer).
- Port mappings (e.g., mapping a port on your host machine to the port Homer runs on inside the container).
- Volume mounts (e.g., linking a directory on your host machine to the /www/assets directory inside the container where Homer expects its config.yml). This is crucial for persisting your configuration.
- Restart policies (e.g., ensuring Homer automatically restarts if it crashes or if the system reboots).

Installation:

Docker: You'll need Docker installed on your system (Linux, Windows, or macOS). Installation instructions vary by OS. Visit the official Docker website (docker.com) for guides. For Linux, it usually involves adding Docker's official repository and installing the docker-ce (Community Edition) package.

# Example for Ubuntu/Debian:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt update
sudo apt install docker-ce
sudo usermod -aG docker ${USER} # Add your user to the docker group to run docker without sudo
# You'll need to log out and log back in for this group change to take effect.

Docker Compose: For Docker Compose V2 (integrated into Docker CLI), it's usually installed with Docker. You can check with docker compose version. For older V1 (standalone docker-compose), you might need to install it separately.

# Check if Docker Compose V2 is available
docker compose version
# If not, or if you prefer V1 (though V2 is recommended)
# sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
# sudo chmod +x /usr/local/bin/docker-compose
# docker-compose --version

Ensure Docker is running before proceeding: sudo systemctl status docker (Linux).

Basic Linux Command Line Familiarity

Since we'll be using Docker primarily from the command line (especially on Linux servers), some basic familiarity is essential:

Navigating directories (cd).
Listing files (ls).
Creating directories (mkdir).
Creating and editing files (using a text editor like nano, vim, or gedit).
Basic Docker commands (which we will cover).

If you are on Windows or macOS, Docker Desktop provides a graphical interface, but understanding the command line is still beneficial.

Text Editor for Configuration

You will need a text editor to create and modify Homer's config.yml file and the docker-compose.yml file.

Command-line editors (Linux): nano (beginner-friendly), vim (powerful but steeper learning curve).
GUI editors (all platforms): VS Code (Visual Studio Code - highly recommended for its YAML support and Docker integration), Sublime Text, Notepad++, Atom.

Choose one you are comfortable with. VS Code is an excellent choice as it often has extensions that can help with YAML syntax.

Installation using Docker

The official Homer image is b4bz/homer. We will explore two ways: a simple docker run command for a quick start, and then a more robust docker-compose setup.

Pulling the Homer Docker Image

Before running, you can optionally pull the image to ensure you have the latest version locally:

docker pull b4bz/homer

This step downloads the Homer image from Docker Hub. If you skip this, Docker will automatically pull it when you try to run a container from the image for the first time.

Running Homer with a Simple Docker Command

This command will start Homer with a default configuration. It's good for a quick test but not ideal for persistent configuration.

docker run -d \
  -p 8080:8080 \
  --name homer \
  b4bz/homer

Let's break this command down:

docker run: The command to create and start a new container.
-d: Detached mode. Runs the container in the background and prints the container ID. Without this, your terminal would be attached to the container's logs.
-p 8080:8080: Port mapping. This maps port 8080 on your host machine to port 8080 inside the Homer container (which is the port Homer listens on by default). You can change the host port if 8080 is already in use (e.g., -p 8989:8080 would make Homer accessible on your host at port 8989).
--name homer: Assigns a name ("homer") to your container. This makes it easier to manage (e.g., docker stop homer). If you don't specify a name, Docker assigns a random one.
b4bz/homer: The name of the Docker image to use.

After running this command, wait a few seconds for Homer to start. You should then be able to access it in your web browser at http://localhost:8080 (if running Docker locally) or http://<your-server-ip>:8080 (if running Docker on a remote server). You'll see the default Homer dashboard.

Important Note:
With this simple command, any changes you make to the dashboard (if Homer allowed direct UI editing, which it doesn't for its core config) or if you wanted to use a custom config.yml, they wouldn't persist if you remove the container. The configuration is inside the container. To make your configuration persistent and customizable, we need to use volume mounts, which is best managed with Docker Compose.

To stop and remove this temporary container:

docker stop homer
docker rm homer

Understanding Homer's Configuration File (`config.yml`)

The heart of your Homer dashboard is the config.yml file. This YAML file tells Homer what to display and how. By default, Homer looks for this file inside its container at /www/assets/config.yml. To customize Homer, you'll create your own config.yml on your host system and "mount" it into the container.

Let's look at the basic structure. YAML is syntax-sensitive, especially with indentation (usually 2 spaces, no tabs).

# config.yml

# Page metadata
title: "My Awesome Dashboard"
subtitle: "Homer"
# documentTitle: "Welcome" # Customize the browser tab title
logo: "assets/logo.png" # URL or path to a logo file
# You can also use a Font Awesome icon as a logo:
# logo: "fas fa-rocket"

# Optional: Use a custom favicon
# favicon: "assets/favicon.ico"

# Optional: Set a background image
# background: "assets/background.jpg" # URL or path to a background image

# Optional: Define a header style (true or false)
header: true

# Optional: Define a footer
# footer: '<p>Created with <span class="has-text-danger">❤️</span> with <a href="https://bulma.io/">Bulma</a>, <a href="https://vuejs.org/">Vuejs</a> & <a href="https://fontawesome.com/">Font Awesome</a></p>' # HTML Content

# Optional: Define custom CSS and JS files
# Refer to https://github.com/bastienwirtz/homer/blob/main/docs/customization.md#custom-css--js
# customCSS: "assets/custom.css"
# customJS: "assets/custom.js"

# Optional: Define a theme. If not set, the default "default" theme is used.
# theme: default # Available themes: default, light, dark, dark-blur, searx, Dracula, Nord, Solarized Dark

# Optional: Define a columns layout for services.
# columns: "3" # "1", "2", "3", "4", "5", "6"

# Optional: Define services an array of items
# Services are displayed grouped by "type"
# The order of groups is defined by the order in the config
services:
  - name: "Applications" # Name of the group
    icon: "fas fa-cloud" # Optional icon for the group
    # Optional: You can set a custom background color for the group
    # background: "#212529" # Dark background color
    items:
      - name: "Awesome Application 1"
        logo: "assets/tools/some-logo.png" # Can be a path to an image in 'assets' or a full URL
        # Or use an icon:
        # icon: "fas fa-code-branch"
        subtitle: "Bookmark example"
        tag: "app" # Optional tag
        url: "https://www.reddit.com/r/selfhosted/"
        target: "_blank" # Optional: "_blank" to open in a new tab, "_self" in the same tab (default)

      - name: "Another Application"
        icon: "fab fa-gitlab"
        subtitle: "Another web service"
        url: "https://gitlab.com/"
        # Optional: Add a connectivity check
        # type: "Ping" # For a simple HTTP GET request
        # status: "200" # Expected status code for "up"

  - name: "Network Utilities"
    icon: "fas fa-server"
    items:
      - name: "Router"
        icon: "fas fa-network-wired"
        subtitle: "Access your router"
        url: "http://192.168.1.1" # Replace with your router's IP

# Optional: Define an array of links for the footer, or header if header is false
# links:
#   - name: "GitHub"
#     icon: "fab fa-github"
#     url: "https://github.com/bastienwirtz/homer"
#     target: "_blank" # optional html a tag target attribute

Core Structure - title, subtitle, logo, etc.

title: The main title displayed at the top of your dashboard.
subtitle: A smaller text line below the title.
logo: Path to a logo image (e.g., assets/logo.png which would be /www/assets/logo.png inside the container) or a Font Awesome icon class (e.g., fas fa-rocket).
favicon: Path to a custom favicon for the browser tab.
background: Path or URL to a background image for the dashboard.
header: true or false. Controls the display of the header section.
footer: Custom HTML content for the footer.
customCSS / customJS: Paths to custom CSS or JavaScript files for advanced customization.
theme: Specifies the theme to use (e.g., default, dark, light).
columns: Defines the number of columns for service items (e.g., "3" or "4").

Defining Services

The services key holds an array (list) of service groups.

Each item in the services array is a group.
- name: The displayed name for the group (e.g., "Applications", "Network Utilities").
- icon: An optional Font Awesome icon for the group header.
- items: An array of actual service entries within that group.
  - Each item in this items array represents a single service link.
    - name: The name of the service (e.g., "My NAS", "Plex").
    - logo or icon: Path to an image for the service (e.g., assets/tools/plex.png) or a Font Awesome/MDI icon class (e.g., fas fa-server). If both are provided, logo often takes precedence.
    - subtitle: A short description displayed below the service name.
    - tag: An optional small label/tag for the service, can be styled.
    - url: The URL the service links to.
    - target: How the link opens: _blank (new tab) or _self (same tab, default).
    - type and status: Used for connectivity checks (more on this in Intermediate).

Defining Links

The links key (optional) allows you to add a list of quick links, typically displayed in the footer or header. Each link has:

name: Display text for the link.
icon: Optional Font Awesome icon.
url: The URL the link points to.
target: _blank or _self.

Initial Customization

Now, let's set up Homer with Docker Compose and create our first custom config.yml.

Create a Directory for Homer:
On your host machine, create a directory where you'll store your Homer configuration.
```
mkdir ~/homer_dashboard
cd ~/homer_dashboard
```
Inside this directory, we'll create two files: docker-compose.yml and (inside an assets subdirectory) config.yml.
Create docker-compose.yml:
Create a file named docker-compose.yml in the ~/homer_dashboard directory with the following content:
```
version: "3.3" # Specifies the Docker Compose file format version

services:
  homer:
    image: b4bz/homer # The Docker image to use
    container_name: homer # A friendly name for your container
    volumes:
      - ./assets:/www/assets # Mounts the local './assets' directory to '/www/assets' in the container
    ports:
      - "8080:8080" # Maps port 8080 on the host to port 8080 in the container
    # user: "1000:1000" # Optional: Run as a specific user/group (UID:GID). Useful for file permissions.
                       # Replace 1000:1000 with your actual UID and GID (use `id` command in Linux).
    restart: unless-stopped # Policy to restart the container unless it's manually stopped
    environment:
      - INIT_ASSETS=1 # Tells Homer to copy default assets if /www/assets is empty on first run.
                      # This can be useful to get default icons/logos if you don't have them yet.
                      # Set to 0 or remove after initial setup if you manage all assets yourself.
      # - TZ=Europe/London # Optional: Set your timezone
```
Explanation of docker-compose.yml:
- version: "3.3": Defines the version of the Compose file format.
- services:: Defines the different application services. We only have one, homer.
- image: b4bz/homer: Specifies the Docker image.
- container_name: homer: Names the container.
- volumes: - ./assets:/www/assets: This is crucial. It maps a subdirectory named assets (which we will create in ~/homer_dashboard) to the /www/assets directory inside the Homer container. This is where Homer looks for config.yml, custom CSS, logos, etc. Your changes in the local assets directory will be reflected inside the container.
- ports: - "8080:8080": Exposes Homer on port 8080 of your host machine.
- restart: unless-stopped: Ensures Homer restarts automatically if it crashes or if the Docker daemon restarts (e.g., after a system reboot), unless you explicitly stop it.
- environment: - INIT_ASSETS=1: This is a helpful feature of the b4bz/homer image. If the mounted /www/assets directory is empty on the first run, Homer will copy its default assets (including a sample config.yml, default logo, etc.) into it. This gives you a starting point. After the first run, you'll typically manage these files yourself, so you might set it to 0 or remove it.

Create the assets Directory and Initial config.yml:
In your ~/homer_dashboard directory, create the assets subdirectory:

mkdir assets
cd assets

Now, create your first config.yml file inside ~/homer_dashboard/assets/ with some basic content. You can start with the example below, or copy and modify the one provided in the previous subsection.

File: ~/homer_dashboard/assets/config.yml

# Page metadata
title: "My First Dashboard"
subtitle: "Homer Rocks!"
logo: "fas fa-home" # Using a Font Awesome icon as a logo

# Services
services:
  - name: "Useful Links"
    icon: "fas fa-link"
    items:
      - name: "Google"
        icon: "fab fa-google"
        subtitle: "Search the web"
        url: "https://www.google.com"
        target: "_blank"

      - name: "My University"
        icon: "fas fa-university"
        subtitle: "University Portal"
        url: "https://www.example-university.com" # Change to your university's URL
        target: "_blank"

  - name: "My Local Services"
    icon: "fas fa-server"
    items:
      - name: "Router Admin"
        icon: "fas fa-network-wired"
        subtitle: "Access router settings"
        url: "http://192.168.1.1" # Change if your router IP is different

Launch Homer with Docker Compose:
Navigate back to the ~/homer_dashboard directory (where your docker-compose.yml is located):
```
cd ~/homer_dashboard
```
Then, run:
```
docker compose up -d
```
- docker compose up: This command builds (if necessary), (re)creates, starts, and attaches to containers for a service.
- -d: Runs containers in detached mode (in the background).
If this is the first time, Docker Compose will pull the b4bz/homer image and then create and start the container according to your docker-compose.yml. Because INIT_ASSETS=1 was set and if your assets folder was empty or didn't have a config.yml, Homer would copy default files. Since we created one, it should use ours.
Access Your Dashboard:
Open your web browser and go to http://localhost:8080 or http://<your-server-ip>:8080. You should see your customized Homer dashboard with the title "My First Dashboard" and the services you defined!

Changing the Title and Subtitle

To change the title or subtitle:

Open ~/homer_dashboard/assets/config.yml in your text editor.

Modify the title: and subtitle: lines.

title: "John Doe's Homelab Central"
subtitle: "All my services in one place"

Save the config.yml file.
Refresh your browser window where Homer is open. The changes should appear almost instantly because Homer re-reads the config.yml (or the browser cache needs a hard refresh - Ctrl+Shift+R or Cmd+Shift+R). The b4bz/homer container is set up to watch for changes in config.yml and reload automatically. If not, a container restart might be needed for some structural changes, but often text/link changes are live. If changes don't appear, you might need to restart the container:
```
docker compose restart homer
```
Or, for a more forceful update:
```
docker compose down
docker compose up -d
```

Adding Your First Services

Let's add another service. Suppose you have a self-hosted file service like Nextcloud running at http://192.168.1.100:80.

Edit ~/homer_dashboard/assets/config.yml.
Find the services: section and the group where you want to add Nextcloud (e.g., "My Local Services").

Add a new item to the items: list for that group:

# ... (other parts of config.yml)
  - name: "My Local Services"
    icon: "fas fa-server"
    items:
      - name: "Router Admin"
        icon: "fas fa-network-wired"
        subtitle: "Access router settings"
        url: "http://192.168.1.1"

      - name: "Nextcloud"             # New service
        icon: "fas fa-cloud"         # Or use a specific Nextcloud logo if you have one
        subtitle: "My Personal Cloud"
        url: "http://192.168.1.100:80"
# ...

Save the file and refresh Homer in your browser. Your new Nextcloud link should appear.

Adding External Links

This is done exactly like adding services. External links are just services whose URLs point to external websites. You've already done this with Google and your university portal in the example config.yml.

Workshop - Building Your First Simple Dashboard

Project Goal:
Create a functional Homer dashboard using Docker Compose, featuring at least three personally relevant local/hypothetical services and three useful external links.

Steps:

Prerequisites Check:
- Ensure Docker and Docker Compose are installed and running on your system.
- If you haven't added your user to the docker group on Linux, you might need to prefix docker and docker compose commands with sudo. It's recommended to add your user to the group and log out/in.
Set up Project Directory:
- Create a main directory for your Homer project, for example, my_homer_dashboard.
```
mkdir ~/my_homer_dashboard
cd ~/my_homer_dashboard
```
- Inside my_homer_dashboard, create an assets subdirectory.
```
mkdir assets
```

Create docker-compose.yml:

Inside ~/my_homer_dashboard, create a file named docker-compose.yml.

Populate it with the following content:

version: "3.3"

services:
  homer:
    image: b4bz/homer
    container_name: my-homer-instance # You can choose a custom container name
    volumes:
      - ./assets:/www/assets
    ports:
      - "8088:8080" # Using host port 8088 to avoid conflict if 8080 is used
    restart: unless-stopped
    environment:
      - INIT_ASSETS=0 # Set to 0 as we are providing our own config from the start
      # - TZ=America/New_York # Optional: Set your timezone

Note: I've used port 8088 on the host side in this example. Adjust as needed. If 8080 is free on your host, you can use 8080:8080.

Create Your Initial config.yml:

Inside the ~/my_homer_dashboard/assets/ directory, create a file named config.yml.

Start with a basic structure:

# Page metadata
title: "My Personal Hub"
subtitle: "Student Edition"
# logo: "assets/logo.png" # We'll use a Font Awesome icon for now
logo: "fas fa-user-astronaut"
header: true
theme: "default" # Start with the default theme

# Services
services:
  - name: "My Homelab"
    icon: "fas fa-server"
    items:
      # We will add local services here

  - name: "Online Resources"
    icon: "fas fa-globe"
    items:
      # We will add external links here

Define Title, Subtitle, and Logo (Already in config.yml):
- You've already set a title, subtitle, and a Font Awesome logo (fas fa-user-astronaut). Feel free to change the icon to something else from Font Awesome (e.g., fas fa-book-reader, fas fa-laptop-code). You can browse icons on the Font Awesome website.

Add Three Hypothetical Local Services:

Let's assume you're planning to self-host (or already have) some services.

Edit ~/my_homer_dashboard/assets/config.yml and add three items under the "My Homelab" group.

# ... (metadata) ...
services:
  - name: "My Homelab"
    icon: "fas fa-server"
    items:
      - name: "My NAS"
        icon: "fas fa-hdd" # Hard Drive icon
        subtitle: "Network Attached Storage"
        url: "http://192.168.1.50" # Replace with your actual NAS IP if you have one
        tag: "Storage"

      - name: "Router Config"
        icon: "fas fa-network-wired"
        subtitle: "Network Settings"
        url: "http://192.168.0.1" # Replace with your router's IP
        tag: "Network"

      - name: "Pi-hole"
        icon: "fas fa-shield-alt" # Shield icon for ad-blocker
        subtitle: "DNS Ad Blocker"
        url: "http://192.168.1.53/admin" # Example Pi-hole URL
        tag: "Network"
# ... (Online Resources group will follow) ...

Choose icons from Font Awesome (use their website to search for free icons; look for classes like fas fa-something or fab fa-brandname).

Add Three Useful External Links:

Under the "Online Resources" group in your config.yml, add three external links relevant to you.

# ... (My Homelab group) ...
  - name: "Online Resources"
    icon: "fas fa-globe"
    items:
      - name: "My University Portal"
        icon: "fas fa-graduation-cap"
        subtitle: "Courses and Grades"
        url: "https://portal.youruniversity.edu" # CHANGE THIS
        target: "_blank"

      - name: "Tech News"
        icon: "far fa-newspaper" # Regular style newspaper icon
        subtitle: "Latest in Tech"
        url: "https://news.ycombinator.com" # Example, choose your favorite
        target: "_blank"

      - name: "Documentation Search"
        icon: "fas fa-book"
        subtitle: "Find Dev Docs"
        url: "https://devdocs.io" # Example, great resource
        target: "_blank"

Launch Homer and Verify Your Dashboard:
- Go to your project's root directory (~/my_homer_dashboard):
```
cd ~/my_homer_dashboard
```
- Start Homer using Docker Compose:
```
docker compose up -d
```
- Open your web browser and navigate to http://localhost:8088 (or whatever host port you configured).
- Verify:
  - Your custom title, subtitle, and logo are displayed.
  - Both service groups ("My Homelab," "Online Resources") are present with their icons.
  - All six services/links appear correctly with their names, icons, subtitles, and tags.
  - Test if the external links open correctly in a new tab. The local links will only work if the specified IP addresses are real and accessible on your network.
Experiment with Changing Service Icons:
- Go back to your config.yml.
- Pick one service, for example, "My NAS."
- Visit the Font Awesome website (fontawesome.com/icons) and find a different free icon you like (e.g., fas fa-database).
- Change the icon: value for "My NAS" in config.yml.
```
# ...
      - name: "My NAS"
        icon: "fas fa-database" # Changed icon
        subtitle: "Network Attached Storage"
        url: "http://192.168.1.50"
        tag: "Storage"
# ...
```
- Save the config.yml file.
- Refresh the Homer page in your browser. You should see the icon update. If it doesn't update immediately, try a hard refresh (Ctrl+Shift+R or Cmd+Shift+R).

Congratulations! You've successfully set up a basic Homer dashboard with custom content. You now have a solid foundation for further customization. In the next section, we'll explore intermediate features like advanced service configuration, theming, and better organization.

To stop your Homer instance if needed:

cd ~/my_homer_dashboard
docker compose down

2. Intermediate Customization and Features

With Homer up and running, it's time to explore its more nuanced features. This section focuses on enhancing your dashboard's functionality and appearance. We'll cover advanced service configurations like grouping and status checks, delve into Homer's theming system, and discuss best practices for organizing a larger dashboard.

Advanced Service Configuration

Beyond basic names, URLs, and icons, Homer allows for richer service definitions.

Grouping Services

You've already seen basic grouping in the previous section. Each top-level entry under the services: key in config.yml defines a group.

services:
  - name: "Media Servers" # Group 1
    icon: "fas fa-photo-video"
    # background: "#333" # Optional custom background for this group card
    items:
      - name: "Plex"
        # ...
      - name: "Jellyfin"
        # ...

  - name: "Network Tools" # Group 2
    icon: "fas fa-tools"
    items:
      - name: "Pi-hole"
        # ...
      - name: "Router"
        # ...

The order of groups in the config.yml file dictates their display order on the dashboard. You can add as many groups as you need to logically categorize your services. Each group can have its own name and icon. You can also specify a background color for the group card itself, which can help visually distinguish different sections.

Adding Icons to Services (Font Awesome, MDI, custom URLs)

Homer supports several ways to add icons to your services, making your dashboard more visual and intuitive.

Font Awesome Icons:
Homer natively supports Font Awesome (versions 5 and 6, depending on the Homer version; recent versions favor FA6). You specify the icon class in the icon: field.
- Free icons are generally available. You'll use prefixes like fas (Solid), far (Regular), fab (Brands).
- Example: icon: "fas fa-server", icon: "fab fa-docker"
- To find icons, visit the Font Awesome Icons gallery. Make sure to filter by "Free" if you don't have a Pro license.
Material Design Icons (MDI):
Homer also supports Material Design Icons. The syntax is similar, using the mdi: prefix followed by the icon name.
- Example: icon: "mdi:plex", icon: "mdi:router-wireless"
- To find MDI icons, visit a site like Material Design Icons by Pictogrammers. The name you use in Homer is typically the one listed on the site (e.g., plex, router-wireless).

Custom Image URLs (logo field):
If you have a specific logo for a service (e.g., a .png or .svg file) that isn't available in icon fonts, or if you prefer using official branding, you can use the logo: field.

The path should be relative to the /www/assets/ directory inside the container (which corresponds to your local assets directory mapped via Docker volume).

Example:

# In your ~/homer_dashboard/assets/ directory, create a 'tools' subdirectory
# mkdir -p ~/homer_dashboard/assets/tools
# Place plex_logo.png in ~/homer_dashboard/assets/tools/

# In config.yml:
items:
  - name: "Plex Media Server"
    logo: "assets/tools/plex_logo.png" # Path relative to /www/ in container
    url: "http://your-plex-ip:32400"

You can also use absolute URLs if the image is hosted online:

items:
  - name: "Some Online Service"
    logo: "https://somewebsite.com/path/to/logo.png"
    url: "..."

If both icon and logo are specified for an item, logo usually takes precedence.

Displaying Service Status (Connectivity Checks)

Homer can perform a simple "ping" (an HTTP GET request) to your services to check if they are online. This is visualized as a small colored dot next to the service name (typically green for online, red for offline/error).

To enable a status check for a service, add the type: and optionally status: fields to its definition:

items:
  - name: "My Web App"
    icon: "fas fa-rocket"
    url: "http://192.168.1.120:8000"
    # Connectivity Check for HTTP services
    type: "Ping"
    # Optional: Specify expected status code for 'up'. Defaults to 200-299 range.
    # status: "200" # Could be a single code
    # status: ["200", "302"] # Or an array of acceptable codes

  - name: "My Other Service (requires auth, expect 401 when up)"
    icon: "fas fa-lock"
    url: "http://192.168.1.121/restricted_area"
    type: "Ping"
    status: "401" # If a 401 means it's 'up' but needs login

  # For services that don't run on standard HTTP/HTTPS, or for simple TCP port check:
  - name: "SSH Server"
    icon: "fas fa-terminal"
    url: "ssh://user@192.168.1.10" # URL is still for clicking, not directly for status check
    # For TCP port check, specify the host and port explicitly for the check
    # This is a more advanced feature and might require specific Homer version or interpretation.
    # Homer's "Ping" type is primarily for HTTP. For raw TCP checks,
    # Homer might not support it directly out-of-the-box as robustly as dedicated monitoring tools.
    # Typically, if the service has an HTTP endpoint, even a simple one, use that.
    # If a service does not have an HTTP endpoint, Homer's 'Ping' might not be suitable.
    # Let's assume it has a health check endpoint:
    # url: "http://192.168.1.10/_health" # Link to a conceptual health page
    # type: "Ping"
    # status: "200"

How type: "Ping" works:

Homer's backend (running in the Docker container) will periodically send an HTTP GET request to the service's url.
If the response status code is in the 200-299 range (or matches the specified status value(s)), the service is considered "up."
Otherwise (timeout, connection refused, other status codes), it's considered "down."
Important: The connectivity check originates from the Homer Docker container. This means the container must be able to resolve and reach the url of the service. If you're using hostnames for local services (e.g., http://myservice.local), the Homer container needs to be able to resolve these names. This might involve custom DNS settings for your Docker daemon or using IP addresses. For services on the same Docker network, using the service name as the hostname often works.

Considerations for Status Checks:

Frequency: The check interval is usually predefined in Homer (e.g., every 30 seconds or 1 minute). This might not be highly configurable without modifying Homer's source.
Resource Usage: Too many status checks, especially to slow or external services, can add minor overhead.
Accuracy for Complex Apps: A simple HTTP GET to the base URL might not accurately reflect the health of a complex application. Some apps have dedicated /health or /status endpoints that are better for this.
Security: Be mindful if your service URLs contain sensitive information. Homer makes GET requests to these URLs.

Customizing Service Appearance (Tags, Subtitles)

Subtitles: The subtitle: field provides a way to add a short description under the service name. This is useful for clarifying the service's purpose or providing extra context.
```
items:
  - name: "Proxmox VE"
    icon: "fas fa-cubes"
    subtitle: "Virtualization Management"
    url: "https://192.168.1.200:8006"
```
Tags: The tag: field allows you to add a small label or badge to a service item. This can be used for categorization, status indication (though different from connectivity check), or highlighting.
```
items:
  - name: "GitLab CE"
    icon: "fab fa-gitlab"
    subtitle: "Self-hosted Git Repos"
    url: "http://gitlab.local"
    tag: "Dev" # A simple text tag
```
Homer may also support styling tags with pre-defined colors based on the tag name or by adding a tagStyle property, depending on the version and theme. For example:
```
items:
  - name: "Transmission"
    icon: "fas fa-download"
    subtitle: "Torrent Client"
    url: "http://192.168.1.60:9091"
    tag: "Media"
    # tagStyle: "is-success" # Example using Bulma CSS classes if supported by theme
                             # Common classes: is-info, is-success, is-warning, is-danger
```
Check the Homer documentation or experiment to see which tag styling options are available with your current theme. tagStyle allows you to use Bulma CSS helper classes (e.g., is-primary, is-link, is-info, is-success, is-warning, is-danger, is-black, is-dark, is-light, is-white) to color the tag.

Theming Homer

Homer's appearance can be significantly altered using themes and custom CSS. This allows you to match your dashboard to your personal taste or even your desktop environment's theme.

Understanding Homer's Theming System

Homer uses CSS for styling. A theme essentially consists of a set of CSS rules that define colors, fonts, spacing, and other visual aspects. Themes are typically stored as CSS files.

Using Built-in Themes

Homer comes with several pre-built themes. You can activate a theme by setting the theme: property in your config.yml at the root level.

# config.yml
title: "My Themed Dashboard"
subtitle: "Looking Good!"
logo: "fas fa-palette"
theme: "dark" # Change this to try different themes

services:
  # ... your services ...

Common built-in themes might include (the exact list can vary with Homer versions):

default (often a light theme)
light
dark
dark-blur (a dark theme with a blurred background effect, often needs a background image set)
oled (very dark, for OLED screens)
dracula
nord
solarized-dark
catppuccin-latte, catppuccin-frappe, catppuccin-macchiato, catppuccin-mocha (popular color schemes)

To try a theme, simply change the theme: value in config.yml, save the file, and refresh Homer in your browser.

Creating Custom Color Schemes

While full theme creation involves writing a complete CSS file, you can often override specific colors or styles using a custom CSS file, or by leveraging theme-specific variables if the theme supports it.

Some themes might expose CSS variables that you can override. For example, a theme might define primary color, background color, text color, etc., using CSS custom properties (e.g., --primary-color: #ff0000;). You could then override these in a custom CSS file.

Custom CSS for Advanced Styling

For more fine-grained control or to create your own look from scratch (or heavily modify an existing theme), you can use custom CSS.

Enable Custom CSS in config.yml:
Add or uncomment the customCSS: line in your config.yml:

# config.yml
title: "My Custom Styled Dashboard"
# ... other settings ...
customCSS: "assets/custom.css" # Path relative to /www/ in container

services:
  # ...

Create custom.css file:
In your local ~/homer_dashboard/assets/ directory (the one mapped to /www/assets in the container), create a file named custom.css.
Add Your CSS Rules:
You'll need to use your browser's developer tools (usually by pressing F12) to inspect elements on your Homer page and find the CSS selectors you want to target. For example, to change the main background color and the default text color: File: ~/homer_dashboard/assets/custom.css
```
/* Custom CSS for Homer */

body {
    background-color: #282a36 !important; /* Dracula background */
    color: #f8f8f2 !important; /* Dracula foreground */
}

.page-title .title {
    color: #50fa7b !important; /* Dracula green for the main title */
}

.page-title .subtitle {
    color: #bd93f9 !important; /* Dracula purple for the subtitle */
}

.service .name, .service .subtitle {
    color: #f8f8f2 !important; /* Ensure service text is readable */
}

.service .tag {
    background-color: #ffb86c !important; /* Dracula orange for tags */
    color: #282a36 !important;
}

/* Make service cards semi-transparent with a different background */
.service {
    background-color: rgba(68, 71, 90, 0.8) !important; /* Dracula current line, semi-transparent */
    border-radius: 8px;
}
```
Important Notes on Custom CSS:
- !important: You might often need to use !important to override existing theme styles, as Homer's default styles can be quite specific. Use it judiciously, as overusing !important can make CSS harder to manage.
- Specificity: CSS rules are applied based on specificity. More specific selectors override less specific ones. Inspecting elements will help you understand the existing selectors.
- Browser Cache: When making CSS changes, browsers can aggressively cache CSS files. Always do a hard refresh (Ctrl+Shift+R or Cmd+Shift+R) in your browser to ensure you're seeing the latest changes. You might even need to clear your browser cache sometimes.
- Testing: Make small changes, save, and refresh to see the effect. This iterative process is key.

Organizing Your Dashboard

As you add more services, your dashboard can become cluttered. Effective organization is key to maintaining its usefulness.

Managing a Large Configuration File

Homer primarily uses a single config.yml. While it doesn't have a native "include" system to split this file into smaller manageable chunks that are then re-assembled, you can employ strategies to keep your main config.yml organized:

Comments:
Use YAML comments (#) extensively to label sections, explain choices, or temporarily disable entries.

# ----------------------------------------------------
# SECTION: MEDIA SERVICES
# This group contains all applications related to media consumption and management.
# ----------------------------------------------------
services:
  - name: "Media Suite"
    # ...

Consistent Formatting:
Maintain strict and consistent indentation. Use a YAML linter (many text editors like VS Code have them) to catch syntax errors.
Logical Grouping:
Plan your service groups thoughtfully. Group by function (e.g., "Downloaders," "System Monitoring," "Development Tools"), by physical server, or any other logic that makes sense to you.
YAML Anchors and Aliases (Advanced YAML):
For highly repetitive blocks, YAML anchors (&) and aliases (*) can reduce duplication. However, their use in Homer's config.yml for complex structures might be limited by how Homer parses the YAML. They are generally more useful for data parts, not entire service definitions if those definitions need unique URLs, etc. Example of a potential use for a common setting (use with caution and test):
```
# Define an anchor for common target_blank setting
common_settings: &common_settings
  target: "_blank"

services:
  - name: "External Sites"
    items:
      - name: "Google"
        url: "https://google.com"
        <<: *common_settings # Merge common_settings
      - name: "Wikipedia"
        url: "https://wikipedia.org"
        <<: *common_settings
```
Test this carefully; not all YAML parsers or applications handle merge keys (<<:) in all contexts. Homer's parser might or might not fully support this for all structures. Simpler is often better.
Separate Homer Instances for Drastically Different Dashboards: If you need entirely separate dashboards (e.g., one for work, one for personal, one for a specific project) with different global settings (titles, themes), you can run multiple Homer instances. Each instance would have its own docker-compose.yml (or a different service definition within a single docker-compose.yml) pointing to a different assets directory (and thus a different config.yml). For example, in one docker-compose.yml:
```
services:
  homer_personal:
    image: b4bz/homer
    container_name: homer-personal
    volumes:
      - ./personal_assets:/www/assets
    ports:
      - "8080:8080"
    restart: unless-stopped

  homer_work:
    image: b4bz/homer
    container_name: homer-work
    volumes:
      - ./work_assets:/www/assets # Different assets directory
    ports:
      - "8081:8080" # Different host port
    restart: unless-stopped
```
You would then have ~/homer_dashboards/personal_assets/config.yml and ~/homer_dashboards/work_assets/config.yml.

Best Practices for a Clean and Usable Dashboard Layout

Limit Columns: While Homer supports multiple columns (columns: "4" or "5" in config.yml), too many columns on a smaller screen can make items too small. Test on different screen sizes. 3 or 4 columns are often a good balance.
Strategic Grouping: Don't create too many small groups or too few overly large groups. Aim for a balance that minimizes scrolling while keeping related items together.
Prioritize Frequently Used Services: Place your most used services or groups at the top or in a prominent position.
Consistent Iconography: Try to use icons from the same family (e.g., all Font Awesome Solid, or all MDI) for a more cohesive look, or use custom logos consistently.
Clear Naming and Subtitles: Use descriptive names and subtitles so you (and anyone else using the dashboard) can easily identify services.
Minimalism: Avoid clutter. Only include services and links you actually use or need quick access to. A dashboard with hundreds of rarely used items defeats its purpose.

Utilizing Bookmarks for Quick Access

Homer also supports a bookmarks section in its config.yml. These are typically displayed in a more compact way, often in the header or as a dedicated section, separate from the main service tiles. This feature might vary in prominence and styling depending on the Homer version and theme.

The bookmarks section has been part of older Homer versions and might be configured differently or be less emphasized in newer versions in favor of the links section (which can be placed in the header or footer). If your Homer version supports a distinct bookmarks section for the header, it's usually structured like this:

# config.yml
# ... (other settings)

# Header configuration (if you want bookmarks in the header)
header: true
# layout: " compacto" # some themes might have layout options for header

# Bookmarks (often displayed in the header if 'header: true')
# Check your Homer version's documentation for the exact structure,
# it might also be 'links' as shown in basic setup.
# If 'links' is used for header display:
links:
  - name: "Docs"
    icon: "fas fa-book"
    url: "https://my-docs.example.com"
    target: "_blank"
  - name: "Search"
    icon: "fas fa-search"
    url: "https://google.com"
    target: "_blank"

# ... (services section)

Refer to the documentation for your specific Homer version or the default config.yml provided by the INIT_ASSETS=1 feature for the most accurate way to configure header/footer links or bookmarks. The links: array shown in the "Basic Setup" is the more common way to add such quick links, and their placement (header/footer) can sometimes be influenced by the header: false setting. If header: false, links often appear in the footer. If header: true, links might appear near the header or as a menu.

Workshop - Enhancing Your Dashboard with Groups, Icons, and a Custom Theme

Project Goal: Organize your existing services from the Basic workshop into logical groups, assign appropriate and varied icons (Font Awesome, MDI, and one custom logo if possible), apply a built-in theme, and attempt a minor custom CSS modification. Also, add a connectivity check to at least one local service.

Steps:

Start with Your Previous Dashboard:
- Ensure your Homer instance from the "Basic Setup Workshop" is running. If not, navigate to its directory (~/my_homer_dashboard) and run docker compose up -d.
- Have your ~/my_homer_dashboard/assets/config.yml file open in your text editor.

Create at Least Two Service Groups:

Identify logical categories for your current services. For example, "Network Utilities" and "Development Tools," or "Local Media" and "Online Study."
Restructure your config.yml's services section to reflect these groups.

Example transformation: Before (from Basic workshop - simplified):

services:
  - name: "My Homelab"
    items:
      - name: "My NAS" # ...
      - name: "Router Config" # ...
      - name: "Pi-hole" # ...
  - name: "Online Resources"
    items:
      - name: "My University Portal" # ...
      - name: "Tech News" # ...
      - name: "Documentation Search" # ...

After (example restructuring):

services:
  - name: "Local Network Services" # New Group 1
    icon: "fas fa-network-wired"
    items:
      # Move Router Config and Pi-hole here
      - name: "Router Config"
        icon: "fas fa-cogs" # Change icon if desired
        subtitle: "Network Settings"
        url: "http://192.168.0.1"
        tag: "Config"

      - name: "Pi-hole"
        icon: "fas fa-shield-alt"
        subtitle: "DNS Ad Blocker"
        url: "http://192.168.1.53/admin"
        tag: "Security"

  - name: "Storage & Data" # New Group 2
    icon: "fas fa-database"
    items:
      # Move My NAS here
      - name: "My NAS"
        icon: "fas fa-hdd"
        subtitle: "Network Attached Storage"
        url: "http://192.168.1.50"
        tag: "Storage"

  - name: "Educational & News" # New Group 3 (for previous "Online Resources")
    icon: "fas fa-graduation-cap"
    items:
      # Move University, News, Docs here
      - name: "My University Portal"
        icon: "fas fa-university"
        subtitle: "Courses and Grades"
        url: "https://portal.youruniversity.edu"
        target: "_blank"

      - name: "Tech News Aggregator"
        icon: "far fa-newspaper"
        subtitle: "Latest in Technology"
        url: "https://news.ycombinator.com"
        target: "_blank"

      - name: "DevDocs Central"
        icon: "fas fa-book-open"
        subtitle: "Programming Documentation"
        url: "https://devdocs.io"
        target: "_blank"

Save config.yml and refresh Homer to see the new group structure.

Find and Apply Varied Icons:
- For each service, choose an appropriate icon. Try to use:
  - At least two Font Awesome icons (e.g., fas fa-something, fab fa-something).
  - At least one Material Design Icon (e.g., mdi:server). Search on Pictogrammers MDI Library.
  - (Optional Challenge): One custom logo.
    - Find a small .png or .svg logo for one of your services (e.g., your university logo, or a generic "files" icon).
    - Create a subdirectory in ~/my_homer_dashboard/assets/ called icons (e.g., mkdir ~/my_homer_dashboard/assets/icons).
    - Place your chosen logo image (e.g., my_uni_logo.png) into this assets/icons/ directory.
    - In config.yml, for that service, use the logo: property:
      - name: "My University Portal" logo: "assets/icons/my_uni_logo.png" # Path relative to /www/ subtitle: "Courses and Grades" url: "https://portal.youruniversity.edu" target: "_blank"
- Update your config.yml with these new icon: and logo: values. Save and refresh.
Explore and Apply a Built-in Theme:
- In your config.yml, find or add the theme: setting at the root level.
- Try out at least three different built-in themes. Examples: dark, light, nord, dracula, catppuccin-mocha.
```
# config.yml
title: "My Enhanced Dashboard"
# ...
theme: "dracula" # Try this one
# ...
```
- After each change, save config.yml and refresh Homer to see the new look.
- Settle on one theme you like for the next step.
Attempt a Simple Custom CSS Modification:
- Enable custom CSS by adding/uncommenting customCSS: "assets/custom.css" in config.yml.
- Create the file ~/my_homer_dashboard/assets/custom.css.
- Goal: Change the font size of all service names.
- How:
  - Open Homer in your browser, then open Developer Tools (F12).
  - Use the "Inspector" tool (it usually looks like a mouse pointer in a square) to click on one of the service names on your dashboard.
  - Examine the HTML structure and the CSS styles applied to it. You should find a class associated with the service name, often something like .service .name or similar.
  - In your custom.css, add a rule to target this class:
```
/* ~/my_homer_dashboard/assets/custom.css */
.service .name {
    font-size: 1.2em !important; /* Increase font size, !important might be needed */
    /* You could also try changing color:
    color: #yourchoiceofcolor !important;
    */
}
```
- Save custom.css. Hard refresh Homer in your browser (Ctrl+Shift+R or Cmd+Shift+R).
- Observe if the service names are now larger. If not, double-check your CSS selector and ensure customCSS is correctly configured in config.yml.
Add a Connectivity Check:
- Choose one of your local services that runs on HTTP (e.g., "Router Config" or "Pi-hole", assuming they are accessible via HTTP from the Homer container). If you don't have a real local service, you can use a public service that you know is usually up, like https://www.google.com for testing, but ideally, test with a local one.
- Add the type: "Ping" field to its definition in config.yml.
```
# ...
      - name: "Router Config"
        icon: "fas fa-cogs"
        subtitle: "Network Settings"
        url: "http://192.168.0.1" # Make sure this is reachable from the Docker container
        tag: "Config"
        type: "Ping" # Add this line
# ...
```
- Save config.yml. Refresh Homer.
- Look for a small status indicator (dot) next to the "Router Config" service. It might take a few seconds to appear.
  - Green dot: The service is reachable.
  - Red dot: The service is not reachable (or returned an unexpected status code).
  - Troubleshooting: If it's red, ensure the URL is correct and that the Homer container can actually access that IP and port. If your router's admin page redirects immediately or requires login that results in a non-2xx status code, you might need to adjust the status: field (e.g., status: "302" if it redirects, or status: "401" if it's an auth page). For simple services that just return 200 OK, type: "Ping" alone is usually sufficient.

By completing this workshop, your Homer dashboard should now be more organized, visually appealing with a new theme and varied icons, and provide at-a-glance status for at least one service. You've also taken your first steps into custom CSS modifications.

3. Advanced Homer Techniques and Integrations

This section takes you further into mastering Homer, focusing on deeper customization, integration within your broader self-hosted ecosystem, crucial security considerations, and effective troubleshooting. These advanced techniques will help you create a truly personalized, robust, and secure dashboard.

Custom Assets and Branding

Making your Homer dashboard uniquely yours often involves custom branding elements beyond just themes.

Using Custom Logos and Favicons

Custom Dashboard Logo: You've seen the logo: field in config.yml. While Font Awesome icons are convenient, a custom image logo can significantly enhance branding.
1. Prepare Your Logo: Create or obtain a logo image. Good formats are PNG (with transparency) or SVG (scalable). Aim for a reasonable size (e.g., 100x100 pixels, but Homer will scale it).
2. Place the Logo: Put your logo file (e.g., my_dashboard_logo.png) into your ~/homer_dashboard/assets/ directory, or a subdirectory like ~/homer_dashboard/assets/images/.
3. Configure in config.yml:
```
# config.yml
title: "My Branded Homelab"
logo: "assets/images/my_dashboard_logo.png" # Path relative to /www/
# ... other settings ...
```
4. Save and refresh Homer. Your custom logo should appear. You might need to adjust its size or the layout with custom CSS if it doesn't fit well initially.
Custom Favicon: A favicon is the small icon displayed in the browser tab, bookmarks, and history.
1. Prepare Your Favicon: Create a favicon. The traditional format is .ico, but modern browsers also support .png (e.g., 16x16, 32x32, or 64x64 pixels). There are many online favicon generators.
2. Place the Favicon: Put your favicon file (e.g., favicon.png or favicon.ico) into your ~/homer_dashboard/assets/ directory.
3. Configure in config.yml:
```
# config.yml
# ... other settings ...
favicon: "assets/favicon.png" # Path relative to /www/
# documentTitle: "My Hub" # Optional: Set a custom browser tab title
# ...
```
4. Save config.yml. You might need to do a hard refresh (Ctrl+Shift+R or Cmd+Shift+R) or even clear your browser cache and restart the browser for favicon changes to become visible, as browsers cache favicons aggressively.

Adding Custom Background Images or Videos

A custom background can dramatically change the feel of your dashboard.

Custom Background Image:
1. Choose Your Image: Select a high-quality background image. Consider images that are not too "busy" so that text and service cards remain readable.
2. Place the Image:
  Put your image file (e.g., background.jpg) into ~/homer_dashboard/assets/ or a subdirectory like ~/homer_dashboard/assets/backgrounds/.
3. Configure in config.yml:
```
# config.yml
# ... other settings ...
background: "assets/backgrounds/my_cool_background.jpg" # Path relative to /www/
# ...
```
4. Save and refresh. You may need to adjust text colors (via theme or custom CSS) for readability against your new background.
5. Advanced Background Styling (via custom.css):
  For more control (e.g., background-size: cover, background-attachment: fixed, opacity, blur), you can set the background using your custom.css file instead of the config.yml setting. File: ~/homer_dashboard/assets/custom.css
```
body {
    background-image: url('assets/backgrounds/my_cool_background.jpg');
    background-size: cover; /* Cover the entire viewport */
    background-position: center center; /* Center the image */
    background-repeat: no-repeat; /* Do not repeat the image */
    background-attachment: fixed; /* Fixed background, scrolls with content */
}
```
  If using custom.css for the background, you might want to remove or comment out the background: line in config.yml to avoid conflicts.
Custom Background Video (Advanced):
Homer doesn't have a direct config.yml option for background videos, but this can be achieved with custom CSS and HTML (potentially by modifying the footer or using customJS to inject HTML). This is significantly more advanced. A simpler approach for a "video-like" effect might be an animated GIF set as a background image, but be mindful of file size and performance. For a true HTML5 video background, you would typically:
1. Add a <video> element to the page (e.g., using customJS to append it to the body or a specific div).
2. Style this video element with CSS to act as a background (fixed position, z-index, dimensions). This is beyond typical Homer usage but possible with web development skills.

Advanced CSS for Complete Visual Overhaul

If you have strong CSS skills, you can completely transform Homer's appearance.

Inspect and Override: Use browser developer tools extensively to understand Homer's HTML structure and existing CSS.
Start from a Base Theme: It's often easier to pick a built-in theme that's closest to your desired look and then heavily customize it via custom.css, rather than starting from scratch.
CSS Variables: If the theme uses CSS custom properties (variables), overriding these can be a powerful way to change core aspects like color palettes and fonts globally. Example: If a theme defines --theme-primary-color: blue;, you could put --theme-primary-color: green !important; in your custom.css inside the :root or body selector.
Responsive Design: Pay attention to how your custom styles affect responsiveness. Test on different screen sizes (desktop, tablet, mobile). Use media queries (@media (max-width: 768px) { ... }) in your custom.css to apply different styles for different screen sizes.
Font Changes: You can change fonts using @font-face rules (if using custom font files placed in your assets directory) or by linking to Google Fonts in your custom.css and then applying them to body or specific elements.
```
/* custom.css - Example using Google Fonts */
@import url('https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;700&display=swap');

body {
    font-family: 'Roboto', sans-serif;
}
```

Integrating with Other Self-Hosted Services

Homer primarily acts as a launchpad. Direct embedding of complex interactive content from other services (like live Grafana panels) within a Homer service card is generally not a feature of Homer, as it's a static site. Its strength lies in providing quick and organized access to those services.

Embedding Content (Limited Scope in Homer)

Simple Image Embeds: Some services might provide direct URLs to images (e.g., a weather widget that's just an image, a status badge as an image). You can use such an image URL as a service logo:
```
- name: "Server CPU Temp"
  logo: "http://my-monitoring-service/cpu_temp_graph.png" # Assuming this URL returns an image
  url: "http://my-monitoring-service/dashboard" # Link to the actual dashboard
  subtitle: "Live CPU Temperature Chart"
```
The image will act as the "icon" for the service link. It won't be a large embedded panel.
Iframes (Not Natively Supported by Homer's config.yml): True embedding of interactive content usually requires HTML <iframe> elements. Homer's config.yml doesn't have a standard way to define iframes directly as service items.
- Workaround (Advanced - Custom HTML in Footer/Header or custom.js): You could potentially inject an iframe using the footer option in config.yml if you need a small, persistent embedded element somewhere on the page, or use custom.js to dynamically create and insert an iframe. This is a hack and might not integrate well with Homer's layout.
- Alternative Dashboard Solutions: If deep embedding of various service UIs is a primary requirement, other dashboard solutions like Organizr or Dashy might be more suitable as they are designed with such capabilities in mind.

Using Homer as a Launchpad for Your Homelab

This is Homer's core strength.

Centralized Access: List all your self-hosted services (Plex, Nextcloud, Home Assistant, Proxmox, AdGuard Home, your development projects, etc.) with clear names, icons, and direct URLs.
Network Device Management: Add links to your router, modem, switches, NAS admin UIs.
Status Indicators: Use the type: "Ping" feature to get a quick visual cue if a local service is responsive.

Deep Linking: Instead of just linking to the main page of a service, you can link to specific deep pages.

- name: "Router - Traffic Stats"
  icon: "fas fa-chart-line"
  url: "http://192.168.1.1/traffic_stats.html" # Deep link
  subtitle: "View network traffic"

Organize by Workflow: Group services based on how you use them (e.g., "Media Management," "System Administration," "Development Projects").

Security Considerations for Your Homer Instance

If your Homer dashboard is only accessible on your local network, security concerns are somewhat reduced. However, if you plan to expose it to the internet (even through a VPN), or if multiple users access the machine hosting Docker, consider these points.

Exposing Homer to the Internet (Reverse Proxies)

Exposing services directly to the internet can be risky. A reverse proxy is a server that sits in front of web servers and forwards client (e.g., web browser) requests to those web servers. Reverse proxies are crucial for:

SSL/TLS Termination: Easily add HTTPS (encryption) to your services.
Host-based Routing: Access multiple services on the same IP/port using different hostnames (e.g., homer.mydomain.com, nextcloud.mydomain.com).
Load Balancing: (Not typically needed for Homer, but a general reverse proxy feature).
Security Layers: Can provide features like rate limiting, IP blocking, web application firewall (WAF) capabilities, and centralized authentication.

Popular Reverse Proxy Options (often run in Docker):

Nginx Proxy Manager (NPM): Very user-friendly GUI for managing Nginx as a reverse proxy. Excellent for beginners. Handles SSL certificates (via Let's Encrypt) automatically.
Traefik: More advanced, powerful, and automates configuration via Docker labels (dynamic configuration). Steeper learning curve but very efficient once set up.
Caddy: Known for its automatic HTTPS by default and simple configuration file.

General Workflow for Exposing Homer with a Reverse Proxy (e.g., NPM):

Domain Name: You'll need a domain name (e.g., mydomain.com) and the ability to configure its DNS records.
Port Forwarding: On your router, forward ports 80 (for HTTP) and 443 (for HTTPS) to the server running your reverse proxy.
Install Reverse Proxy: Set up Nginx Proxy Manager or Traefik (usually as a Docker container).
Configure Proxy Host:
- In your reverse proxy, create a new proxy host.
- Domain/Hostname: homer.mydomain.com (or whatever subdomain you choose).
- Scheme: http (since Homer itself is running on HTTP within your Docker network).
- Forward Hostname/IP: The IP address of the Docker host and the port Homer is running on (e.g., 192.168.1.10 if Docker host is at that IP, or the Docker container name/IP if on a shared Docker network like homer if that's the service name in the same Docker Compose network as NPM).
- Forward Port: The host port you mapped for Homer (e.g., 8080 from ports: - "8080:8080" in Homer's docker-compose.yml).
- SSL: Enable SSL and request a Let's Encrypt certificate.
DNS Configuration: Point your chosen subdomain (homer.mydomain.com) via an A record (or CNAME) to your public IP address.
Access: You should now be able to access Homer securely via https://homer.mydomain.com.

Basic Authentication

Homer itself does not have built-in authentication (username/password protection). If your dashboard contains links to sensitive internal services, exposing it without authentication is a security risk, even if the services themselves are password-protected.

Reverse Proxy Authentication: The easiest and recommended way to add authentication to Homer is through your reverse proxy.
- Nginx Proxy Manager: In the "Access List" settings for your proxy host, you can easily create an access list with usernames and hashed passwords (HTTP Basic Auth).
- Traefik: Supports various authentication middlewares (BasicAuth, DigestAuth, OAuth, etc.).
VPN: Access your Homer instance (and other internal services) exclusively through a VPN (e.g., WireGuard, OpenVPN). This keeps them off the public internet entirely.
Firewall Rules: Restrict access to Homer's port to specific IP addresses if possible (e.g., only your university's IP range, though this can be unreliable with dynamic IPs).

Keeping Homer Updated

Software vulnerabilities can be discovered over time. Keeping Homer (and all your self-hosted services) updated is important.

Docker Image Updates: The b4bz/homer image is regularly updated.
1. Pull the Latest Image:
```
docker pull b4bz/homer:latest
```
2. Stop and Remove Old Container (if using docker-compose): Navigate to your ~/homer_dashboard directory:
```
docker compose down
```
3. Recreate and Start Container with New Image:
```
docker compose up -d
```
  Docker Compose will use the newly pulled latest image. Your assets volume mount ensures your configuration persists.
Watch for Announcements: Follow the Homer GitHub repository (bastienwirtz/homer) for release notes and security advisories. Tools like Diun or Watchtower can also automate notifications or updates for Docker containers, but use automated updates with caution for critical services.

Troubleshooting and Maintenance

Even with a simple application like Homer, you might encounter issues.

Common Configuration Errors and How to Fix Them

YAML Syntax Errors:
YAML is very strict about indentation (spaces, not tabs!) and structure.
- Symptom: Homer might not start, show a blank page, display an error, or not load your config.yml changes.
- Fix:
  - Use a YAML linter/validator. Many online validators exist, or your text editor (like VS Code with YAML extensions) can highlight errors.
  - Carefully check indentation. Typically 2 spaces per level. Be consistent.
  - Ensure colons (:) are followed by a space.
  - Lists (arrays) are denoted by hyphens (-) with a space after the hyphen.
Incorrect Paths for Assets (Logos, CSS, Backgrounds):
- Symptom: Images/icons don't load, custom CSS not applied.
- Fix: Remember that paths in config.yml (like logo: "assets/my_logo.png") are relative to the /www/ directory inside the container. Your local assets directory is mapped to /www/assets.
  - If your logo is in ~/homer_dashboard/assets/images/logo.png locally, the path in config.yml should be assets/images/logo.png.
  - Double-check file names for typos and case sensitivity (Linux is case-sensitive).
Connectivity Check Failures (Red Dots):
- Symptom: Service status shows red.
- Fix:
  - Verify the service url is correct and accessible from the Homer container.
  - Use docker exec -it homer_container_name sh (replace homer_container_name with your actual container name, usually homer or what you set in docker-compose.yml) to get a shell inside the container. Then try to ping (if ICMP is allowed) or curl -v <service_url> from inside the container to diagnose connectivity.
  - Check if the service requires authentication or returns a non-2xx status code by default. Adjust the status: field in config.yml if necessary.
  - Firewall rules on the Docker host or network might be blocking access.
Theme Not Applying:
- Symptom: Dashboard uses the default theme despite setting a different one.
- Fix:
  - Ensure the theme name in config.yml (theme: "dracula") is spelled correctly and is a valid, available theme. Check Homer's documentation or GitHub for a list of themes.
  - Clear browser cache and do a hard refresh.

Checking Docker Logs for Issues

Docker logs are invaluable for troubleshooting container problems.

If using docker compose: Navigate to your ~/homer_dashboard directory.

docker compose logs homer # 'homer' is the service name in your docker-compose.yml
docker compose logs -f homer # To follow logs in real-time

If using docker run (and you named your container homer_instance):
```
docker logs homer_instance
docker logs -f homer_instance
```
Look for error messages, warnings, or clues about what might be going wrong (e.g., "Cannot parse config.yml," "File not found").

Backing Up Your Homer Configuration

Your Homer configuration is primarily contained in your ~/homer_dashboard/assets/ directory (especially config.yml and any custom images, CSS).

Manual Backup: Regularly copy the entire ~/homer_dashboard/assets/ directory to a safe location (another drive, cloud storage, USB stick).
Version Control (Git): This is highly recommended.
1. Initialize a Git repository in your ~/homer_dashboard/ directory:
```
cd ~/homer_dashboard
git init
echo "node_modules/" > .gitignore # If any JS tools generate this
echo "*.log" >> .gitignore
git add .
git commit -m "Initial Homer configuration"
```
2. After making significant changes to config.yml or other assets:
```
git add .
git commit -m "Added new media services and updated theme"
```
3. You can then push this repository to a private remote Git server (like a self-hosted Gitea/GitLab or a private GitHub/GitLab repository) for offsite backup. This allows you to track changes, revert to previous versions, and easily restore your configuration.

Workshop - Advanced Branding and Setting up a Reverse Proxy (Conceptual for Local NPM)

Project Goal:
Brand your Homer dashboard with a custom logo and background. Then, conceptually (or actually, if you have a domain and public IP) set up Nginx Proxy Manager (NPM) to serve Homer, and optionally add basic authentication through NPM. For this workshop, we'll simulate the NPM part mostly on a local network if you don't have a public domain.

Prerequisites:

Your Homer dashboard from previous workshops.
Docker and Docker Compose installed.

Part 1: Custom Branding

Design or Find a Custom Logo:
- Find or create a small logo image (e.g., a .png with transparency, or an .svg). For this workshop, you can search for "placeholder logo png" or "sample icon png" and download one. Let's say you download mylogo.png.
- Create an images subdirectory in your ~/my_homer_dashboard/assets/ directory:
```
mkdir -p ~/my_homer_dashboard/assets/images
```
- Move your mylogo.png into ~/my_homer_dashboard/assets/images/.
Design or Find a Custom Background Image:
- Find a suitable background image (e.g., a subtle texture, a space nebula, a landscape). Search for "royalty free background images." Let's say you download mybackground.jpg.
- Move mybackground.jpg into ~/my_homer_dashboard/assets/images/.
Configure Homer to Use Custom Assets:
- Edit your ~/my_homer_dashboard/assets/config.yml:
```
# Page metadata
title: "My Fully Branded Hub"
subtitle: "Pro Edition"
logo: "assets/images/mylogo.png" # Update path to your logo
# favicon: "assets/images/myfavicon.png" # Optional: add a favicon too

background: "assets/images/mybackground.jpg" # Add path to your background

# ... rest of your config ...
```
- Save the config.yml file.
- Refresh your Homer dashboard in the browser. You should see your new logo and background image.
- Troubleshooting: If images don't appear, double-check paths, file names (case sensitivity!), and clear browser cache/hard refresh. Check Docker logs for errors.

Part 2: Setting up Nginx Proxy Manager (NPM) - Local Network Simulation

If you have a real domain and public IP, you can follow these steps for actual internet exposure. If not, we'll simulate it using local hostnames by editing your computer's hosts file.

Install Nginx Proxy Manager (NPM) in Docker:

Create a new directory for NPM, outside your Homer directory:
```
mkdir ~/npm_data
cd ~/npm_data
```

Create a docker-compose.yml for NPM: File: ~/npm_data/docker-compose.yml

version: '3.8'
services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    container_name: nginx-proxy-manager
    restart: unless-stopped
    ports:
      # These ports are in format <host-port>:<container-port>
      - '80:80'   # Public HTTP Port
      - '443:443' # Public HTTPS Port
      - '81:81'   # Admin Web Port
    volumes:
      - ./data:/data # Persists NPM data
      - ./letsencrypt:/etc/letsencrypt # Persists Let's Encrypt certificates

Start NPM:
```
docker compose up -d
```
Wait a minute for NPM to initialize.

Access NPM Admin Interface:
- Open your browser and go to http://<your-docker-host-ip>:81. (If running Docker locally, this is http://localhost:81).
- Default Admin User (first time login):
  - Email: admin@example.com
  - Password: changeme
- You will be prompted to change these credentials immediately. Do so.
(Simulation Step) Modify Your Hosts File (If No Real Domain):
- To access Homer via a custom hostname locally (e.g., homer.local), you need to tell your computer that this hostname points to your Docker host's IP address (where NPM is listening on ports 80/443).
- Find your Docker host's local IP: Use ip addr show (Linux) or ipconfig (Windows). Let's say it's 192.168.1.100.
- Edit hosts file:
  - Linux/macOS: sudo nano /etc/hosts
  - Windows: C:\Windows\System32\drivers\etc\hosts (edit as Administrator)
- Add a line:
```
192.168.1.100   homer.local
```
  (Replace 192.168.1.100 with your Docker host's actual local IP).
- Save the hosts file. You might need to flush your DNS cache (ipconfig /flushdns on Windows).
Configure NPM to Create a Proxy Host for Homer:
- In the NPM web UI (http://<your-docker-host-ip>:81):
  - Go to "Hosts" -> "Proxy Hosts."
  - Click "Add Proxy Host."
  - Details Tab:
    - Domain Names: homer.local (or your actual homer.yourdomain.com if using a real domain).
    - Scheme: http
    - Forward Hostname / IP: The IP address of your Docker host (e.g., 192.168.1.100) or, if Homer and NPM are on the same custom Docker network, you could use Homer's container name (e.g., my-homer-instance from your Homer docker-compose.yml). For simplicity with default Docker networking, use the Docker host's IP.
    - Forward Port: The port your Homer instance is exposed on on the host (e.g., 8088 from the Basic workshop docker-compose.yml).
    - Cache Assets: You can enable this.
    - Block Common Exploits: Good to enable.
    - Websockets Support: Not typically needed for Homer itself.
  - SSL Tab (If using a real domain and want HTTPS):
    - Select "Request a new SSL Certificate" from the "SSL Certificate" dropdown.
    - Enable "Force SSL."
    - Enable "HTTP/2 Support."
    - Agree to Let's Encrypt Terms of Service.
    - Click "Save." NPM will attempt to get a certificate. (This will fail for homer.local as Let's Encrypt can't validate local-only domains).
    - For homer.local (No SSL): On the SSL tab, choose "None" for SSL Certificate.
  - Click "Save."
Access Homer Through the NPM-Defined Hostname:
- If you configured homer.local without SSL, open your browser and go to http://homer.local.
- If you used a real domain and SSL, go to https://homer.yourdomain.com.
- You should see your Homer dashboard, now served through Nginx Proxy Manager.
(Optional) Add Basic Authentication via NPM:
- This step adds a username/password prompt before anyone can see your Homer dashboard.
- In NPM:
  - Go to "Access Lists."
  - Click "Add Access List."
  - Give it a name (e.g., "Homer Auth").
  - Under "Authorization," click "Add" and enter a username and password. Save these credentials.
  - Click "Save" for the Access List.
- Now, go back to "Hosts" -> "Proxy Hosts" and edit your homer.local (or homer.yourdomain.com) entry.
- Go to the "Access List" tab.
- Select your newly created access list ("Homer Auth") from the dropdown.
- Under "HTTP Basic Authentication," toggle it ON.
- Click "Save."
- Now, when you try to access http://homer.local (or your HTTPS domain), your browser should pop up a login dialog asking for the username and password you just set up.

This workshop gives you a taste of advanced branding and the power of using a reverse proxy like Nginx Proxy Manager. Even if simulated locally, understanding the NPM setup process is crucial for securely exposing any self-hosted service.

Conclusion

Throughout this guide, we've journeyed from the basics of what Homer is to advanced customization and security practices. You've learned how to install Homer using Docker, craft its configuration with YAML, personalize its appearance with themes and custom CSS, and integrate it as a central launchpad for your digital life. We've also touched upon the critical aspects of securing your dashboard, especially when considering external access.

Recap of Homer's Capabilities

Simplicity and Speed: Homer's static nature, configured via YAML, makes it incredibly lightweight, fast, and easy to manage.
Centralized Access: It provides a clean, organized interface to all your self-hosted applications, network devices, and important web links.
Customization: From titles and logos to themes, custom CSS, service grouping, icons, and status checks, Homer offers a good degree of personalization to fit your needs.
Docker-Native: Easy deployment and updates using Docker and Docker Compose.
Community: While simple, Homer has a community and its development is active, meaning new features and themes can emerge.

Homer excels as a straightforward, visually appealing dashboard that "just works." It's an excellent starting point for anyone building a homelab or simply wanting to organize their digital bookmarks more effectively.

Next Steps in Your Self-Hosting Journey

Mastering Homer is often a gateway to exploring the broader world of self-hosting. Here are some potential next steps:

Explore More Self-Hosted Services: Now that you have a dashboard, start populating it! Consider services like:
- Media: Plex, Jellyfin, Emby
- File Sync & Sharing: Nextcloud, Syncthing
- Automation: Home Assistant
- Network Ad-Blocking: Pi-hole, AdGuard Home
- Password Management: Vaultwarden (Bitwarden_rs)
- Note-Taking/Wikis: Joplin Server, BookStack, DokuWiki
Deepen Your Docker Knowledge: Understanding Docker more thoroughly will empower you to manage and deploy almost any self-hosted application.
Learn More About Networking: Concepts like DNS, VPNs (WireGuard is highly recommended), and firewalls are crucial for a secure and robust self-hosted environment.
Consider a Dedicated Homelab Server: If you find yourself running many services, a dedicated low-power server (like a Raspberry Pi, an old PC, or a NUC) can be a great investment.
Contribute: If you enjoy Homer and have ideas or find bugs, consider contributing to its development on GitHub.

Community and Resources

Homer GitHub Repository: bastienwirtz/homer - The primary source for code, documentation, issues, and discussions.
r/selfhosted on Reddit: An excellent community for discovering new self-hosted apps, getting help, and sharing your setups.
Awesome Selfhosted List: A curated list of Free Software network services and web applications which can be hosted locally. Search for "awesome-selfhosted github."
Docker and Docker Compose Documentation: The official docs are comprehensive and essential reading.

Self-hosting is a rewarding journey of learning and empowerment. Your Homer dashboard can serve as your command center as you explore this exciting domain. Happy self-hosting!

Personal Dashboard - Homer

Introduction to Homer

What is Homer?

Why Use a Personal Dashboard?

Homer's Key Features

Alternatives to Homer

Workshop - Exploring the Homer Demo

1. Basic Setup and Configuration

Prerequisites for Homer Installation

Understanding Docker and Docker Compose

Basic Linux Command Line Familiarity

Text Editor for Configuration

Installation using Docker

Pulling the Homer Docker Image

Running Homer with a Simple Docker Command

Understanding Homer's Configuration File (config.yml)

Core Structure - title, subtitle, logo, etc.

Defining Services

Defining Links

Initial Customization

Changing the Title and Subtitle

Adding Your First Services

Adding External Links

Workshop - Building Your First Simple Dashboard

2. Intermediate Customization and Features

Advanced Service Configuration

Grouping Services

Adding Icons to Services (Font Awesome, MDI, custom URLs)

Displaying Service Status (Connectivity Checks)

Customizing Service Appearance (Tags, Subtitles)

Theming Homer

Understanding Homer's Theming System

Using Built-in Themes

Creating Custom Color Schemes

Custom CSS for Advanced Styling

Organizing Your Dashboard

Managing a Large Configuration File

Best Practices for a Clean and Usable Dashboard Layout

Utilizing Bookmarks for Quick Access

Workshop - Enhancing Your Dashboard with Groups, Icons, and a Custom Theme

3. Advanced Homer Techniques and Integrations

Custom Assets and Branding

Using Custom Logos and Favicons

Adding Custom Background Images or Videos

Advanced CSS for Complete Visual Overhaul

Integrating with Other Self-Hosted Services

Embedding Content (Limited Scope in Homer)

Using Homer as a Launchpad for Your Homelab

Security Considerations for Your Homer Instance

Exposing Homer to the Internet (Reverse Proxies)

Basic Authentication

Keeping Homer Updated

Troubleshooting and Maintenance

Common Configuration Errors and How to Fix Them

Checking Docker Logs for Issues

Backing Up Your Homer Configuration

Workshop - Advanced Branding and Setting up a Reverse Proxy (Conceptual for Local NPM)

Conclusion

Recap of Homer's Capabilities

Next Steps in Your Self-Hosting Journey

Community and Resources

Understanding Homer's Configuration File (`config.yml`)