How To Install Uptime Kuma on Fedora

Are you tired of wondering whether your websites and services are actually running? If you’re managing servers or web applications, you know that downtime can be costly and frustrating. That’s where Uptime Kuma comes to the rescue! This powerful, self-hosted monitoring tool will keep a watchful eye on your services 24/7, alerting you the moment something goes wrong.

In this comprehensive guide, I’ll walk you through three different methods to install Uptime Kuma on Fedora Linux. Whether you’re a Docker enthusiast, prefer traditional installations, or want to use npm, I’ve got you covered. By the end of this article, you’ll have a fully functional monitoring system up and running.

Table of Contents

What is Uptime Kuma?

Uptime Kuma is a modern, open-source uptime monitoring tool that’s gained massive popularity in the self-hosting community. Think of it as your digital watchdog – it continuously checks your websites, APIs, databases, and other services to ensure they’re responding correctly. When something goes wrong, it immediately sends you alerts through various channels like email, Discord, Slack, or dozens of other notification services.

Key Features of Uptime Kuma

What makes Uptime Kuma special? Let me break down its standout features:

Beautiful, intuitive web interface that’s easy to navigate
Multiple monitoring types including HTTP/HTTPS, TCP, ping, DNS, and more
Extensive notification support with over 90 notification services
Status pages for public or private use
Multi-language support in over 20 languages
Mobile-responsive design for monitoring on the go
Free and open-source with active community development

Why Choose Uptime Kuma for Server Monitoring?

You might wonder why you should choose Uptime Kuma over commercial solutions like Pingdom or UptimeRobot. Here’s the thing – while those services are great, they come with monthly fees and limitations. Uptime Kuma gives you complete control over your monitoring data, unlimited monitors, and zero recurring costs. Plus, since it’s self-hosted, your monitoring data stays private and secure on your own servers.

Prerequisites for Installing Uptime Kuma on Fedora

Before we dive into the installation process, let’s make sure your Fedora system is ready. Don’t worry – the requirements are pretty straightforward!

System Requirements

Uptime Kuma is surprisingly lightweight, but here’s what you’ll need:

Fedora Linux (any recent version works great)
At least 512MB RAM (1GB recommended for multiple monitors)
1GB free disk space for the application and data
Network connectivity to reach the services you want to monitor
Root or sudo access for installation

Required Software Dependencies

Depending on your chosen installation method, you’ll need different components. Let’s install the essential ones first.

Node.js and npm Installation

Since Uptime Kuma is built with Node.js, you’ll need it installed on your system. Here’s how to get the latest version:

# Update your system first
sudo dnf update -y

# Install Node.js and npm from Fedora repositories
sudo dnf install nodejs npm -y

# Verify the installation
node --version
npm --version

If you prefer the latest Node.js version, you can use the official NodeSource repository:

# Add NodeSource repository
curl -sL https://rpm.nodesource.com/setup_lts.x | sudo bash -

# Install Node.js
sudo dnf install nodejs -y

Git Installation

You’ll also need Git to clone the Uptime Kuma repository:

# Install Git
sudo dnf install git -y

# Verify installation
git --version

Method 1: Installing Uptime Kuma via Docker (Recommended)

Docker installation is my top recommendation because it’s clean, isolated, and incredibly easy to manage. If you’re new to Docker, think of it as a way to package applications with all their dependencies in a portable container.

Installing Docker on Fedora

First, let’s get Docker running on your Fedora system:

# Install Docker
sudo dnf install docker -y

# Start and enable Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to the docker group (logout and login after this)
sudo usermod -aG docker $USER

Running Uptime Kuma Docker Container

Now comes the magic moment! With Docker installed, you can get Uptime Kuma running with a single command:

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

Let me explain what this command does:

-d runs the container in the background
--restart=always ensures it starts automatically after reboots
-p 3001:3001 maps port 3001 from the container to your host
-v uptime-kuma:/app/data creates a persistent volume for your data
--name uptime-kuma gives the container a friendly name

Configuring Docker Volume and Ports

Want to customize the setup? You can easily change the port or data location:

# Custom port and local directory
docker run -d \
  --restart=always \
  -p 8080:3001 \
  -v /home/username/uptime-kuma-data:/app/data \
  --name uptime-kuma \
  louislam/uptime-kuma:1

Important note: Never use network file systems like NFS for the data volume. Uptime Kuma uses SQLite, which requires proper file locking that NFS doesn’t support.

Method 2: Installing Uptime Kuma from Source

If you prefer more control over the installation or want to contribute to development, installing from source is the way to go. This method gives you access to the latest features and allows for easy customization.

