====== Homepage ======

[[https://homepage.dev|Homepage]] is an amazing web dashboard, very customizable and mostly static, that you can use to create a landing page for your services. It's quite pretty and can be customized extensively. It also comes with a pre-integration with many common self-hosted services.

==== Installation ====

As usual, create the dedicated user and the required folders. In addition, you need to create folders for custom icons, images and configuration. Also, since homepage will create quite some logs, better create a dedicated log folder and process it with logrotate:
<code bash>
useradd -d /data/daemons/homepage -m homepage
mkdir /var/log/homepage
chown homepage:homepage /var/log/homepage
su - homepage
mkdir -p config
mkdir -p images
mkdir -p icons
</code>
(don't forget to add the /var/log/homepage/logs/homepage.log file to logrotate settings under /etc/logrotate.d/!). Homepage will create a //logs// subfolder, i don't like it too much, but whatever, it works.

the config, icons and images folders needs to be mapped in the container, see the docker compose:
<file - docker-compose.yml>
services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    ports:
      - 3000:3000
    volumes:
      - /data/daemons/homepage/config:/app/config 
      - /data/daemons/homepage/icons:/app/icons 
      - /data/daemons/homepage/images:/app/images 
      - /var/log/homepage:/app/logs 
</file>
Of course, adapt the port 3000 to whatever you need on your setup.

Then pull the images:
<code bash>
su - homepage
podman compose pull
podman compose up
</code>

Home page does not provide any kind of authentication, it must be added by your [[selfhost:nginx|reverse proxy]] and [[selfhost:sso|SSO provider]], see the paragraph with the reverse proxy configuration.

For logrotate, create the following file:
<file - /etc/logrotate.d/homepage>
/var/log/homepage/logs/homepage.log {
    missingok
    notifempty
}
</file>

==== Configuration ====

You should read the quite detailed [[https://gethomepage.dev|documentation]], i will detail a few issues i ran into.

For specifics on initial configuration check out the great documentation [[https://gethomepage.dev/configs/settings|here]]. 

Homepage is divided in:
  * Services, or links to your services, they can include widgets
  * Widgets, which are run-time display of data from services, and are always associated to services
  * Information Widgets, which are confined to the top-level header of the page to show small amount of data
  * Bookmarks, which are links to other web pages

Widgets are cool to show //on the flight// data about a service, but they can pose an issue when your Homepage is behind SSO.

Sometimes new images or icons are not picked up, in this case restarting the container fix the issue.

I choose not to monitor directly resources in Homepage, first because the build-in //resource// widget and info widget will not work due to the containerization (it will monitor the //container// and not the server itself), and because Glances was using a little bit too much resources for my taste. Not too much mind you, but i prefer to have Glances on it's own (see [[services:glances|this page]]) and then add it to Homepage as a clickable service. This allows the actual Glance overhead to kick in only when i want, and not whenever and wherever i have one or more Homepages open around.

As a suggestion, don't apply image modifications for your backgrounds in homepage but directly modify the image with GIMP / Krita or whatever tools you like. In fact, applying resizes or blurs or brightness or other corrections, while quick and easier, directly in Homepage will result in additional CPU consumption every time you open Homepage, which is a waste, and can be pretty slow on mobile browsers.

==== Reverse Proxy configuration ====

Follow the [[selfhost:nginx|The Reverse Proxy concept]], then create the following specific NGINX configuration file:
<file - homepage.conf>

location / {
        proxy_pass   http://127.0.0.1:3000;
    }
</file>

and restart your NGINX.

I assume you have already protected your subdomain with your SSO, but there is a current caveat with Homepage... Since it will not detect when an authentication token has expired, it will not force a reload of the homepage itself to trigger the SSO login page. This means that if you leave your homepage open, after authentication expires, all your widgets will stop working and lots of errors will propagate in your logs. Due to this issue, i prefer **not** to use widgets in my Homepage setup.


==== Autostart ====

If you follow the approach defined in [[gentoo:containers|Using Containers on Gentoo]], yo uare using my **user-containers** script. Then create the config file:
<file - /etc/conf.d/user_containers.homepage>
USER=homepage
DESCRIPTION="Homepage Dashboard"
</file>

and the link (as root):
<code bash>
ln -s /etc/init.d/user-containers /etc/init.d/user-containers.homepage
rc-update add user-containers.homepage default
/etc/init.d/user-containers.homepage start
</code>