Uptime Kuma is a wonderful open-source and free web monitoring platform (https://github.com/louislam/uptime-kuma) though it's missing one crucial feature: an API. At least, until now.

API Container

While not an official API, it does connect through the built-in sockets API in-order to give us a well-defined web REST API. You can see the GitHub repo here:

GitHub - MedAziz11/Uptime-Kuma-Web-API: Uptime Kuma REST API

Uptime Kuma REST API. Contribute to MedAziz11/Uptime-Kuma-Web-API development by creating an account on GitHub.

GitHubMedAziz11

There are a few API repos for Uptime Kuma around, though I just happened to choose that one. The best news, though, is that it's super easy to launch by simply adding it to your docker file with a few light config options (and adding it to your reverse proxy) and like magic it'll work.

Quick Tips

Further down in this article, you can find my compose file, though I wanted to explain a few things first:

(1) I use docker networks to separate out access rights. Anything that needs access to the reverse proxy goes into the work_network network.

(2) I added the dns option to the kuma container to help work around the potential DNS rate limits that myself, a few others have experienced. Here is the official GitHub issue (and comment thread plus solution) to DNS caching in kuma:

Error getaddrinfo EAI_AGAIN xxx.com · Issue #1697 · louislam/uptime-kuma

⚠️ Please verify that this bug has NOT been raised before. I checked and didn’t find similar issue 🛡️ Security Policy I agree to have read this project Security Policy Description It is impossible…

GitHublouislam

(3) I don't use named volumes much. I prefer to hold all config files and important stuff in local folders.

(4) I use named spaces / named DNS rather than local IP addresses for all my containers, as IP addresses can change, while the names rarely do. Thus, it makes it easier to keep everything connected even if the IP changes.

(5) I do not publish ports. Everything goes through the internal network to the reverse proxy (via the named spaces / dns names in number 4)

Docker Compose file

Your updated docker-compose.yml file will look something like mine, which you can find below:

version: '3.9'
services:
  kuma:
      container_name: uptime-kuma
      image: louislam/uptime-kuma:latest
      restart: always
      dns:
        - 1.0.0.1
        - 1.1.1.1
      volumes:
        - ./data:/app/data
        - /var/run/docker.sock:/var/run/docker.sock
      networks:
        - work_network
        
  api:
      container_name: uptime-kuma-api
      image: medaziz11/uptimekuma_restapi
      volumes:
        - ./db:/db
      restart: always
      environment:
        - KUMA_SERVER=http://kuma:3001
        - KUMA_USERNAME=YOURKUMALOGINUSERNAMEHERE
        - KUMA_PASSWORD=YOURACTUALLOGINPASSWORDHERE
        - ADMIN_PASSWORD=SOMERANDOMGENERATEDNICEPASSWORDHERE
      depends_on:
        - kuma
      networks:
        - work_network

networks:
  work_network:
    external: true

Reverse Proxy Setup

You will have to connect a reserve proxy up to this new api container in-order to access it externally. For my Uptime Kuma domain, I have something such as: uptime.example.com and therefore I used uptime-api.example.com for my API domain. Though you're free to use whatever domain or subdomain you wish.

The API container runs on port 8000. Thus, point your reverse proxy to the container at port 8000, and you're set.

Admin Password

You do need to set an admin password. This is not your Kuma login. This is the password you'll pass to the API to authenticate your request.

I recommend using a password generator tool, or smashing your face against the keyboard, in-order to generate something unique.

Once you've generated your password, simply add it to the line:

ADMIN_PASSWORD=SOMERANDOMGENERATEDNICEPASSWORDHERE

So if your chosen admin password is abc123 (please please do not use this as an actual password), then your ADMIN_PASSWORD line would look like:

ADMIN_PASSWORD=abc123

Login Credentials Requirements

This particular API does require an Uptime Kuma username and password. Therefore, if you're running Kuma with authentication turned off, I believe you'll still need to create (and have) a user account for it to work.

You can use your login or create a user purely for the API to use. Once you have that, add your Uptime Kuma username and password to the API environment and replace the dummy info I have below with your own:

- KUMA_USERNAME=YOURKUMALOGINUSERNAMEHERE
- KUMA_PASSWORD=YOURACTUALLOGINPASSWORDHERE

If the username for your Uptime Kuma instance is johnsmith and your password is P4ssw0Rd then your environment variables would be:

- KUMA_USERNAME=johnsmith
- KUMA_PASSWORD=P4ssw0Rd