Skip to content
Fiction Becomes Fact

Homer NixOS container setup

Introduction

Homer describes itself as: A dead simple static HOMepage for your servER to keep your services on hand, from a simple yaml configuration file.

The dashboard is indeed easy to configure, supports dark mode, and allows for tile grouping. You can also add extra features to tiles, such as displaying info about Pi-hole.

Homer Dashboard

Setup

  1. Add virtualisation to configuration.nix

    Add virtualisation and the import to a seperate nix file for the container to configuration.nix:

    /etc/nixos/configuration.nix
      # To edit use your text editor application, for example Nano
      virtualisation = {
        podman = {
          enable = true;
          dockerCompat = true; # Create a `docker` alias for podman, to use it as a drop-in replacement
          defaultNetwork.settings.dns_enabled = true; # release 23.05
        };
        oci-containers = {
          backend = "podman";
          containers = {
            homer = import ./containers/homer.nix;
          };
        };
      };
  2. Add the macvlan network to configuration.nix

    The container will use a macvlan network (net_macvlan) with a dedicated IP address. Add the following to configuration.nix:

    /etc/nixos/configuration.nix
    # To edit use your text editor application, for example Nano
    systemd.services.create-podman-network = with config.virtualisation.oci-containers; {
      serviceConfig.Type = "oneshot";
      wantedBy = [ "${backend}-homer.service" ];
      script = ''${pkgs.podman}/bin/podman network exists net_macvlan || \ ${pkgs.podman}/bin/podman network create --driver=macvlan --gateway=192.168.1.1 --subnet=192.168.1.0/24 -o parent=ens18 net_macvlan'';
    };
    # IMPORTANT: Please read the instructions below
    Instructions:
    • Required Replace 192.168.1.1 with your gateway IP address
    • Required Replace 192.168.1.0 with your subnet
    • Required Replace ens18 with the name of own network interface
  3. Add a script to create folders to configuration.nix

    Make sure the folders for use with the container are created by adding the following to configuration.nix:

    /etc/nixos/configuration.nix
    # To edit use your text editor application, for example Nano
    system.activationScripts = {
      script.text = ''
        install -d -m 755 /home/<username>/homer/assets -o root -g root
      '';
    };
    # IMPORTANT: Please read the instructions below
    Instructions:
    • Required Replace <username> with your NixOS username
  4. Create the containers folder

    Run the following command:

    # Open your terminal application
    mkdir -p /etc/nixos/containers # Make sure the directory exists
  5. Add the container configuration to homer.nix

    Add the following to homer.nix:

    /etc/nixos/containers/homer.nix
    # To edit use your text editor application, for example Nano
    {
      image = "b4bz/homer:latest";
    

      environment = {
        "TZ" = "Europe/Amsterdam";
      };
    

      user = "root:root";
    

      volumes = [
        "/home/<username>/homer/assets:/www/assets"
      ];
    

      extraOptions = [
        "--pull=newer" # Pull if the image on the registry is newer than the one in the local containers storage
        "--name=homer"
        "--hostname=homer"
        "--network=net_macvlan"
        "--ip=<IP address>"
        "--mac-address=<MAC address>"
      ];
    }
    # IMPORTANT: Please read the instructions below
    Instructions:
    • Required Replace Europe/Amsterdam with your own timezone
    • Required Replace <username> with your NixOS username
    • Optional Replace --pull=newer with --pull=never if you do not want the image to be automatically replaced by new versions
    • Optional Replace net_macvlan with the name of your macvlan network if needed
    • Required Replace <IP address> with the IP address of this container. Make sure it is within the range of the macvlan network
    • Required Replace <MAC address> a (randomly generated) MAC address. Otherwise, every time the container is started, a new mac address will be used, which for example will be created as a new device within the Unifi Network Application. Or temporarily disable this option, and add the MAC address that is generated the first time when this container is started. Use inspect to get the MAC address if needed: sudo podman inspect <container name> |grep MacAddress|tr -d ' ,"'|sort -u
  6. Switch NixOS configuration

    Now you can switch to the new configuration within NixOS, the image will be downloaded and the container will be created:

    Run the following command:

    # Open your terminal application
    sudo nix-collect-garbage # Optional: clean up
    sudo nixos-rebuild switch
  7. Check the results

    Run the following command to check if the container is working properly:

    # Open your terminal application
    journalctl -u podman-homer.service

    Now you can browse to the Homer dashboard by opening a web browser and going to: http://localhost:8080. Replace localhost with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier.

Favorites

Homer Docker Hub

Comments

    No comments found for this note.

    Join the discussion for this note on Github. Comments appear on this page instantly.

    Tags:
    Copyright 2021- Fiction Becomes Fact