← Back to Blog Home

How to Run the Homepage App Via Its Docker Image

Extracurricular Activities
by: Matt Fletcher
A screenshot of the homepage app, illustrating a blog post titled How to Run the Homepage App Via Its Docker Image

Article summary

Homepage is “A modern, fully static, fast, secure, fully proxied, highly customizable application dashboard with integrations for over 100 services and translations into multiple languages.” Earlier this year, I switched to using it over another homepage solution, and I’m quite happy with it overall. I’ll provide an overview of what it looks like to get it running.

As is typical for my homelab, Homepage is another service running as part of one of my Docker Compose environments.

Running the App Via docker compose

Here is what the relevant section of my compose.yml file looks like:


networks:
  homepage:

  homepage:
    container_name: homepage
    image: ghcr.io/gethomepage/homepage:v1.1.1
    restart: unless-stopped

    env_file:
      - ./common.env
      - ./secret.env
    environment:
      - HOMEPAGE_ALLOWED_HOSTS=[secret elided]
    # - LOG_LEVEL=debug
    networks:
      - homepage
    ports:
      - 80:3000
    volumes:
      - ${SERVICE_DATA_DIR}/homepage:/app/config
      - ${SERVICE_DATA_DIR}/homepage-data:/app/public/images

Additionally, here is what some of the configuration in the homepage directory looks like. This is a snippet from my services.yaml file. The file is long, so this is simply a preview. Secret values are not included, of course.


- Utility:
    - Speedtest Tracker:
        href: [secret elided]
        icon: speedtest-tracker
        widget:
          type: speedtest
          url: [secret elided]
          bitratePrecision: 2
    - Code-server:
        href: [secret elided]
        icon: code-server
    - Duplicacy:
        href: [secret elided]
        icon: duplicacy
    - filebrowser:
        href: [secret elided]
        icon: filebrowser
    - it-tools:
        href: [secret elided]
        icon: it-tools
    - Librespeed:
        href: [secret elided]
        icon: librespeed
    - netboot.xyz:
        href: [secret elided]
        icon: netboot

About This Configuration

Compose configuration

First we define the network and image to use for this container. Here I am using the latest image version hosted on ghcr.io.

Next we include environment files for the various common and secret environment variables shared across containers.

The environment section is relatively small compared to most. It is critical to include the HOMEPAGE_ALLOWED_HOSTS value, or else you will effectively be unable to access the container. Read more about how to set this value here. I also have LOG_LEVEL present but commented out — at one point, I was using it to debug a problem, but now that things are running smoothly, I’ve left it here for reference.

Of course, I also need to specify the container’s port mappings. In this case, there’s a sole mapping being used: I am mapping 80 externally to 3000 internally. Since I use Homepage as, well, my homepage, it make sense for it to be running on 80.

Lastl,y I have my volume mappings. There are two: the primary is for the majority of homepage data (homepage) and the secondary is for images (homepage-data). I’m not all that certain why the author of this image has the split between the two directories; perhaps because of where the web server being used is looking for files? Whatever. I’ll go with it.

Homepage configuration

Aside from a couple of environment variables, the vast majority of Homepage’s configuration is done via a set of YAML files. You can read about all of them here. There’s a good amount, so I’m not going to include most of it here, since it would make this blog post unreadable.

Instead, I’ve included a snippet above. You can see the configuration for a handful of services here. Most are simply a link (which are secret to me, so are left out of the example) and an icon to use. The value for the icon key pulls from a handful of sources documented here. I super appreciate this feature! It makes it super duper easy to include, what is almost always, official icons.

I will also point out that the Speedtest Tracker app includes a widget. Widgets often provide a quick reference to additional data and, in my opinion, look quite nice visually.

Screenshot of Homepage's Speedtest Tracker widget.
Homepage’s Speedtest Tracker widget.

Not gunna lie: it did take me several hours to get the container running and configured for my couple dozen services. None of it was hard. It was mostly a matter of flipping back-and-forth between YAML files, documentation, and my browser refreshing. But with that initial hump out of the way, the changes I make every few weeks are significantly easier. All I need to do is touch up a few lines of YAML and I’m done — no more fiddling with lousy wysiwyg tools. I also appreciate being able to check it into source control.

Conclusion

Once I got Homepage running, I went to my various web browsers and updated my bookmarks, homepage, etc. I’m pretty happy with the result — primarily with the visuals. I like the overall layout and visual design; it is quite easy on the eyes and far better than my old solution.

Thanks to the Homepage project for the wonderful solution!

Past Posts in This Series

Over the last several years, I have produced a number of posts like this for various applications. Below is the complete list. Note: I do not maintain these posts over time, so some may be out of date or otherwise irrelevant. They are left as references only.

Related Posts

Conversation

Join the conversation

Your email address will not be published. Required fields are marked *