How To Install Uptime Kuma on Fedora 43

Monitoring server uptime and service availability is critical for maintaining reliable IT infrastructure. Uptime Kuma provides a powerful, self-hosted monitoring solution that rivals expensive commercial alternatives. This comprehensive guide walks through installing Uptime Kuma on Fedora 43, covering both Docker and manual installation methods, configuration options, and security best practices.

Whether you’re managing a single website or an entire network of services, Uptime Kuma delivers real-time monitoring with beautiful visualizations and multi-channel notifications. By the end of this tutorial, you’ll have a fully functional monitoring system running on your Fedora 43 server.

What is Uptime Kuma?

Overview and Key Features

Uptime Kuma is an open-source, self-hosted monitoring tool built with Node.js that provides comprehensive service monitoring capabilities. The application features a modern, reactive user interface with dark mode support, making it both functional and visually appealing for daily use.

The monitoring platform supports HTTP/HTTPS endpoints, TCP port checks, ping operations, DNS record validation, and database connections including MySQL and PostgreSQL. Advanced features include keyword detection on webpages, Docker container monitoring, and customizable status pages for public communication. With support for over 20 languages and more than 90 notification channels, Uptime Kuma adapts to diverse organizational needs.

System Requirements

Running Uptime Kuma efficiently requires modest hardware resources. The minimum configuration includes 1 vCPU, 1GB RAM, and 20GB storage space. For production environments or monitoring numerous endpoints, 2 vCPUs and 2GB RAM are recommended to ensure smooth performance.

Resource consumption scales with the number of monitoring probes configured. A server monitoring 50 endpoints will consume more resources than one tracking just 10 services. Fedora 43, Ubuntu, Debian, CentOS, and Windows 10 x64 all serve as compatible platforms for deployment.

Prerequisites for Installation on Fedora 43

System Requirements

Before beginning the installation process, ensure your Fedora 43 system meets the necessary requirements. Root or sudo access is essential for installing packages and configuring services. The server should have at least 1GB RAM and 1 CPU core available, though 2GB RAM and 2 cores provide better performance for production workloads.

Allocate a minimum of 5GB free disk space for the application, dependencies, and monitoring data storage. An active internet connection is required during installation to download packages and Docker images.

Required Software Packages

Uptime Kuma requires Node.js version 14, 16, 18, or 20.4 or later for proper operation. The npm package manager version 9 or higher handles dependency installation. Git version control enables cloning the repository for manual installations.

For production deployments, PM2 process manager provides automatic restarts, log rotation, and process monitoring capabilities. Docker offers an alternative installation method that simplifies deployment and updates.

Network Configuration

Uptime Kuma defaults to port 3001 for the web interface. Firewall rules must allow traffic on this port for remote access. Planning reverse proxy configurations with Nginx or Apache should be considered for production environments requiring SSL/TLS encryption.

Preparing Your Fedora 43 Environment

Updating the System

Start by updating your Fedora 43 system to ensure all packages are current. Open a terminal and execute:

sudo dnf update -y

This command refreshes package repositories and upgrades installed software to the latest stable versions. System updates patch security vulnerabilities and prevent compatibility issues during the installation process.

Installing Dependencies

Install the required dependencies using Fedora’s DNF package manager:

sudo dnf install nodejs npm git -y

This single command installs Node.js, npm, and Git simultaneously. The -y flag automatically confirms installation without prompting for user input.

Verify successful installation by checking each version:

node --version
npm --version
git --version

Each command should display version numbers confirming proper installation. Node.js should report version 14 or higher, while npm should show version 9 or greater.

Configuring Firewall Settings

Open port 3001 through the firewall to enable web interface access:

sudo firewall-cmd --add-port=3001/tcp --permanent
sudo firewall-cmd --reload

The --permanent flag ensures the rule persists across system reboots. The reload command applies changes immediately without disrupting existing connections.

For deployments using custom ports, replace 3001 with your preferred port number in both commands. Restrict access to specific IP addresses by using rich rules for enhanced security.

Installation Method 1: Docker Installation

Installing Docker on Fedora 43

Docker provides the simplest installation method with containerized deployment. Install Docker with the following command:

sudo dnf install docker -y

Start the Docker service immediately:

sudo systemctl start docker

Enable Docker to launch automatically at system boot:

sudo systemctl enable docker

Confirm successful installation by checking the Docker version:

sudo docker --version

The output should display the installed Docker version number. If errors occur, verify that your system architecture supports Docker and that no conflicting container runtimes are installed.

Pulling the Uptime Kuma Docker Image

Download the official Uptime Kuma Docker image from Docker Hub:

sudo docker pull louislam/uptime-kuma:1

