Homepage on VPS: installation, setup, and maintenance

Homepage on VPS is a personalized control panel for quick access to your self-hosted applications and services, installed on a virtual server for centralized monitoring and navigation across your entire infrastructure. This article will detail how to install Homepage on a VPS, configure it for optimal performance, and ensure regular maintenance, including backups and updates. We will cover system requirements, step-by-step installation via Docker/Compose, integration with a reverse proxy (Nginx/Caddy) for secure HTTPS access, and provide recommendations for choosing the right VPS configuration for various Homepage use cases.

In a world where everyone strives for maximum efficiency and control over their digital environment, tools for centralized management become a necessity. Homepage is precisely such a tool: a flexible, customizable, and powerful dashboard that allows you to gather all your important links, API metrics, and service status information in one place. Imagine having a single portal from which you can launch code-server, check Docker container logs via Dozzle, or navigate to your project management panel in OpenProject – all from one page, accessible from anywhere in the world via your own VPS. This is why installing Homepage on your own virtual server is the choice of many enthusiasts and professionals.

What is Homepage and why do you need it on a VPS?

Homepage is a modern, customizable start screen or dashboard that provides convenient and quick access to your self-hosted applications, services, monitoring, and other useful information. It is designed for those who manage multiple local or remote services and want a centralized place to organize them. Deploying Homepage on a VPS allows you to create your own web portal, accessible from anywhere in the world, without relying on third-party cloud services.

The main idea behind Homepage is to aggregate information and links into an intuitive interface. You can add shortcuts for your web applications (e.g., Nextcloud, Jellyfin, AdGuard Home), widgets to display system information (CPU, RAM, disk usage), metrics from APIs (e.g., weather, news, server status), and much more. All of this is configured via simple YAML files, making Homepage an incredibly flexible and powerful tool for organizing your digital space.

Advantages of self-hosting Homepage on your own server

• Centralized Access: All your services and links are gathered in one place, reducing the time spent searching for the right application.
• Full Control: Since Homepage is self-hosted on your VPS, you have complete control over data, security, and configuration, without relying on third-party providers.
• Customization: Flexible customization of appearance, themes, shortcuts, widgets, and integrations to meet your specific needs.
• Monitoring: Ability to display service status, system metrics, and data from various APIs directly on the dashboard.
• Independence: No ads, restrictions, or subscriptions inherent in many cloud solutions.
• Security: You manage access and security yourself, using tools like Reverse Proxy and HTTPS, which is especially important when Homepage on the server becomes the entry point to your infrastructure.

Key Features and Capabilities

• Categories and Bookmarks: Organize links by categories for easy navigation.
• Widgets: Built-in widgets for displaying time, date, weather, network status, system resources, etc.
• API Integration: Support for a wide range of APIs to retrieve data from various services (Sonarr, Radarr, Plex, Pi-hole, Proxmox, TrueNAS, and many others).
• Search: Built-in search bar for quickly finding desired services or information.
• Themes and Styles: Ability to choose from many pre-installed themes and create custom CSS styles.
• Automatic Discovery: Integration with Docker API for automatic detection and display of running containers.

System Requirements for Installing Homepage on a VPS

Homepage is a relatively lightweight application, especially if it's primarily used as a collection of links and simple widgets. However, when you start adding many API integrations, monitoring a large number of services, and an active Docker socket, resource requirements can increase slightly. Deploying Homepage on a VPS via Docker makes it even more efficient, as the container uses minimal resources.

Minimum and Recommended Configurations

For successful Homepage installation and comfortable operation on a VPS, consider the following recommendations:

• Processor (CPU):
  • Minimum: 1 vCPU (virtual core) with a frequency of 1.5 GHz. This is sufficient for running Homepage and a few basic widgets.
  • Recommended: 2 vCPU with a frequency of 2.0 GHz or higher. This will ensure smooth interface operation, fast widget loading, and stable performance with multiple API integrations.
• Random Access Memory (RAM):
  • Minimum: 512 MB. Homepage itself in a Docker container consumes about 50-100 MB of RAM. The rest will be used by the operating system and Docker Engine.
  • Recommended: 1 GB or 2 GB. This will allow the operating system (e.g., Ubuntu Server), Docker Engine, and Homepage itself to run comfortably, as well as provide headroom for other background processes or small Docker containers you might want to run on the same VPS.
• Disk Space (Storage):
  • Minimum: 10 GB NVMe/SSD. Most of this volume will be occupied by the operating system and Docker Engine. Homepage itself takes up very little space (a few tens of megabytes for the image and configuration).
  • Recommended: 20-40 GB NVMe/SSD. This will provide enough space for the system, Docker images, logs, Homepage configuration backups, and possibly other small applications. NVMe or SSD drives are critically important for I/O operation speed, which ensures fast application loading and system responsiveness.
