A Complete Guide to Monitoring With Uptime Kuma | Better Stack Community (2024)

Managing the availability of your services, applications, and databases can be daunting, but Uptime Kuma makes it effortless. This free, open-source, self-hosted tool informs you about your infrastructure's health with real-time monitoring and timely alerts, enabling proactive responses.

With support for over 78 notification services—including email, Telegram, and Slack—Uptime Kuma ensures you stay connected. It also lets you create customizable status pages to keep your team and users updated on service health.

In this guide, you'll set up Uptime Kuma by configuring monitors and notifications, as well as creating status pages to track and share your infrastructure's status easily.

Prerequisites

To get started, make sure you have:

• A basic web server with an active endpoint. This guide uses Python forsimplicity, but you can use any server setup you choose.
• Optionally, install thelatest version of Docker, whichsimplifies running Uptime Kuma. You can also set it up without Docker, thoughit requires more effort.

Getting started with Uptime Kuma

In this section, you’ll install Uptime Kuma on your system using Docker and setup your admin account.

To get started, run the following command in your terminal:

docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:1

Here’s a breakdown of the command:

• docker run: initiates a new container using the Uptime Kuma image.
• -d: runs the container in the background (detached mode).
• --restart=always ensures the container restarts automatically if it crashesor when Docker is restarted.
• -p 3001:3001: maps port 3001 of your host to port 3001 inside the container,making Uptime Kuma accessible via this port.
• -v uptime-kuma:/app/data: mounts the uptime-kuma volume to the /app/datadirectory in the container, ensuring data persistence.
• --name uptime-kuma: assigns the name uptime-kuma to the container foreasier reference.
• louislam/uptime-kuma:1: specifies the version 1 of the Uptime Kuma image touse.

Docker will download the Uptime Kuma image if it’s not already availablelocally:

Unable to find image 'louislam/uptime-kuma:1' locally1: Pulling from louislam/uptime-kuma...Downloaded newer image for louislam/uptime-kuma:1

Once the download completes, Uptime Kuma will be running athttp://localhost:3001.

You’ll be prompted to create an admin account. Enter your preferred details andclick Create:

After creating the account, you’ll be redirected to the dashboard:

The dashboard displays the status of monitored services and offers insights intouptime, downtime, and maintenance.

With Uptime Kuma now running, continue to the next section to set up your firstmonitor.

Creating a monitor with Uptime Kuma

In this section, you'll set up a simple server to monitor its status using Uptime Kuma.

