docudjeex/content/en/3.serveex/4.monitoring/1.uptime-kuma.md

title, description

title	description
Uptime-Kuma	Install Uptime-Kuma to monitor your self-hosted services uptime, set up alerts, and optionally protect the dashboard with Tinyauth or Authentik

:ellipsis{left=0px width=40rem top=10rem blur=140px zIndex=60}

Installation

Folder structure

root
└── docker
    └── uptime-kuma
        ├── date
        └── compose.yaml

::steps{level="3"}

Deploy the stack

Open Dockge, click on compose, name the stack uptime-kuma, then copy and paste the following:

---
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2-slim
    container_name: uptime-kuma
    volumes:

      - /docker/uptime-kuma/uptime-kuma-data:/app/data
    ports:

      - 3200:3001 # <Host Port>:<Container Port>
    restart: always

::tip{icon=""} ✨ Tip: Add the Watchtower label to each container to automate updates

```yaml [compose.yaml]
services:
  uptime-kuma:
    #...
    labels:

      - com.centurylinklabs.watchtower.enable=true
```

::

Access the web UI

You can now access the tool via http://yourserverip:3200.

::caution

If it fails: check your firewall rules. ::

Done !

::

Expose with Swag

::note{icon=""} 📋 Before you begin:

We assume you have the subdomain stats.mydomain.com with a CNAME pointing to mydomain.com in your DNS zone. And of course, unless you're using Cloudflare Zero Trust, port 443 of your router should point to port 443 of your server via NAT rules. ::

::warning

Uptime-Kuma does not use multi-factor authentication. Exposing Uptime-Kuma on the internet could compromise the machines it monitors. Only do this if you're using an MFA system like TinyAuth or Authentik. Otherwise, don’t expose it with SWAG; use a VPN like Wireguard instead. ::

::steps{level="3"}

Create the subdomain.conf file

In the Swag folders, create the stats.subdomain.conf file.

::tip{icon=""} ✨ Tip for those who dislike the terminal: you can use File Browser Quantum to browse and edit your files instead of using terminal commands. ::

sudo nano /docker/swag/config/nginx/proxy-confs/stats.subdomain.conf

Paste the following config:

## Version 2023/12/19

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name stats.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    #if ($lan-ip = yes) { set $geo-whitelist yes; }
    #if ($geo-whitelist = no) { return 404; }
    if ($geo-blacklist = no) { return 404; }

    # enable for ldap auth (requires ldap-location.conf in the location block)
    #include /config/nginx/ldap-server.conf;

    # enable for Authelia (requires authelia-location.conf in the location block)
    #include /config/nginx/authelia-server.conf;

    # enable for Authentik (requires authentik-location.conf in the location block)
    #include /config/nginx/authentik-server.conf;

    location / {
        # enable the next two lines for http auth
        #auth_basic "Restricted";
        #auth_basic_user_file /config/nginx/.htpasswd;

        # enable for ldap auth (requires ldap-server.conf in the server block)
        #include /config/nginx/ldap-location.conf;

        # enable for Authelia (requires authelia-server.conf in the server block)
        #include /config/nginx/authelia-location.conf;

        # enable for Authentik (requires authentik-server.conf in the server block)
        #include /config/nginx/authentik-location.conf;

        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app uptime-kuma;
        set $upstream_port 3001;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

    }
}

Press :kbd{value="Ctrl+O"}, then :kbd{value="Enter"} to save, and :kbd{value="Ctrl+X"} to exit.

Add Uptime-Kuma's network to SWAG

In Dockge, edit the SWAG compose and add the Uptime-Kuma network:

services:
  swag:
     container_name: # ...
      # ... 
     networks:                 # Link container to custom network 
      # ...           

      - uptime-kuma            # Name of the declared network

networks:                      # Define custom network
  # ...
  uptime-kuma:                 # Name of the declared network
    name: uptime-kuma_default  # Actual name of the external network
    external: true             # Specifies it's an external network

Restart the stack and wait until SWAG is fully operational.

::note

Here we assume that the network name of Uptime-Kuma is uptime-kuma_default. You can verify the connection by visiting SWAG's dashboard at http://yourserverip:81. ::

Done !

::

That's it! Uptime-Kuma is now exposed, and you can access it via https://stats.mydomain.com.

Protecting Uptime-Kuma with TinyAuth

TinyAuth can sit in front of Uptime-Kuma the same way as any other app, but here we also want the public status page (and the assets it needs to render) to stay reachable without logging in. This uses the same location regex technique as Leaving specific paths public, applied directly to stats.subdomain.conf.

::steps{level="3"}

Open the subdomain.conf file

sudo nano /docker/swag/config/nginx/proxy-confs/stats.subdomain.conf

Add the forward-auth check and public paths

Replace the file's content with the following. The location ~ ^/(...) block matches Uptime-Kuma's public status page and its assets, and is served directly, without ever reaching the auth_request check in location /:

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name stats.*;

    include /config/nginx/ssl.conf;

    location ~ ^/(status|assets|icon\.svg|api|upload|metrics) {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app uptime-kuma;
        set $upstream_port 3001;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }

    location /tinyauth {
        internal;
        proxy_pass http://tinyauth:3000/api/auth/nginx;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
        proxy_set_header X-Forwarded-Uri $request_uri;
    }

    location @tinyauth_login {
        return 302 https://tinyauth.mydomain.com/login?redirect_uri=$scheme://$http_host$request_uri;
    }

    location / {
        auth_request /tinyauth;
        error_page 401 = @tinyauth_login;

        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app uptime-kuma;
        set $upstream_port 3001;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }
}

::note

The location /tinyauth block runs inside SWAG's own container, so SWAG needs to be on TinyAuth's Docker network to reach it by name (tinyauth here). This should already be set up from exposing TinyAuth itself. If you run into an error, double-check SWAG's compose file still has that network attached. ::

Press :kbd{value="Ctrl+O"}, then :kbd{value="Enter"} to save, and :kbd{value="Ctrl+X"} to exit.

Done !

::

Redeploy the stack. Uptime-Kuma will then be publicly reachable via https://stats.mydomain.com, with the status page open and everything else behind TinyAuth.

::tip{icon=""} ✨ Tip: You can also protect this app with Authentik instead: open stats.subdomain.conf and uncomment the lines include /config/nginx/authentik-server.conf; and include /config/nginx/authentik-location.conf;. Don’t forget to create an application and provider in Authentik. Then edit the Uptime-Kuma provider, and under Advanced Protocol Settings > Authenticated Paths, enter:

```properties
^/$
^/status
^/assets/
^/assets
^/icon.svg
^/api/.*
^/upload/.*
^/metrics
```

::

::tip{icon=""} ✨ Tip: If you're using TinyAuth or Authentik and don't mind exposing the admin panel to your local network, you can disable Uptime-Kuma's native authentication in its settings and rely solely on whichever one is protecting it. ::