The tag “1” represents the latest stable release and is recommended for production use. Alternative tags include “latest” for Debian-based images and “nightly” for development builds with experimental features. Alpine-based images are deprecated and should be avoided.

Running the Uptime Kuma Container

Launch the Uptime Kuma container with persistent data storage:

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

This command contains several critical parameters:

• -d runs the container in detached mode, allowing it to operate in the background
• --restart=unless-stopped automatically restarts the container after crashes or system reboots
• -p 3001:3001 maps container port 3001 to host port 3001 for web access
• -v uptime-kuma:/app/data creates a named volume for persistent data storage
• --name uptime-kuma assigns a recognizable name to the container

The volume mount ensures monitoring data, configurations, and user accounts survive container updates and recreations. Important: The storage system must support POSIX file locks to prevent SQLite database corruption.

Verifying Docker Installation

Check that the container is running properly:

sudo docker ps

This command lists all running containers. Look for “uptime-kuma” in the output.

View container logs to troubleshoot issues:

sudo docker logs uptime-kuma

Access the web interface by navigating to http://localhost:3001 or http://your_server_ip:3001 in a web browser. The Uptime Kuma welcome screen should appear, prompting for initial setup.

Installation Method 2: Manual Installation

Cloning the Uptime Kuma Repository

Navigate to the installation directory:

cd /opt

Clone the official GitHub repository:

sudo git clone https://github.com/louislam/uptime-kuma.git

Enter the newly created directory:

cd uptime-kuma

The /opt directory is conventional for third-party applications on Linux systems. Using sudo ensures proper permissions during the clone operation.

Installing Node.js Dependencies

Run the setup script to install dependencies and build the application:

npm run setup

This command executes multiple tasks including dependency installation, database initialization, and production build compilation. The process typically takes 3-5 minutes depending on system performance and internet speed.

Alternatively, install dependencies manually:

npm install
npm run build

These commands provide more granular control over the installation process. The build step compiles frontend assets and optimizes the application for production use.

Testing the Installation

Verify the installation works correctly by starting the server manually:

node server/server.js

Open a web browser and navigate to http://localhost:3001. The Uptime Kuma interface should load successfully. Press Ctrl+C to stop the test server once verified.

Installing PM2 Process Manager

Install PM2 globally to manage the Uptime Kuma process:

npm install pm2 -g
pm2 install pm2-logrotate

PM2 provides automatic process restarts, log management, and system monitoring capabilities. The pm2-logrotate module prevents log files from consuming excessive disk space.

Starting Uptime Kuma with PM2

Launch Uptime Kuma as a PM2-managed process:

pm2 start server/server.js --name uptime-kuma

Configure PM2 to start automatically at system boot:

pm2 save
pm2 startup

Execute the command output by pm2 startup to complete the boot configuration.

Useful PM2 commands for managing Uptime Kuma include:

• pm2 monit – Real-time process monitoring
• pm2 logs uptime-kuma – View application logs
• pm2 restart uptime-kuma – Restart the process
• pm2 stop uptime-kuma – Stop the process
• pm2 delete uptime-kuma – Remove from PM2 management

These commands provide comprehensive control over the Uptime Kuma process.

Creating a Systemd Service (Alternative to PM2)

Creating the Service File

For systems preferring systemd over PM2, create a service file:

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

Add the following configuration:

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

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

[Install]
WantedBy=multi-user.target

This configuration defines service behavior, startup dependencies, and restart policies. Adjust the User directive to run as a non-root user for enhanced security.

Enabling and Managing the Service

Reload the systemd daemon to recognize the new service:

sudo systemctl daemon-reload

Enable the service to start at boot:

sudo systemctl enable uptime-kuma

Start the service immediately:

sudo systemctl start uptime-kuma

Check service status:

sudo systemctl status uptime-kuma

The output should show “active (running)” in green text. Additional management commands include sudo systemctl stop uptime-kuma and sudo systemctl restart uptime-kuma.

Initial Configuration and Setup

Accessing the Web Interface

Open a web browser and navigate to http://your_server_ip:3001. Replace your_server_ip with your Fedora server’s IP address. Local installations can use http://localhost:3001.

Creating Your First Admin Account

The initial setup wizard prompts for administrator credentials. Choose a strong username and password combination. Password requirements typically include:

• Minimum 8 characters
• Mix of uppercase and lowercase letters
• At least one number
• Special characters recommended

Store credentials securely using a password manager. Admin access controls all monitoring configurations and user management.

Exploring the Dashboard

The Uptime Kuma dashboard features a clean, intuitive interface with several key sections.

