Uptime Kuma with Subfolder Path

This repository provides a ready-to-use Docker Compose setup to run Uptime Kuma behind an Nginx reverse proxy with a subfolder path (/kuma).

Purpose

Deploying Uptime Kuma under a subfolder (like /kuma) has been a common challenge as discussed in Uptime Kuma issue #147. This project explain how it can be achieved using Docker Compose and Nginx.:

• Configuring Nginx as a reverse proxy to serve Uptime Kuma under a subfolder
• Providing a custom entrypoint script that modifies the necessary paths in the Uptime Kuma frontend
• Setting up proper environment variables to make everything work together

Adding support in the original Uptime Kuma will be a great improvement, but until then, this setup provides a workaround.

Quick Start

Prerequisites

• Docker and Docker Compose installed on your system
• Git (to clone this repository)

Setup Instructions

1. Clone this repository:

   git clone https://github.com/arulrajnet/uptime-kuma-subfolder-compose.git
   cd uptime-kuma-subfolder-compose

2. Make the entrypoint script executable:

   chmod +x entrypoint.sh

3. Start the services using Docker Compose:

   docker compose up -d

4. Access Uptime Kuma at:

   http://localhost:8080/kuma
   

How It Works

Docker Compose Configuration

The docker-compose.yml file sets up:

1. An Nginx service acting as a reverse proxy
2. Uptime Kuma service configured to run under the /kuma path
3. Persistent volume for Uptime Kuma data

Key configurations in the Uptime Kuma service:

• The SERVER_CONTEXTPATH: "/kuma" environment variable tells Uptime Kuma to use the subfolder
• A custom entrypoint script modifies the frontend resources to work with the subfolder path

Nginx Configuration

The kuma-nginx.conf file configures Nginx to:

1. Listen on port 8080
2. Proxy requests from /kuma to the Uptime Kuma service
3. Strip the /kuma prefix when forwarding requests
4. Add the /kuma prefix back to response headers (like Location)

# Key part of the configuration
location /kuma {
    # Strip /kuma prefix
    rewrite ^/kuma/?(.*)$ /$1 break;

    # Proxy to upstream service
    proxy_pass http://kuma_service;
}

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Arul