138 lines
4.6 KiB
Markdown
138 lines
4.6 KiB
Markdown
# Uptime Kuma Terminal Dashboard
|
|
|
|
|
|
|
|
A terminal-based monitoring dashboard for Uptime Kuma that displays service status, uptime percentages, and historical performance data directly in your terminal. Built with Rust for performance and reliability.
|
|
|
|
## Overview
|
|
|
|
This personal project started as a way to monitor my home lab services without needing a web browser. It connects to your Uptime Kuma instance API and presents a clean, color-coded view of your services' status with real-time updates. The dashboard works great on servers, remote terminals, or anywhere you prefer a lightweight monitoring solution.
|
|
|
|
Perfect for DevOps engineers, system administrators, or anyone who prefers terminal workflows over web interfaces for quick status checks.
|
|
|
|
## Features
|
|
|
|
- Real-time service monitoring with automatic refresh
|
|
- Color-coded status indicators (green for up, red for down)
|
|
- Historical uptime visualization with compact status history lines
|
|
- Responsive terminal UI that adapts to window size
|
|
- Internationalization support (English and Portuguese)
|
|
- Configurable refresh intervals
|
|
- Minimal resource usage (runs efficiently even on low-power devices)
|
|
- Keyboard navigation support (arrow keys, home/end)
|
|
- Mobile-friendly design for SSH connections
|
|
|
|
## Tech Stack
|
|
|
|
This project demonstrates proficiency with several modern technologies:
|
|
|
|
- **Rust** (core language with async capabilities)
|
|
- **ratatui** (terminal UI framework)
|
|
- **reqwest** (HTTP client for API communication)
|
|
- **serde** (JSON serialization/deserialization)
|
|
- **clap** (command-line argument parsing)
|
|
- **fluent-templates** (internationalization framework)
|
|
- REST API integration patterns
|
|
- Error handling and logging best practices
|
|
- Cross-platform terminal development
|
|
|
|
You can find the latest releases in the [Releases section](https://git.marcodearaujo.com/marcodearaujo/uptime-kuma-dashboard/releases).
|
|
|
|
## Installation
|
|
|
|
### Option 1: Download built Binary (Recommended)
|
|
|
|
1. Go to the [Releases page](https://git.marcodearaujo.com/marcodearaujo/uptime-kuma-dashboard/releases)
|
|
2. Download the binary for your operating system:
|
|
- **Linux (x86_64)**: `uptime-kuma-dashboard-x86_64-unknown-linux-gnu`
|
|
- **Linux (ARM64)**: `uptime-kuma-dashboard-aarch64-unknown-linux-gnu` (Raspberry Pi, ARM servers)
|
|
- **Windows**: `uptime-kuma-dashboard-x86_64-pc-windows-gnu.exe`
|
|
3. Verify the checksum (recommended for security):
|
|
```bash
|
|
sha256sum -c SHA256SUMS.txt
|
|
```
|
|
4. Make it executable (Linux/ARM only):
|
|
```bash
|
|
chmod +x uptime-kuma-dashboard-*
|
|
```
|
|
5. Run with your parameters:
|
|
```bash
|
|
./uptime-kuma-dashboard-* --base-url="http://your-kuma:3001/" --slug="your-slug"
|
|
```
|
|
|
|
### Option 2: Build From Source
|
|
|
|
### Prerequisites
|
|
|
|
- Rust 1.74+ toolchain (install via [rustup](https://rustup.rs/))
|
|
- Uptime Kuma instance with API access
|
|
|
|
### Build from Source
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://git.marcodearaujo.com/marcodearaujo/uptime-kuma-dashboard.git
|
|
cd uptime-kuma-dashboard
|
|
|
|
# Build the project
|
|
cargo build --release
|
|
|
|
# Run the dashboard (replace with your Uptime Kuma URL and status page slug)
|
|
./target/release/uptime-kuma-dashboard \
|
|
--base-url="http://your-uptime-kuma-instance:3001/" \
|
|
--slug="your-status-page-slug"
|
|
```
|
|
|
|
## Usage
|
|
|
|
The dashboard requires two parameters:
|
|
|
|
- `--base-url`: Your Uptime Kuma instance URL (including port)
|
|
- `--slug`: Your status page slug identifier
|
|
|
|
Example:
|
|
|
|
```bash
|
|
./uptime-kuma-dashboard --base-url="http://192.168.1.100:3001/" --slug="home-services"
|
|
```
|
|
|
|
**Controls during runtime:**
|
|
|
|
- `q` or `ESC`: Exit the dashboard
|
|
- `↑`/`↓` or `k`/`j`: Navigate through monitors
|
|
- `Home`/`End`: Jump to top/bottom of the list
|
|
|
|
## Configuration
|
|
|
|
You can set environment variables to avoid typing parameters each time:
|
|
|
|
```bash
|
|
export UPTIME_KUMA_URL="http://your-uptime-kuma-instance:3001/"
|
|
export STATUS_PAGE_SLUG="your-status-page-slug"
|
|
```
|
|
|
|
## Development Notes
|
|
|
|
This project follows Rust best practices including:
|
|
|
|
- Comprehensive error handling with `anyhow`
|
|
- Internationalization-ready architecture
|
|
- Modular code organization
|
|
- Performance optimization for terminal rendering
|
|
- Cross-platform compatibility testing
|
|
|
|
The architecture separates concerns into:
|
|
|
|
- API client layer
|
|
- Data processing core
|
|
- UI rendering components
|
|
- Configuration management
|
|
- Internationalization system
|
|
|
|
## License
|
|
|
|
This project is available under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
---
|
|
|
|
_Developed as a personal learning project to improve Rust skills and create a useful tool for my home lab monitoring. Feedback welcome!_
|