The left sidebar contains navigation for monitors, status pages, settings, and notification configurations. The main panel displays monitor status with color-coded indicators showing uptime percentages. Green indicates healthy services, red signals downtime, and yellow shows degraded performance.

A dark mode toggle in the upper right corner switches between light and dark themes. The responsive design adapts to mobile devices for monitoring on the go.

Setting Up Your First Monitor

Adding HTTP/HTTPS Monitors

Click “Add New Monitor” to create your first monitoring check. Select “HTTP(s)” as the monitor type for website monitoring.

Configure these essential settings:

• Friendly Name: A descriptive label for the monitor
• URL: The complete web address to monitor (e.g., https://example.com)
• Heartbeat Interval: How frequently to check (minimum 20 seconds)
• Retries: Number of retry attempts before marking as down
• Timeout: Maximum wait time for responses (in seconds)

Advanced options include:

• Accepted Status Codes: Define valid HTTP response codes (default 200-299)
• Ignore TLS/SSL Error: Disable certificate validation for self-signed certificates
• Custom Headers: Add authentication tokens or user agents
• Keyword Detection: Monitor for specific text on pages

Click “Save” to activate the monitor. Uptime Kuma immediately begins checking the endpoint.

Configuring Other Monitor Types

Beyond HTTP monitoring, Uptime Kuma supports multiple protocol checks:

TCP Port Monitoring verifies network services by connecting to specific ports. Configure hostname and port number to monitor SSH (22), SMTP (25), or custom application ports.

Ping Monitors perform ICMP checks to verify basic connectivity. Useful for monitoring network devices like routers and switches.

DNS Monitoring validates DNS resolution and record accuracy. Specify the domain name and expected IP address or record type.

Database Monitors test MySQL, PostgreSQL, and other database connections. Provide connection strings with credentials to verify database availability.

Understanding Monitor Settings

The Heartbeat Interval determines check frequency. Shorter intervals detect outages faster but consume more resources. Balance responsiveness with system load.

Upside-Down Mode inverts success conditions, marking monitors as healthy when they return errors. Useful for monitoring failure endpoints or maintenance pages.

Custom user agents spoof browser identities for websites with user agent restrictions. Timeout values prevent hung connections from delaying subsequent checks.

Configuring Notification Methods

Email Notifications

Navigate to Settings > Notifications > Add New Notification. Select “Email (SMTP)” as the notification type.

Configure SMTP server details:

• Hostname: SMTP server address (e.g., smtp.gmail.com)
• Port: Usually 587 for TLS or 465 for SSL
• Security: Select TLS, SSL, or None
• Username: Email account username
• Password: Email account password
• From Email: Sender address
• To Email: Recipient address(es)

Click “Test” to verify configuration. Successful tests send a sample notification email. Apply the configuration to monitors by editing each monitor and selecting the notification.

Telegram, Discord, and Slack Integration

Telegram Integration requires creating a bot via @BotFather. Obtain the bot token and chat ID, then enter these values in the Telegram notification configuration.

Discord Webhooks enable channel notifications. Create a webhook in Discord server settings, copy the webhook URL, and paste it into Uptime Kuma’s Discord notification settings.

Slack Integration uses incoming webhooks. Generate a webhook URL from Slack’s app directory, then configure it in Uptime Kuma. Test notifications to verify proper routing.

Other Notification Channels

Uptime Kuma supports over 90 notification services including:

• PagerDuty for incident management
• OpsGenie for on-call alerting
• Pushover for mobile push notifications
• Gotify for self-hosted notifications
• Generic webhooks for custom integrations

Each service requires specific API keys or webhook URLs. Consult individual service documentation for obtaining credentials.

Creating Status Pages

Public Status Page Setup

Status pages provide transparent service status communication to users and customers. Click “Status Pages” in the sidebar, then “Add New Status Page.”

Configure the following settings:

• Title: Page headline (e.g., “System Status”)
• Description: Brief explanation of monitored services
• Theme: Choose light, dark, or auto-switching themes
• Show Tags: Display monitor categories
• Domain: Custom domain for branded status pages

Select monitors to display on the status page. Organize monitors into groups for clearer presentation.

Customizing Status Page Appearance

Customize branding by uploading a company logo and selecting color schemes. Add footer text for contact information or support links.

Maintenance announcements communicate scheduled downtime. Create announcements with start times, end times, and descriptions to keep users informed.

The public status page URL is shareable without authentication requirements. Embed it in websites or share via social media during incidents.

Advanced Configuration Options

Setting Up Reverse Proxy with Nginx

Production deployments benefit from reverse proxy configurations for SSL/TLS termination and domain-based routing. Install Nginx:

sudo dnf install nginx -y

Create a virtual host configuration:

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

Add this configuration:

server {
    listen 80;
    server_name status.yourdomain.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;
    }
}