• Network Connection:
  • Minimum: 100 Mbps.
  • Recommended: 1 Gbps. High connection speed will ensure fast external access to Homepage and prompt data loading from APIs.

Choosing an Operating System

For deploying Homepage via Docker, stable Linux distributions are recommended. The most popular and well-supported options are:

• Ubuntu Server (LTS versions, e.g., 22.04 or 24.04): Widely used, has extensive documentation and a large community. An excellent choice for most users.
• Debian (Stable versions): Known for its stability and security, slightly more minimalistic than Ubuntu.
• CentOS Stream / AlmaLinux / Rocky Linux: A good choice for those who prefer RHEL-like distributions.

Ensure that the chosen OS has a minimal installation without unnecessary graphical interfaces to free up maximum resources for your Homepage Docker container and other applications.

Preparing your VPS for Homepage Installation via Docker

Before proceeding with Homepage installation, you need to prepare your VPS. This includes updating the system, installing Docker Engine and Docker Compose, and creating the necessary directories for storing configuration files.

System Update and Docker Engine Installation

Start by connecting to your VPS via SSH and update the package list, then upgrade all installed packages to their latest versions. This will ensure all necessary dependencies and security patches are in place.

sudo apt update
sudo apt upgrade -y

Next, install Docker Engine. It is recommended to use the official Docker installation script, which guarantees you get the latest stable version.

sudo apt install ca-certificates curl gnupg -y
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

Add your user to the docker group to execute Docker commands without sudo (remember to log out and log back into your SSH session for changes to take effect):

sudo usermod -aG docker $USER

Verify that Docker is installed and running:

docker run hello-world

You should see the message "Hello from Docker!".

Creating Directories and Setting Permissions

Create a separate directory to store Homepage configuration files. This will help maintain order and simplify the backup process.

mkdir -p ~/homepage/config

Now we are ready to create the docker-compose.yml file and configure it.

Step-by-Step Homepage Installation on a VPS with Docker Compose

Homepage installation is most effectively done using Docker Compose. This allows you to define all container parameters (image, ports, volumes, environment variables) in a single YAML file, simplifying management and deployment.

Configuring the docker-compose.yml file

Navigate to the created directory and create the docker-compose.yml file:

cd ~/homepage
nano docker-compose.yml

Paste the following content. This file describes the minimal configuration for running the Homepage Docker container:

version: '3.3'
services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    ports:
      - 3000:3000
    volumes:
      - ./config:/app/config # Directory for Homepage configuration files
      - /var/run/docker.sock:/var/run/docker.sock:ro # For Docker API integration
    environment:
      PUID: 1000 # User ID under which the container will run
      PGID: 1000 # Group ID under which the container will run
      TZ: Europe/Moscow # Your timezone
    restart: unless-stopped

Let's break down the main parameters:

• image: ghcr.io/gethomepage/homepage:latest: Specifies the use of the latest stable Homepage image from GitHub Container Registry.
• container_name: homepage: Assigns a descriptive name to the container.
• ports: - 3000:3000: Maps container port 3000 to host system port 3000. This means Homepage will be accessible at http://YOUR_VPS_IP:3000.
• volumes::
  • ./config:/app/config: Mounts the local ./config directory (which we created earlier) inside the container at /app/config. All your Homepage settings, including settings.yaml, services.yaml, and others, will be stored here. This is critically important for preserving data when updating the container.
  • /var/run/docker.sock:/var/run/docker.sock:ro: Mounts the host system's Docker socket inside the container in "read-only" mode (ro). This allows Homepage to interact with the Docker API and display information about other running Docker containers (e.g., their status).
• environment::
  • PUID: 1000 and PGID: 1000: Define the user and group IDs under which processes will run inside the container. Typically, 1000 corresponds to the first created user (your user) in most Linux systems. You can find your IDs by running id -u and id -g on your VPS.
  • TZ: Europe/Moscow: Sets the timezone for the container. Replace with your timezone (e.g., America/New_York, Asia/Tokyo).
• restart: unless-stopped: Ensures that the container will automatically restart after failures or VPS reboots, unless you manually stop it.

Launching Homepage and Initial Configuration

After saving the docker-compose.yml file (Ctrl+O, Enter, Ctrl+X in nano), launch the container:

docker compose up -d

The -d option runs the container in detached mode (background). Docker will download the Homepage image, create the container, and start it.

Check the container status:

docker compose ps

You should see that the homepage container is in "Up" status.

Now you can access Homepage by opening http://YOUR_VPS_IP:3000 in your browser. You will see the basic Homepage interface.

To configure Homepage, you will need to edit the YAML files in the ~/homepage/config directory. The main files are:

• settings.yaml: General Homepage settings (theme, language, widgets).
• services.yaml: Definition of your services and links.
• widgets.yaml: Additional widgets.