Start by creating a basic HTTP server using Python (or any language you're comfortable with). Open your terminal and run:

python -m http.server 8000

This command launches a simple HTTP server on port 8000. This server will act as the target for your Uptime Kuma monitor.

Next, click the Add New Monitor button in Uptime Kuma:

You will be redirected to the /add page, where you can enter the monitordetails. Once you’ve entered the necessary values, click Save:

For this example, you’ve chosen "HTTP(s)" as the monitor type to track a webservice. The http://host.docker.internal:8000/ allows the Docker containerto connect to the service running on your host machine. The "Heartbeat Interval"is automatically set to 60 seconds, meaning Uptime Kuma will check the server’savailability every minute. After saving, you’ll be redirected to the monitorstatus page:

Here, you'll see that the Simple Server monitor is up with 100% uptime.

Now, let's simulate the server going down. Return to the terminal and pressCTRL + C to stop the server.

Once the server is stopped, Uptime Kuma will detect it and show that the monitoris down:

To bring the server back up, rerun the following command:

python -m http.server 8000

With your monitor set up, you can proceed to the next section to configurenotifications.

Setting up notifications

In this section, you'll configure email notifications in Uptime Kuma to alertyou when something goes wrong. We'll use Gmail to send these alerts, so let'sstart by setting that up.

First, configure an app password for your Gmail account. To do this, visitGoogle My Account → Security andenable 2-Step Verification.

Next, go to the App passwordssection at the bottom of the page and click the marked arrow:

Create a new app password. You can name it anything you like—here, we’ll use"UptimeKumaAlert". Enter the name in the text field and click Create.

Once the password is generated, copy it and store it in a safe place, as youwon't be able to view it again.

Now, return to the Uptime Kuma tab and click Edit to configurenotifications:

You will be taken back to the monitor configuration page. Click SetupNotification.

On the notification setup page, enter your email, SMTP details, and the apppassword:

Here, you set the notification type to "Email (SMTP)", using smtp.gmail.com asthe SMTP hostname and port 587. Then, you enter your Gmail credentials (withthe app password as the password) and fill both the "From Email" and "To Email"fields with your Gmail address.

Next, click Test. You should receive an email indicating that Uptime Kumacan send notifications:

If everything works, click Save to confirm the notification setup.

After saving, enable notifications for the monitor:

Now, click on the monitor to view its current status:

You should now see the status of the monitor:

Stop the server by returning to the terminal andpressing CTRL + C to test the notifications. After a short delay, check your Gmail inbox, and you’llreceive an email indicating that the service is down:

Once you restart the server, you will receive another email confirming that theservice is back up:

With email notifications successfully configured in Uptime Kuma, you'll proceed to create a status page in the next section.

Creating a status page

Having set up notifications to receive alerts when services change status, it's time to create a status page. This page will be visible to users, informing them which services are operational.

To start, click the Status Page button in the navigation bar:

Next, click on New Status Page:

You’ll then be redirected to a page where you can enter the status page name andslug:

In this example, you name the status page and set the slug to demo. Afterentering these details, click Next.

On the following page, you can add more information, such as a description andfooter text. Once you've done that, click Add a Monitor to select themonitor the status page will track:

After choosing the monitor, you’ll see that it is being tracked. Click Saveto save your changes:

Once saved, the status page will be live:

Since you’re logged in, you’ll see the Edit Status Page button, but if youview the page in incognito mode, you’ll see how it looks to users:

To test if the status page updates correctly when the monitor goes down, stopthe server. After a few minutes, the status page will reflect the change,showing the service is down:

With that, you’ve successfully created and tested your status page!

Why you shouldn't use Uptime Kuma

While Uptime Kuma is a capable self-hosted monitoring tool, it may not suit all environments due to key limitations. A significant issue is its inability to support multiple users, leading to the absence of role-based access control (RBAC). Without multiple user accounts or RBAC, anyone with dashboard access can modify or delete critical settings, posing security risks for larger teams.

Another limitation is the absence of API support for tasks like adding, updating, or removing monitors. Although an API is currently in development, this gap hinders the ability to automate workflows effectively, which can be a significant drawback if you're relying on automation for efficiency.

Self-hosting Uptime Kuma also brings a maintenance burden. It requires regular server upkeep, applying updates, and ensuring security patches—all of which can be resource-intensive. This ongoing maintenance demands time and technical expertise that you might prefer to allocate elsewhere.

As your infrastructure grows, Uptime Kuma’s single-instance setup can encounter performance bottlenecks. This limitation makes it less suitable for large-scale environments that require distributed monitoring across multiple instances to handle increased load and ensure reliability.

Moreover, Uptime Kuma lacks built-in redundancy or failover features like data replication or automatic failover. If the instance goes down, so does your entire monitoring system, creating a risk of service blind spots.

Lastly, the tool's health check functionality is limited due to the absence of an API for configuring or customizing health checks programmatically. While the Docker setup includes a basic health check, its fixed configuration may not suit all environments or use cases. This limitation restricts flexibility if you require more advanced or tailored health monitoring solutions.

Monitoring with Better Stack

Better Stack is an excellent choice if you're looking for an alternative that simplifies monitoring and avoids self-hosting challenges. It offers scalability by eliminating the need to manage infrastructure, apply updates, or handle maintenance tasks, allowing you to expand your monitoring efforts without additional overhead.

Better Stack performs multi-location checks every 30 seconds from sites worldwide, ensuring more accurate incident detection and reducing the chance of false alarms—something not possible with a self-hosted Uptime Kuma setup.

It also provides:

• Built-in incident management features.
• Unlimited voice calls and SMS alerts.
• On-call scheduling.
• Incident escalation.

Moreover, Better Stack offers comprehensive API support for monitoring, incident management, on-call scheduling, and integrations. This enables automation and scaling as your organization grows, ensuring efficiency and adaptability.

Lastly, its user management system includes features like team creation, single sign-on (SSO), audit logs, and team-wide maintenance controls. These tools ensure that team members have appropriate permissions and visibility, enhancing security and collaboration within your organization.

Starting with Better Stack is easy. Simply create a free account, and you can swiftly deploy your monitor and set up notifications.

For instance, once you've set up a monitor, you'll see its status as "UP," indicating it's ready to go.

If your server goes down, Better Stack will detect the issue and update thestatus to "DOWN," triggering an immediate alert:

You’ll then receive a notification, such as this email alert:

Additionally, you can create a custom status page with Better Stack, where youcan set up a company name and subdomain for your status page

Once live, your status page will show your service's operational status:

With Better Stack, you can easily create monitors and status pages whileavoiding the complexities of self-hosting.

Final thoughts

This article explored how to get started with Uptime Kuma by creating a monitor,setting up notifications, and building a status page. With this, you should nowhave a solid foundation for monitoring various services in your applicationusing Uptime Kuma. Check out ourmonitoring guides to continue learning more about monitoring.

Thanks for reading, and happy monitoring!