Cloning the Uptime Kuma Repository

Let’s start by getting the source code:

# Navigate to your preferred installation directory
cd /opt

# Clone the repository
sudo git clone https://github.com/louislam/uptime-kuma.git

# Change ownership to your user
sudo chown -R $USER:$USER uptime-kuma

# Navigate to the directory
cd uptime-kuma

Installing Dependencies with npm

Now we’ll install all the required Node.js packages:

# Install dependencies
npm install

# This might take a few minutes depending on your internet connection

Building and Starting Uptime Kuma

With dependencies installed, let’s build and start the application:

# Build the application
npm run build

# Start Uptime Kuma
node server/server.js

You should see output indicating that Uptime Kuma is starting up. The application will be available at http://localhost:3001.

Method 3: Installing Uptime Kuma via npm Package Manager

The npm method is perfect if you want a global installation that’s easy to manage and update.

Global npm Installation

Installing globally makes Uptime Kuma available system-wide:

# Install Uptime Kuma globally
sudo npm install -g uptime-kuma

# Start Uptime Kuma
uptime-kuma

That’s it! The global installation creates a convenient command you can run from anywhere.

Running Uptime Kuma as a Service

For production use, you’ll want Uptime Kuma to run automatically. We’ll use pm2, a popular Node.js process manager:

# Install pm2 globally
sudo npm install -g pm2

# Start Uptime Kuma with pm2
pm2 start uptime-kuma --name "uptime-kuma"

# Save the pm2 configuration
pm2 save

# Setup pm2 to start on boot
pm2 startup

Initial Setup and Configuration

Regardless of which installation method you chose, the initial setup process is identical and straightforward.

Accessing the Web Interface

Open your web browser and navigate to:

http://localhost:3001 (if running locally)
http://your-server-ip:3001 (if running on a remote server)

You should see the Uptime Kuma welcome screen with a language selection dropdown.

Creating Your Administrator Account

The first time you access Uptime Kuma, you’ll need to create an administrator account:

Select your preferred language from the dropdown
Enter a username (this will be your login name)
Create a strong password (use a password manager!)
Confirm your password
Click “Create” to establish your account

Pro tip: Choose a strong, unique password since this account has full control over your monitoring setup.

Basic Configuration Settings

After creating your account, you’ll land on the main dashboard. Here are the first things you should configure:

Server timezone: Ensure logs and alerts show correct timestamps
Default notification settings: Set up your primary alert channels
Maintenance windows: Configure planned downtime periods
General settings: Customize the interface to your preferences

Setting Up Uptime Kuma as a System Service

For production environments, you’ll want Uptime Kuma to start automatically when your server boots. Let’s create a proper systemd service.

Creating a Dedicated User Account

Running services as dedicated users is a security best practice:

# Create a system user for Uptime Kuma
sudo useradd --system --no-create-home --shell /bin/false uptime-kuma

# If you installed from source, change ownership
sudo chown -R uptime-kuma:uptime-kuma /opt/uptime-kuma

Writing the Systemd Service File

Create a systemd service file to manage Uptime Kuma:

sudo nano /etc/systemd/system/uptime-kuma.service

Add this configuration:

[Unit]
Description=Uptime Kuma Service
After=network.target

[Service]
Type=simple
User=uptime-kuma
Group=uptime-kuma
WorkingDirectory=/opt/uptime-kuma
ExecStart=/usr/bin/node server/server.js
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Service Configuration Parameters

Let me explain the key parameters:

User/Group: Runs the service as the dedicated user
WorkingDirectory: Sets the correct directory context
ExecStart: Specifies the command to start Uptime Kuma
Restart=always: Automatically restarts if the service crashes
RestartSec=10: Waits 10 seconds before restarting

Enabling and Starting the Service

Now let’s activate our new service:

# Reload systemd to recognize the new service
sudo systemctl daemon-reload

# Enable the service to start on boot
sudo systemctl enable uptime-kuma

# Start the service now
sudo systemctl start uptime-kuma

# Check the service status
sudo systemctl status uptime-kuma

Configuring Firewall for Uptime Kuma

Fedora comes with firewalld enabled by default, so we need to open the necessary ports.

Opening Required Ports

Allow traffic on port 3001 (or your custom port):

# Open port 3001 permanently
sudo firewall-cmd --permanent --add-port=3001/tcp

# Reload firewall rules
sudo firewall-cmd --reload

# Verify the port is open
sudo firewall-cmd --list-ports

SELinux Considerations

If you encounter permission issues, SELinux might be blocking connections:

