Table of contents
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.
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:
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.
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
(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:
(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
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: - 18.104.22.168 - 22.214.171.124 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.
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:
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:
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