Example services.yaml:

- Home:
    - Valebyte:
        icon: https://valebyte.com/favicon.ico
        href: https://valebyte.com
        description: VPS and dedicated servers
    - Dozzle:
        icon: docker
        href: http://YOUR_VPS_IP:8080 # If Dozzle is running on the same VPS
        description: Docker log monitoring
    - NocoDB:
        icon: database
        href: http://YOUR_VPS_IP:8081 # If NocoDB is running on the same VPS
        description: Database as a spreadsheet

After each change to the configuration files in the ~/homepage/config directory, Homepage automatically reloads them, and the changes immediately appear in the browser. If changes are not visible, clear your browser cache or restart the container:

docker compose restart homepage

Remember that for working with Homepage on the server and its integrations, such as NocoDB, it is important to correctly configure ports and access.

Configuring Reverse Proxy (Nginx or Caddy) and HTTPS for Homepage

Accessing Homepage via an IP address and port 3000 is neither secure nor convenient. To ensure secure access via a domain name and encrypt traffic (HTTPS), a reverse proxy must be used. Nginx and Caddy are two popular choices for this task.

Why a Reverse Proxy and HTTPS are needed

• HTTPS (SSL/TLS): Encrypts all traffic between your browser and the server, protecting your data from interception. This is critically important for any publicly accessible web service.
• Domain Name: Allows you to access Homepage via a convenient domain name (e.g., homepage.yourdomain.com) instead of an IP address and port.
• Port Masking: A reverse proxy allows you to hide port 3000, making Homepage accessible on the standard port 443 (HTTPS).
• Centralized Management: You can use a single reverse proxy to route traffic to multiple applications running on your VPS.
• Additional Security: A reverse proxy can act as a first line of defense, filtering malicious traffic.

To configure HTTPS, you will need a domain name pointing to your VPS's IP address. You will also need to open ports 80 (HTTP) and 443 (HTTPS) in your firewall (e.g., UFW):

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Nginx Configuration for Homepage

First, install Nginx:

sudo apt install nginx -y

Then create a new configuration file for your domain (e.g., homepage.conf) in the /etc/nginx/sites-available/ directory:

sudo nano /etc/nginx/sites-available/homepage.conf

Paste the following basic configuration (replace homepage.yourdomain.com with your domain):

