Admin: New server guide

2026-04-13T10:01:48Z

New server guide

New page

= Setting Up Uptime Monitoring =
This guide details how to set up a self-hosted uptime monitoring solution using Uptime Kuma, a popular and user-friendly alternative to services like Pingdom. We will cover installation, configuration, and basic usage, along with considerations for setting up public status pages.

== Introduction ==
Ensuring your servers and services are consistently available is crucial for any system administrator. Downtime can lead to lost revenue, damaged reputation, and frustrated users. While commercial services offer robust monitoring, self-hosting provides greater control, privacy, and cost-effectiveness. Uptime Kuma is an excellent open-source tool that allows you to monitor various services, receive notifications, and display their status on a public page.

== Prerequisites ==
Before you begin, ensure you have the following:

* A Linux server with root or sudo privileges. A VPS from providers like PowerVPS (https://powervps.net/?from=32) is a good option for hosting monitoring tools.
* Docker and Docker Compose installed on your server. If not, follow the official Docker installation guide for your distribution.
* Basic familiarity with the Linux command line.
* (Optional) A domain name or subdomain for accessing your Uptime Kuma instance and its status page.

== Installing Uptime Kuma with Docker Compose ==
Using Docker Compose simplifies the installation and management of Uptime Kuma.

=== Step 1: Create a Docker Compose File ===
Create a directory for your Uptime Kuma installation and navigate into it:
<pre>
mkdir uptime-kuma
cd uptime-kuma
</pre>

Create a file named <code>docker-compose.yml</code> with the following content:
<pre>
version: '3.8'

services:
uptime-kuma:
image: louislam/uptime-kuma:1
container_name: uptime-kuma
restart: unless-stopped
ports:
- "3001:3001"
volumes:
- ./data:/app/data
- /etc/localtime:/etc/localtime:ro
environment:
- NODE_ENV=production
</pre>

* <code>image: louislam/uptime-kuma:1</code>: Specifies the Uptime Kuma Docker image.
* <code>container_name: uptime-kuma</code>: Assigns a friendly name to the container.
* <code>restart: unless-stopped</code>: Ensures the container restarts automatically if it crashes or the server reboots.
* <code>ports: - "3001:3001"</code>: Maps port 3001 on your host machine to port 3001 inside the container, which is Uptime Kuma's default port.
* <code>volumes: - ./data:/app/data</code>: This is crucial for data persistence. It maps a local directory named <code>data</code> within your <code>uptime-kuma</code> folder to the container's data directory, ensuring your monitoring configurations are saved even if the container is removed and recreated.
* <code>volumes: - /etc/localtime:/etc/localtime:ro</code>: Syncs the container's time with your host system's time.
* <code>environment: - NODE_ENV=production</code>: Sets the environment to production for optimal performance.

=== Step 2: Start Uptime Kuma ===
Run the following command in the same directory as your <code>docker-compose.yml</code> file:
<pre>
docker-compose up -d
</pre>
The <code>-d</code> flag runs the container in detached mode, meaning it will run in the background.

=== Step 3: Access Uptime Kuma ===
Open your web browser and navigate to <code>http://your_server_ip:3001</code>. You should see the Uptime Kuma setup page.

=== Step 4: Initial Setup ===
On the first visit, you will be prompted to create an administrator account. Enter a strong password and click "Save". You will then be redirected to the Uptime Kuma dashboard.

== Adding Monitors ==
The Uptime Kuma dashboard is where you'll add and manage your monitors.

=== Step 1: Click "Add New Monitor" ===
On the dashboard, click the prominent "Add New Monitor" button.

=== Step 2: Configure Monitor Type ===
Uptime Kuma supports various monitor types:

* **HTTP(s):** Checks if a web server is responding with a 2xx status code.
* **TCP:** Checks if a specific port is open and listening.
* **Ping:** Sends ICMP echo requests to an IP address or hostname.
* **Keyword:** Checks if a specific keyword exists on a web page.
* **Docker:** Monitors the status of Docker containers.
* ** and many more...**

For example, to monitor a website:
* Select "HTTP(s)".
* Enter the URL (e.g., <code>https://yourwebsite.com</code>).
* Give it a name (e.g., "My Website").
* Set the interval (e.g., every 1 minute).
* Configure advanced settings like expected status code (e.g., 200) or response time thresholds if needed.

For example, to monitor a database on a specific port:
* Select "TCP".
* Enter the hostname or IP address (e.g., <code>db.yourdomain.com</code> or <code>192.168.1.10</code>).
* Enter the port number (e.g., <code>5432</code> for PostgreSQL, <code>3306</code> for MySQL).
* Give it a name (e.g., "Database Server").
* Set the interval.

=== Step 3: Save the Monitor ===
Click "Save" to add the monitor. Uptime Kuma will immediately start checking its status.

== Setting Up Notifications ==
Receiving alerts when a service goes down is essential. Uptime Kuma integrates with numerous notification services.

=== Step 1: Navigate to "Settings" ===
Click on the "Settings" icon (gear) in the top-right corner of the dashboard.

=== Step 2: Go to "Notification Services" ===
Select "Notification Services" from the left-hand menu.

=== Step 3: Add a Notification Service ===
Click "Add Notification Service". Choose your preferred service from the list (e.g., Telegram, Discord, Slack, Email, Webhook).

=== Step 4: Configure the Service ===
Follow the on-screen instructions to configure your chosen service. This typically involves providing API keys, tokens, or webhook URLs. For example, for Telegram, you would need your Bot Token and Chat ID.

=== Step 5: Assign Monitors to Notifications ===
After setting up a notification service, go back to your monitor's configuration (edit the monitor and scroll down to the "Notifications" section). Select the notification service you just added to receive alerts for that specific monitor.

== Public Status Page ==
Uptime Kuma can generate a public-facing status page to inform your users about the availability of your services.

=== Step 1: Enable Status Page ===
Go to "Settings" > "Status Page". Toggle the "Enable Status Page" option.

=== Step 2: Configure Status Page Appearance ===
You can customize the title, logo, and theme of your status page.

=== Step 3: Add Monitors to Status Page ===
On the "Status Page" settings, you can select which monitors you want to display on the public page.

=== Step 4: Access Your Status Page ===
Your status page will be available at <code>http://your_server_ip:3001/status</code> by default. If you have configured a custom domain with a reverse proxy (e.g., Nginx or Caddy), you can access it via that domain.

== Advanced Configurations ==
=== Reverse Proxy with Nginx ===
To access Uptime Kuma via a custom domain (e.g., <code>status.yourdomain.com</code>) and secure it with SSL, you can set up a reverse proxy with Nginx.

First, ensure you have Nginx installed and running. Then, create an Nginx configuration file (e.g., <code>/etc/nginx/sites-available/uptime-kuma</code>):
<pre>
server {
listen 80;
server_name status.yourdomain.com;

location / {
proxy_pass http://127.0.0.1:3001;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
</pre>
Enable the site and restart Nginx:
<pre>
sudo ln -s /etc/nginx/sites-available/uptime-kuma /etc/nginx/sites-enabled/
sudo systemctl restart nginx
</pre>
You can then use Certbot to obtain an SSL certificate for <code>status.yourdomain.com</code>.

=== High Availability and Redundancy ===
For critical monitoring, consider running multiple Uptime Kuma instances on different servers or even in different geographic locations. For example, you could host a primary instance on a VPS from PowerVPS (https://powervps.net/?from=32) and a secondary instance on a cloud GPU provider like Immers Cloud GPU (https://en.immers.cloud/signup/r/20241007-8310688-334/) for failover.

== Troubleshooting ==
* **Uptime Kuma not starting:** Check Docker logs using <code>docker logs uptime-kuma</code>. Ensure port 3001 is not already in use on your host.
* **Monitors not reporting status:**
* Verify the monitor's configuration (URL, IP, port).
* Ensure the server running Uptime Kuma can reach the target service (check firewalls).
* For HTTP monitors, check if the expected status code is correct.
* **Notifications not sending:**
* Double-check your notification service credentials and configuration.
* Test the notification service directly if possible.
* Check Uptime Kuma's logs for any errors related to notifications.
* **Status page not accessible:**
* Ensure the status page is enabled in Uptime Kuma settings.
* If using a reverse proxy, check Nginx/Caddy logs and configuration.
* Verify firewall rules allow access to the Uptime Kuma port or your reverse proxy's port.

== Related Articles ==
* [[Introduction to Docker]]
* [[Nginx Reverse Proxy Setup]]
* [[Server Security Best Practices]]

[[Category:Monitoring]]
[[Category:Self-Hosted Applications]]
[[Category:Docker]]

{{Exchange Box}}

Setting Up Uptime Monitoring - Revision history

Admin: New server guide