# Check SELinux status
sestatus

# If needed, allow HTTP connections on non-standard ports
sudo setsebool -P httpd_can_network_connect 1

Security Best Practices

Security should never be an afterthought, especially for monitoring tools that have access to sensitive information about your infrastructure.

Implementing SSL/TLS Encryption

While Uptime Kuma doesn’t have built-in SSL support, you should never run it without encryption in production. The solution? A reverse proxy!

Setting Up Reverse Proxy with Nginx

Here’s how to set up Nginx as a reverse proxy with SSL:

# Install Nginx
sudo dnf install nginx -y

# Install Certbot for Let's Encrypt
sudo dnf install certbot python3-certbot-nginx -y

Create an Nginx configuration:

sudo nano /etc/nginx/conf.d/uptime-kuma.conf

Add this configuration (replace your-domain.com with your actual domain):

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost: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;
        proxy_cache_bypass $http_upgrade;
    }
}

Get an SSL certificate:

# Obtain SSL certificate
sudo certbot --nginx -d your-domain.com

# Test automatic renewal
sudo certbot renew --dry-run

Monitoring Your First Service

Now for the fun part – let’s set up your first monitor!

Adding HTTP/HTTPS Monitors

Click the “Add New Monitor” button on your dashboard
Choose “HTTP(s)” as the monitor type
Enter a friendly name like “My Website”
Add the URL you want to monitor
Set the check interval (60 seconds is a good starting point)
Configure timeout settings (30 seconds is usually sufficient)
Add keywords to check for specific content (optional)
Click “Save” to create your monitor

Configuring Notification Channels

Monitors are useless if you don’t get notified when something goes wrong! Uptime Kuma supports over 90 notification services. Here are some popular options:

Email (SMTP): Classic and reliable
Discord: Great for team notifications
Slack: Perfect for business environments
Telegram: Fast and mobile-friendly
Webhook: For custom integrations

To set up notifications:

Go to Settings > Notifications
Click “Setup Notification”
Choose your preferred service
Enter the required credentials
Test the notification to ensure it works
Assign it to your monitors

Troubleshooting Common Issues

Even with the best instructions, sometimes things don’t go as planned. Here are solutions to the most common problems I’ve encountered.

Port Conflicts and Resolution

If port 3001 is already in use:

# Check what's using port 3001
sudo netstat -tlnp | grep 3001

# Or use ss command
sudo ss -tlnp | grep 3001

Solution: Either stop the conflicting service or use a different port for Uptime Kuma.

Permission and Ownership Problems

File permission issues are common, especially with source installations:

# Fix ownership for source installation
sudo chown -R uptime-kuma:uptime-kuma /opt/uptime-kuma

# Fix permissions
sudo chmod -R 755 /opt/uptime-kuma

For Docker installations, ensure your data directory has correct permissions:

# Fix Docker volume permissions
sudo chown -R 1000:1000 /path/to/your/data/directory

Maintaining and Updating Uptime Kuma

Keeping your monitoring system updated is crucial for security and new features.

For Docker installations:

# Pull the latest image
docker pull louislam/uptime-kuma:1

# Stop and remove the old container
docker stop uptime-kuma
docker rm uptime-kuma

# Start with the new image (same command as initial installation)
docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:1

For npm installations:

# Update globally
sudo npm update -g uptime-kuma

For source installations:

cd /opt/uptime-kuma
git pull origin master
npm install
npm run build
sudo systemctl restart uptime-kuma

Frequently Asked Questions

1. Can I monitor internal services that aren’t accessible from the internet?

Absolutely! Uptime Kuma can monitor any service accessible from the server where it’s installed. This includes internal APIs, databases, local services, and anything on your private network. Just use the internal IP addresses or hostnames.

2. How many monitors can I create with Uptime Kuma?

There’s no built-in limit to the number of monitors you can create. The practical limit depends on your server resources and check intervals. Most users run hundreds of monitors without issues on modest hardware.

3. What happens to my data if I switch from Docker to source installation?

Your monitoring data is stored in an SQLite database. You can migrate by copying the data directory from your Docker volume to your source installation directory. Just make sure to stop both instances before copying to avoid database corruption.

4. Can I customize the notification messages?

Yes! Uptime Kuma allows you to customize notification templates for different events. You can modify the message format, add custom variables, and even include additional context about the failed service.

5. Is it possible to create public status pages?

Definitely! Uptime Kuma includes a built-in status page feature where you can create public or password-protected status pages. These are perfect for showing your service availability to customers or team members without giving them access to your full monitoring dashboard.