I've been using the same homepage dashboard for quite a while. As I mentioned in my Homelab services tour, I wanted a dashboard with a little more flexibility that I could pass a config to. And that's when I found Homepage. Yeah, that's what it's called. It's called Homepage. Homepage is a fast, and secure homepage that's fully customizable, and it's fully static, meaning you're going to get the best performance out of it. It integrates with over a hundred services and is fully customizable using YAML. This lets you configure widgets and buttons on your homepage that can retrieve additional data about your services. This makes your self-hosted homepage dashboard a lot more useful than a list of static buttons. But you can also configure static buttons too. It's that flexible. And you get all of this inside of a Docker container that's compatible with Docker, Kubernetes, and even Unraid. So that's what we're going to do today. We're going to set up and configure Homepage using Docker. We're going to add some services to it and customize it to our needs. And then we're going to add some widgets to it to make these buttons light up. We'll also talk about how to do this in Kubernetes if you're interested. And I'll share my configuration for both Docker and Kubernetes on my documentation site. Sound good? Let's configure Homepage. So first you'll need a machine with Docker installed. If you need help setting up Docker, I have documentation on how to do that in my documentation site. And you can see that in the links below. Then you'll want to remote in or SSH into your server so we can set up the additional files. Once you've remoted into your server, you'll want to create a directory to hold some of our configuration files. I do this inside of a folder called docker_volumes. So first we'll make a directory called Homepage. Then we'll cd into that directory. Then we'll create a Docker compose file to hold our Docker YAML. Then let's edit this Docker compose file. So what's going to go inside this Docker compose file? Well, it's this YAML right here. So let's talk about it. First, we're going to use Docker compose version 3.3, which is not that important. But you should be sure that you have at least 3.3 installed. Then we're going to use this image right here. So this is coming from the GitHub container registry. And it's going to grab the Homepage container image on the tag latest. Then we're going to expose some ports. So 3000 on the outside and 3000 on the inside. Then we're going to specify a .env file to hold some of our variables. We'll create that here in a second, but let's continue on. And then we want to map some volumes. You can see this container on the inside, it's going to map to a folder called app/config. So on the outside, we also need to map to a folder called config. We haven't set up yet. But we'll create it right here. The next volume we're going to map is to the Docker process itself. So the Docker sock. And this is really optional. I'm not going to use it. But if you need to get some additional information from the Docker host that it's running on, you can keep this volume. But for me, I'll just comment it out for now. And for PUID and PGID, these are needed if you don't want to run the container's route, which you probably don't. So we're going to need to pass our PUID or user that's running Docker. And our PGID, the group that that user belongs to. And instead of hard coding them here, we're going to actually add them to our .env. So we have a couple of tasks to do. We need to create a .env file. We need to add our PUID and our PGID to it. And then we need to create a config folder that we can map our config to. So let's do that. So back in our terminal, the first easy thing to do is to make a directory called config. So that's done. Then we need to find our PUID and our PGID. You can do that by typing in ID. And you'll see here, the one I'm using is 1000 and 1000. So we need to add that to our .env, which we don't have. So let's create a .env file. And here, we're going to put PUID. So our variable is 1000. And then we'll add PGID, which is also 1000. Helps if I type 1000. So our container, when it starts up, it's going to read our .env file and then substitute these variables with their values. So this is good, we could save this, close out. And now we need to copy the YAML contents from here into that Docker compose file on our server. So let's edit this. Edit our Docker compose. Paste the contents. Save. And then exit. Now that we have that in place, we can start up this container. So we're going to do that with Docker compose up -d. Now note that this container takes a little bit of time to start up. It also has health checks in place. And so it won't be fully up for around 60 seconds I've seen. But you can check by doing a docker ps. And we can see here that this started 20 seconds ago. And the health check is still in a starting state. So we'll need to be sure that that's healthy before we actually go out to the web page. And just a little tidbit on troubleshooting if you go out to the web page and you see it hasn't started yet. So now we can see around 51 seconds it says healthy. So now we can go to that server on port 3000 and see our homepage. And if we go to the server on that port 3000 we can see our homepage. So this is pretty nice a quick walkthrough. So we can see the CPU usage that this node is using or this machine is using. How much RAM it's using. How much free space it has. We have a search bar here if we want to search with DuckDuckGo and this is configurable. Then we have a couple of groups for some home pages. First group, second group, third group. And then we have some additional bookmarks right here for GitHub, Reddit, and YouTube. And then down here you can see we can change our color palette if we wanted it to be this pink or a green we could or go back to slate or this blue. And then over here if we wanted to, I don't know why you would want to, check out light mode you totally could. But if that's your thing that's where it is. And you can toggle it back to dark mode where it should be. And then you see this little refresh right here. This refresh is actually to refresh your configuration. So as we make configuration changes as you'll see coming up we can refresh this which will reparse our configuration and we don't need to start and stop our container over and over. This will happen automatically though too as you'll see. So let's start customizing this. Let's customize a few things. As I mentioned earlier this uses YAML to configure it. And you can see here we don't have any YAML specified. That's because it's going to be inside of this config folder right here. So if we go inside of that config folder on the server we should see some additional files for a configuration. So back on the server if we cd into that config directory and we do an ls to c we can see we have bookmarks, we have a kubernetes.yaml, services.yaml, widgets.yaml, and settings.yaml. And this is what we'll use to configure our homepage. So for example if we wanted to change some settings for this homepage let's look at the settings.yaml. And you can see here we only have a provider configured. But if we wanted to set say our title to my awesome homepage instead of using the default homepage we can set the title there in YAML, save this, close here. And if we look at the title now it says my awesome homepage. So this worked. If we wanted to change the background for instance maybe something a little more creative and something that you can actually see we can set the background property and then set it to an image on the internet. You could also do a bind mount local and set it to a local image but I'm going to use one from the internet. So if we save this, close out, go back to our webpage and you see it refresh and you can see we have a background image now. Pretty cool. But let's say this image is too distracting or maybe it's not the right color or we wanted to add a blur to it. We can do that too. If we go back into our configuration and add some additional properties this time making the image a property off of background and then adding a blur, adding a saturate, adding a brightness and adding opacity we can configure these to our liking. Now these are all based on Tailwind CSS, a CSS library that's really awesome and it only has certain values you can configure. So if you want to see which ones are configurable you should see the Tailwind documentation. But for the most part these should work and there are some examples I set here as well. So this should blur it, decrease the saturation, decrease the brightness and decrease the opacity which should make it less distracting. So let's save this and as you can see this is a lot more muted now. So less color, more blur, more opacity, it looks really nice. Now let's say we wanted to do a couple of more things. Let's say we wanted to hard code the theme to dark because why would you ever want light mode? And say we wanted to get rid of the color palette picker and hard code it to slate. Well we can do that by adding this. So we're going to hard code the theme to dark and then we're going to hard code the palette to slate. So let's save this, go back to our home page we see a quick refresh and it kind of looks the same because I had that set already. But what you notice is we don't have the palette picker here anymore and we don't have lighter dark mode picker here anymore. So awesome, it's starting to come together. So our home page is looking pretty good so far but let's say we wanted to add another group to this. Let's say we wanted to add a fourth group with our own services. How would we do that? Well we would do that now by configuring the services.yaml so let's take a look in there. If we look in here we see our first group, our second group and our third group. And this aligns to these groups that we see here. So if you want to change these, get rid of them or add more we would do this in the services.yaml. So let's add another group to this. So I just paste it in this yaml and I'm creating a new group called top services. I'm going to name this one called proxmox and then I'm going to list the icon as this proxmox.png. Probably wondering how do you know there's a proxmox.png? If we take a look at this dashboard icons repo it has icons for a lot of the services that we're going to be using. And it's also compatible with a lot of other dashboards out there. So the homepage project leans into this repo and we can use any PNG or SVG that is in here and only reference it by name which is pretty cool. We wanted Airsonic SVG, it's right here. Or we wanted to use the AMD PNG, the logo, it's right here. It's kind of hard to see in dark mode but if we wanted the Android logo it's right here. So we only need to reference it by name which is really nice. So going back to our services yaml the href is going to be the URL that it brings us to when we click on it. We can add an additional description with this description property. Anything we'd like. And there's some other things I'll show you here in a little bit. And so I'm adding a couple of services. One's called proxmox, one's called piehole, one's called cowboy and one's called McDonald's. And you can see here I don't have an icon listed at all. You can see on this cowboy one I'm using one called mdi account cowboy hat. And then I'm passing in a hex value. What the heck is that from? Well they also pull in material design icons and simple icons too. So you can refer to these either by their icon name from pictogrammers. And so we can refer to these by their icon name. If you see account cowboy hat we can use this one from material design icons. Or we can use any of these icons from simpleicons.org. So super nice, a lot of flexibility, and we have a lot of ways to get icons instead of trying to find them ourselves. And so the way that you reference them is like this. If you want to use a material design icon, you put mdi dash and then the icon name. And then if you want to configure the color, you add the hex value. So I think this one's going to be red. And the same goes for the simple icons. If you want to use a simple icon at SI and then dash the icon name, which I'm putting in McDonald's. And then this hex is gold, which you'll see here in a minute. And that will give us a gold McDonald's icon. So let's save this and apply it and look at our homepage. So here it is. Now we've created this fourth group called top services. We have an icon for Proxmox. We have an icon for piehole. We have an icon for cowboy. And then we have an icon for McDonald's. And if you click on these, it should bring you to the page we were talking about. Here's McDonald's. So I mentioned earlier that we can get data from these services and make these icons a little bit more useful. And if we go to the homepage widget sections, we can see lots of services that we can communicate with to pull in some more information. For instance, we can see piehole here. And on piehole, it has a widget that we can configure. And once configuring it, it will light up this button with our queries for piehole, our blocked count, our block percent count, and gravity or the count of block lists or hosts we have in our block list. And we could do that simply by adding this widget property of type piehole with a URL to our piehole service and an API key on top of that service that we already created. You know, that sounds confusing, but let's show you how that's done. First, you'll need to grab an API key from your piehole instance. That can be done within settings, within API, and then showing your API token. Grab that and save it really quick. Then we'll need to edit our YAML on the server. And what we're going to do now on piehole is add the widget property with the type piehole, everything we saw on their webpage, along with our API key. Now, you can add the API key here if you want, but you probably shouldn't. What we're going to do is add it to our .env file, and then homepage can parse that .env file and do a replace on this property when the service starts up. And if you'll notice, this starts with homepage_var_piehole. Now homepage will only replace variables that are prefixed with this homepage_var_pyhole. Everything else is something you said. So on the left side is what they're looking for. On the right side is what you define. So let's add this to our .env really quick. Let's edit our .env file, which is one folder up. Edit this. Let's add our homepage var_piehole_api_key equals, then you'll paste your API key here. Then we'll go back to our homepage and you'll notice we have an error. This is because it tried to do a string replace right now on that variable, but the environment variable wasn't loaded yet. So Docker only reads these environment variables when the container starts up. So we need to stop the container, start the container again, and then homepage will be able to read that variable and do a string replace, and then we should be able to get to our .pyhole. So let's do that really quick. Let's do a Docker stop on this container, and this is homepage. Let's stop that container, and once that stopped, we can start it back up with a Docker start homepage. Remember when we start and stop, we're going to have to check to make sure that the help checks pass. So let's do a Docker PS. The help is still starting. So it's going to take a little bit when this container starts. There we go. It's healthy. And if we come back to our homepage now, we can see that the homepage server that's running behind the scenes can communicate with our .pyhole API. And you can see I've done a quarter of a million queries. I've blocked 7,000 of those, which is about 3%, and I have 1.5 million hosts on my gravity block list. So pretty cool. Another cool thing you can do with widgets is add them standalone too. Now, I know we added a widget to our service here for .pyhole, but as you can see, we have widgets here that are standalone for our system information. Where do you configure that? Well, in the widgets, YAML. So let's configure that. So if we go back into our server again and edit our widgets.yaml, you can see we have a resource widget and a search widget. Now, if we wanted to change our search provider, this is pretty easy to Google or any other search provider that it supports, we would change that here. But let's say we wanted to add another widget altogether. Let's say I wanted to add date and time, and I wanted to format it a certain way. Well, I could do that by using the date time widget and specifying it here. So let's save this really quick. Let's go back to our homepage. And as you can see, when it refreshed, now I'm searching with Google. And now I have this date time widget here. So pretty cool. So homepage is really flexible. But one of the things that I wanted to do was recreate my Heimdall homepage that you can see here with homepage. And I probably spent way too much time doing it, but that's Homelab, right? And I think I've been able to recreate my old dashboard now using homepage's dashboard. So you can see I have a group of hypervisors. All of my Proxmox servers are connected. I have a group for containers with Portainer connected. Now I could connect Rancher or Kubernetes, but I decided not to at this time. The same goes for my DNS. The same goes for my UniFi network, Uptime Kuma, and Uptime Robot. I even have some external services configured. TrueNAS, which I've been able to connect to. Minio, which this is just a homepage button for me to get to it quickly. Plex, you can see how many active streams. There are also some other items that are configurable here too. Touchily. HD Home Run, this tells me how many channels I have and how many of them are HD. Not too helpful. I wish it showed me how many active streams are being used or how many streams are actually free. Home Assistant, how many people are home, lights on, etc. So a lot of things that you can configure. And I think that I've been able to recreate my dashboard pretty okay. And as I mentioned earlier, one of the reasons why I love homepage and being able to pass a config to it is because I can share that configuration. So if you want to use my dashboard, absolutely you can. I'll have it on my documentation site. So I factored all of my secrets or all of my variables out of the actual configuration and put them in a .env file, which I'm not going to show you. So that you can use this as is, tune it to your liking, and then just supply your values in a .env file. And then you don't have to worry about keeping your secrets and environment variables in code. And you get the benefit of using a dashboard that looks like mine, or at least have a good starting place. And next for me is creating a Kubernetes config file that I can use instead of using a persistent volume, so that I don't have to use persistent volumes. And I can scale my dashboard to more than one, making it highly available. It's pretty complicated. I'll share the Almond documentation site too. Well, I learned a lot about this self-hosted homepage dashboard, and I hope you learned something too. And remember, if you found anything in this video helpful, don't forget to like and subscribe. Thanks for watching.