server {
    listen 80;
    server_name homepage.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Create a symbolic link to this file in sites-enabled and test the Nginx configuration:

sudo ln -s /etc/nginx/sites-available/homepage.conf /etc/nginx/sites-enabled/
sudo nginx -t

If there are no errors, restart Nginx:

sudo systemctl restart nginx

Now your Homepage is accessible via HTTP at http://homepage.yourdomain.com. For HTTPS, use Certbot:

sudo snap install core
sudo snap refresh core
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo certbot --nginx -d homepage.yourdomain.com

Certbot will automatically configure Nginx for HTTPS and add automatic certificate renewal. Follow the on-screen instructions. Once completed, your Homepage will be accessible at https://homepage.yourdomain.com.

Caddy Configuration for Homepage

Caddy is a modern web server that automatically manages HTTPS certificates with Let's Encrypt, making it very convenient for self-hosted applications. Install Caddy:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy -y

Create or edit the /etc/caddy/Caddyfile file:

sudo nano /etc/caddy/Caddyfile

Remove any existing content and add the following configuration (replace homepage.yourdomain.com with your domain):

homepage.yourdomain.com {
    reverse_proxy localhost:3000
}

That's it! Caddy will automatically obtain and configure an HTTPS certificate for your domain. Restart Caddy:

sudo systemctl restart caddy

Now your Homepage will be accessible at https://homepage.yourdomain.com.

Backup and Update Homepage on VPS

Regular backups and timely updates are critically important aspects of maintaining any application, especially when it comes to Homepage on the server, which serves as a central access point to your infrastructure.

Homepage Data Backup Strategies

All important Homepage data is stored in the ~/homepage/config directory, which we mounted as a Docker volume. This significantly simplifies the backup process.

What needs to be backed up:

• The entire ~/homepage/config directory.

Backup methods:

1. Manual Copying:

   You can simply copy the config directory to a safe location on your VPS or download it to your local computer via SCP/SFTP.

   cp -r ~/homepage/config ~/homepage_config_backup_$(date +%Y%m%d%H%M)
   

   To download to your local machine (from your local machine's terminal):

   scp -r user@your_vps_ip:~/homepage/config ~/homepage_backup/
   

2. Automated Backup (Cron + Rsync/Rclone):

   For automation, you can use cron and rsync or rclone to copy data to remote storage (e.g., S3-compatible cloud storage, Google Drive, Dropbox).

   Example script for backing up to a local folder:

   #!/bin/bash
   BACKUP_DIR="/var/backups/homepage"
   CONFIG_DIR="/home/$USER/homepage/config"
   TIMESTAMP=$(date +%Y%m%d%H%M%S)
   ARCHIVE_NAME="homepage_config_${TIMESTAMP}.tar.gz"
   
   mkdir -p $BACKUP_DIR
   tar -czf "${BACKUP_DIR}/${ARCHIVE_NAME}" -C "$(dirname "$CONFIG_DIR")" "$(basename "$CONFIG_DIR")"
   
   # Delete old backups (e.g., older than 7 days)
   find $BACKUP_DIR -name "homepage_config_*.tar.gz" -type f -mtime +7 -delete
   
   echo "Homepage config backup created: ${BACKUP_DIR}/${ARCHIVE_NAME}"
   

   Save this script as ~/backup_homepage.sh, make it executable (chmod +x ~/backup_homepage.sh), and add it to cron for daily execution:

   crontab -e
   

   Add a line for daily execution at 3:00 AM:

   0 3 * * * /home/$USER/backup_homepage.sh >> /var/log/homepage_backup.log 2>&1
   

Homepage and Docker Container Update Process

Thanks to the use of Docker Compose, updating Homepage comes down to a few simple commands.

Update steps:

1. Navigate to the directory with docker-compose.yml:

   cd ~/homepage
           

2. Stop the current Homepage container:

   docker compose stop homepage
           

3. Pull the latest Homepage image:

   docker compose pull homepage
           

   This will download a new version of the ghcr.io/gethomepage/homepage:latest image, if available.

4. Start the container with the new image:

   docker compose up -d homepage
           

   Docker Compose will recreate the container using the new image, but will preserve all your data as it is in the mounted ./config volume.

5. Clean up old Docker images (optional):

   After an update, old images may remain, taking up space. They can be removed:

   docker image prune -f
           

Important notes:

• Always back up the config directory before updating to be able to roll back in case of problems.
• Check the official Homepage GitHub repository or their documentation for important changes or update instructions that may require modifications to docker-compose.yml.

Which VPS configuration to choose for Homepage under real load?

Choosing the right VPS configuration for Homepage on a VPS depends on your needs. Homepage itself doesn't require many resources, but if you plan to host other applications on the same VPS or use Homepage with a large number of widgets and API integrations, it's worth considering a more powerful solution.

Comparison Table of VPS Configurations for Different Scenarios

Below is a table that will help you choose a Valebyte VPS configuration for various Homepage use cases. Prices are approximate and may vary.

Usage Scenario	CPU (vCores)	RAM (GB)	NVMe/SSD (GB)	Bandwidth (Mbps)	Approximate Cost/Month (Valebyte VPS)	Recommendations
Minimal (Homepage only, a few links)	1	1	20	500	From $4.99	Basic plan, ideal for getting started and personal use with minimal widgets.
Standard (Homepage + 2-3 Docker applications)	2	2	40	1000	From $9.99	A good choice for Homepage with active widgets and a few lightweight applications (e.g., Dozzle, AdGuard Home).
Advanced (Homepage + 5+ Docker applications, API integrations)	4	4	80	1000+	From $19.99	Suitable for those who want to host many services on one VPS (e.g., NocoDB, code-server, Plex) and use Homepage as a full-fledged control center.
High-Load (Homepage + resource-intensive applications, databases)	6+	8+	160+	1000+	From $39.99	For professionals and teams managing large projects or requiring high performance for all self-hosted services.

Recommendations for choosing a VPS from Valebyte

1. Start small: If you are new to Homepage installation or unsure of your needs, start with a minimal or standard plan. You can always easily scale VPS resources as your requirements grow. Valebyte offers flexible plans that allow you to increase CPU, RAM, and disk space without reinstalling the system.
2. NVMe/SSD drives: Always prioritize VPS with NVMe or SSD drives. They provide significantly higher read/write speeds compared to traditional HDDs, which is critically important for the performance of the operating system, Docker containers, and fast Homepage responsiveness.
3. Server location: Choose a data center that is geographically closer to you or your primary audience. This minimizes latency and provides faster access to your Homepage.
4. Bandwidth: Ensure your plan includes sufficient bandwidth. While Homepage itself doesn't require much traffic, other applications you might host on the same VPS could be more demanding.
5. Support: Valebyte provides 24/7 technical support, which is especially important if you have questions about configuring or maintaining your VPS.

Conclusion

Homepage is a powerful and flexible tool for creating a personalized dashboard of your self-hosted services. Deployed on a VPS, it provides full control over your digital infrastructure, ensuring convenient access and monitoring. For most users, an optimal choice would be a VPS with 2 vCPU, 2-4 GB RAM, and 40-80 GB NVMe disk, which will ensure stable Homepage operation and sufficient headroom for hosting several additional Docker applications.