The Upgrade and Connection headers enable WebSocket support for real-time updates. Test the configuration:

sudo nginx -t

Reload Nginx to apply changes:

sudo systemctl reload nginx

Implementing SSL/TLS Certificates

Secure your monitoring dashboard with Let’s Encrypt SSL certificates. Install Certbot:

sudo dnf install certbot python3-certbot-nginx -y

Obtain and install a certificate:

sudo certbot --nginx -d status.yourdomain.com

Certbot automatically configures Nginx with SSL and sets up automatic renewal. Verify certificate installation by visiting https://status.yourdomain.com.

Environment Variables and Custom Settings

Customize Uptime Kuma behavior using environment variables. Common variables include:

• PORT – Change default port (e.g., PORT=3002)
• DATA_DIR – Specify custom data directory
• NODE_ENV=production – Enable production optimizations

Set variables in systemd service files or PM2 ecosystem configurations for persistence.

Security Best Practices

Securing Your Installation

Implement these security measures to protect your monitoring infrastructure:

Use strong, unique passwords for admin accounts. Enable two-factor authentication if available through external authentication providers.

Run Uptime Kuma as a non-root user by creating a dedicated service account. Modify systemd service files or PM2 configurations to specify the user.

Keep software updated by regularly checking for Uptime Kuma releases, Node.js updates, and Fedora security patches.

Network Security Considerations

Restrict firewall access to specific IP ranges using firewalld rich rules:

sudo firewall-cmd --add-rich-rule='rule family="ipv4" source address="192.168.1.0/24" port protocol="tcp" port="3001" accept' --permanent
sudo firewall-cmd --reload

This limits access to the specified subnet. Adjust IP ranges to match your network requirements.

Consider VPN access for remote monitoring. Deploy Uptime Kuma on internal networks accessible only via VPN for maximum security.

Regular database backups prevent data loss. Set appropriate file permissions (600 or 640) on SQLite database files to restrict access.

Maintenance and Updates

Backing Up Uptime Kuma Data

Docker installations use volume backups:

sudo docker run --rm -v uptime-kuma:/data -v /backup:/backup alpine tar -czf /backup/uptime-kuma-$(date +%Y%m%d).tar.gz -C /data ./

This command creates timestamped backups in the /backup directory.

Manual installations require backing up the data directory:

sudo tar -czf /backup/uptime-kuma-data-$(date +%Y%m%d).tar.gz /opt/uptime-kuma/data

Schedule automated backups using cron jobs. Daily backups with weekly retention provide adequate protection.

Updating Uptime Kuma

Docker updates follow this process:

sudo docker pull louislam/uptime-kuma:1
sudo docker stop uptime-kuma
sudo docker rm uptime-kuma
sudo docker run -d --restart=unless-stopped -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:1

The named volume preserves data across container recreations.

Manual installations require pulling updates from Git:

cd /opt/uptime-kuma
git pull
npm install
npm run build
pm2 restart uptime-kuma

Always review changelogs before updating to understand new features and potential breaking changes.

Troubleshooting Common Issues

Port Conflicts and Connection Issues

Port 3001 conflicts occur when other services occupy the port. Identify conflicting processes:

sudo lsof -i :3001

Change Uptime Kuma’s port by modifying Docker run commands or environment variables. Update firewall rules to match new port assignments.

Connection failures may indicate firewall blocks. Verify firewall rules with sudo firewall-cmd --list-all. Check SELinux status if connections fail despite correct firewall configuration.

Database and Permission Problems

SQLite database corruption typically results from improper file locking. Ensure storage systems support POSIX file locks, particularly for network-mounted volumes.

Permission errors require adjusting file ownership:

sudo chown -R uptime-kuma:uptime-kuma /opt/uptime-kuma/data

Database migrations occasionally fail during updates. Backup data before updating and restore from backups if migration errors occur.

Performance Optimization

Reduce monitor check frequencies for resource-constrained systems. Increasing heartbeat intervals from 60 seconds to 120 seconds halves CPU usage.

Database maintenance improves performance over time. Uptime Kuma includes built-in cleanup tools for purging old monitoring data.

Monitor system resources with htop or pm2 monit. Upgrade server specifications if CPU consistently exceeds 80% or RAM reaches capacity.

Large deployments benefit from distributed monitoring architectures. Deploy multiple Uptime Kuma instances across geographic regions for redundancy.

Congratulations! You have successfully installed Uptime Kuma. Thanks for using this tutorial to install the latest version of the Uptime Kuma monitoring tool on Fedora 43 Linux. For additional help or useful information, we recommend you check the official Uptime Kuma website.