QuantomOS

QuantomOS - A modern, customizable dashboard system for managing your server and homelab infrastructure.

About QuantomOS

QuantomOS is an open-source user interface designed to be your internally hosted homepage for your homelab and server infrastructure. It provides a sleek, modern dashboard where you can monitor services, manage resources, and access your tools from a single unified interface.

Key Features

Customizable Grid Layout: Drag and drop widgets to create your perfect dashboard
Extensive Widget Library: System monitoring, service health checks, shortcuts, and custom widgets
Multi-Page Support: Organize your dashboard across multiple pages
Full Customization: Change backgrounds, themes, colors, and layout to match your style
Privacy-First: All data stored locally with AES-256-CBC encryption for sensitive information
Role-Based Access: Admin and user roles with granular permissions
PWA Support: Install as an app on desktop, mobile, or tablet
Dark Mode: Beautiful dark theme optimized for 24/7 monitoring
Responsive Design: Works flawlessly on any screen size
Backup & Restore: Easily backup and restore your configurations

Features

Dashboard & Widgets

Shortcuts Widget: Quick access to your favorite services and tools
System Monitor: Real-time CPU, RAM, network, and disk usage
Service Health Checks: Monitor the status of your services
Media Server Integration: Plex, Jellyfin, Emby support
Download Clients: qBittorrent, Transmission, SABnzbd, and more
Arr Stack: Sonarr, Radarr, Lidarr, Prowlarr, Readarr integration
Pi-hole & AdGuard: DNS and ad-blocking statistics
Weather Widget: Current weather and forecast
Clock & Calendar: Time, date, and timezone information
Group Widget: Container widget for organizing related items
Dual Widget: Combine two widgets into a single dashboard item
Custom Extensions: Create your own widgets with JSON-based extensions
- Unified widget selector with extensions integrated alongside built-in widgets
- Comprehensive extension development documentation
- Template system for dynamic content
- Shadow DOM isolation for style encapsulation

Customization

Drag & Drop Interface: Reorder and resize widgets effortlessly
Background Customization: Upload your own background images
Custom Search Providers: Add your preferred search engines
Theme Customization: Adjust colors, fonts, and spacing
Custom Page Names: Organize widgets across multiple named pages
Flexible Layouts: Desktop and mobile layouts managed separately

Privacy & Security

Complete Data Control: All data stored on your own device
Local Encryption: Sensitive data encrypted with AES-256-CBC
Admin-Only Changes: Only administrators can modify dashboards
JWT Authentication: Secure token-based authentication
Rate Limiting: Protection against brute-force attacks
Backup System: Automatic and manual configuration backups

Technology Stack

Backend

Runtime: Node.js
Framework: Express.js 4.21.2
Language: TypeScript 5.7.3
Authentication: JSON Web Tokens (JWT)
Encryption: AES-256-CBC for sensitive data
System Monitoring: systeminformation library
Build Tool: esbuild

Frontend

Framework: React 18.3.1 with TypeScript
UI Library: Material-UI (MUI) 6.4.3
State Management: React Context API
Routing: React Router DOM 7.2.0
Drag & Drop: @dnd-kit for sortable widgets
Charts: MUI X-Charts for data visualization
Build Tool: Vite 6.2.2
Styling: Emotion (CSS-in-JS)

Other Tools

Containerization: Docker
Package Manager: npm
Development: Nodemon, ESLint, ts-node

Getting Started

Prerequisites

Node.js: Version 18.x or higher
npm: Version 9.x or higher (comes with Node.js)
Docker (optional): For containerized deployment

Installation

Clone the repository:

git clone https://github.com/QuantomDevs/quantomos.git
cd quantomos

Install dependencies:
```
npm install
```
This will automatically install dependencies for both backend and frontend.
Set up environment variables: Create a .env file in the root directory:
```
SECRET=your_secret_key_here
```
Generate a secure secret key:
```
openssl rand -base64 32
```

Running in Development Mode

Start both backend and frontend development servers:

npm run dev

Backend runs on: http://localhost:2525
Frontend runs on: http://localhost:5173 (default Vite port)

Building for Production

Build both backend and frontend:

npm run build

This creates optimized production builds in:

backend/dist/ - Bundled backend server
frontend/dist/ - Static frontend assets

Docker Support

Supported Architectures

QuantomOS Docker images support the following architectures:

linux/amd64 - Standard x86-64 servers, PCs, and cloud instances
linux/arm64 - ARM 64-bit devices including:
- Raspberry Pi 3/4/5 (64-bit OS)
- Apple Silicon Macs (M1/M2/M3)
- AWS Graviton instances
- ARM-based cloud servers
linux/arm/v7 - ARM 32-bit devices including:
- Raspberry Pi 2/3/4 (32-bit OS)
- Older Raspberry Pi models
- IoT devices with ARMv7 processors

Docker will automatically pull the correct architecture for your system.

Raspberry Pi Deployment

QuantomOS runs on all Raspberry Pi models (2+) with both 32-bit and 64-bit operating systems.

Recommended Setup:

Raspberry Pi 4/5 with 4GB+ RAM (64-bit OS recommended)
For older models (Pi 2/3), the linux/arm/v7 (32-bit) variant is automatically used
Ensure at least 2GB free disk space
Use privileged mode for hardware monitoring features

Using Docker Compose

The easiest way to run QuantomOS is with Docker Compose:

Create a docker-compose.yml file:

---
services:
  quantomos:
      container_name: quantomos
      image: ghcr.io/quantomdevs/quantomos:latest
      privileged: true
      #network_mode: host # for monitoring network usage stats
      ports:
        - 2022:2022
      environment:
        - SECRET=YOUR_SECRET_KEY
      volumes:
        - /sys:/sys:ro
        - /docker/quantomos/config:/config
        - /docker/quantomos/uploads:/app/public/uploads
        - /var/run/docker.sock:/var/run/docker.sock
      restart: unless-stopped
      labels:
        - "com.centurylinklabs.watchtower.enable=true"

Start the container:

docker compose up -d

Access QuantomOS:
- Local: http://localhost:2022
- Network: http://192.168.x.x:2022
- Domain: http://your-domain.com

Building Docker Images

Build for local platform:

npm run docker:build

Build for multiple platforms (amd64 and arm64):

npm run docker:build:multi

Updating

Via Portainer:

Navigate to Stacks
Click on the quantomos stack
Click the Editor tab
Click "Update the stack"
Enable "Re-pull image and redeploy"
Click "Update"

Via Docker CLI:

cd /path/to/docker-compose.yml
docker compose down
docker compose pull
docker compose up -d

Usage

Accessing QuantomOS

QuantomOS can be accessed from any web browser:

Local device: http://localhost:2022
Local network: http://192.168.x.x:2022
Custom domain: http://www.your-dashboard.com

Important

Assign a static IP address to your server so devices on your network can reliably access QuantomOS.

Installing as PWA

QuantomOS can be installed as a Progressive Web App on:

Chrome: Mac, Windows, Android, Linux (click install icon in address bar)
Safari: iOS/iPadOS (Share menu → Add to Home Screen)

Project Structure

QuantomOS-main/
├── backend/
│   ├── src/
│   │   ├── routes/         # API route handlers
│   │   ├── middleware/     # Authentication, rate limiting
│   │   ├── config/         # Configuration files
│   │   ├── utils/          # Utility functions
│   │   └── types/          # TypeScript type definitions
│   ├── index.ts           # Backend entry point
│   ├── package.json       # Backend dependencies
│   └── tsconfig.json      # TypeScript configuration
├── frontend/
│   ├── src/
│   │   ├── components/    # React components
│   │   ├── api/           # API client functions
│   │   ├── context/       # React context providers
│   │   ├── hooks/         # Custom React hooks
│   │   ├── theme/         # MUI theme and styles
│   │   ├── types/         # TypeScript types
│   │   └── utils/         # Utility functions
│   ├── public/            # Static assets
│   ├── index.html         # HTML entry point
│   ├── package.json       # Frontend dependencies
│   ├── vite.config.ts     # Vite configuration
│   └── tsconfig.json      # TypeScript configuration
├── extensions/            # Custom extension files
│   ├── docs/              # Extension development documentation
│   │   ├── extension-development-guide.md
│   │   ├── extension-structure.md
│   │   ├── settings-reference.md
│   │   ├── template-system.md
│   │   ├── shadow-dom-guide.md
│   │   ├── best-practices.md
│   │   ├── examples.md
│   │   ├── troubleshooting.md
│   │   └── api-reference.md
│   └── *.json             # Extension definition files
├── docker-compose.yml     # Docker Compose configuration
├── Dockerfile             # Docker build instructions
├── package.json           # Root package.json (scripts)
└── README.md              # This file

Configuration

Environment Variables

Create a .env file in the root directory:

SECRET=your_secret_key_here  # Used for JWT and encryption
PORT=2525                     # Backend port (optional, defaults to 2525)

Configuration Files

Backend Config: Located in backend/src/config/config.json
Dashboard Layout: Automatically saved to config directory
User Credentials: Securely stored with bcrypt hashing

Customizing the Dashboard

Add Widgets: Click the "+" button in the top navigation
Drag & Drop: Enter edit mode and drag widgets to reorder
Resize Widgets: Drag widget corners to resize (desktop only)
Change Background: Settings → Appearance → Upload background
Add Pages: Settings → Pages → Create new page
Manage Users: Settings → Users → Add/Edit users (admin only)

Creating Custom Extensions

QuantomOS supports custom widgets through a JSON-based extension system. Extensions are automatically discovered and integrated into the widget selector.

Quick Start:

Create an extension file in the /extensions directory:

{
  "id": "my-widget",
  "name": "myWidget",
  "title": "My Custom Widget",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "A custom widget for my dashboard",
  "settings": [
    {
      "id": "message",
      "name": "Message",
      "type": "text",
      "defaultValue": "Hello World!",
      "description": "Text to display"
    }
  ],
  "html": "<div class='widget'>{{message}}</div>",
  "css": ".widget { padding: 2rem; background: var(--color-widget-background); }",
  "javascript": "console.log('Widget loaded!');"
}

Extension appears automatically in the widget selector under "Custom Extensions"
Configure and add to your dashboard like any built-in widget

Documentation:

Comprehensive extension development documentation is available in /docs/extensions/:

Extension Development Guide - Getting started
Extension Structure - JSON schema and required fields
Settings Reference - All available setting types
Template System - Dynamic content with placeholders
Shadow DOM Guide - Style isolation and theming
Best Practices - Code quality and performance
Examples - Complete extension examples
Troubleshooting - Common issues and solutions
API Reference - Available APIs and utilities

Development

Local Development

Install dependencies:
```
npm install
```
Start development servers:
```
npm run dev
```
Access the application:
- Frontend: http://localhost:5173
- Backend API: http://localhost:2525

Code Style and Conventions

TypeScript: Strict mode enabled
ESLint: Configured for TypeScript and React
Formatting: Consistent code formatting enforced
Commit Messages: Use conventional commit format
Testing: Run npm test before committing

Project Scripts

npm run dev          # Start both backend and frontend in dev mode
npm run build        # Build both backend and frontend
npm run lint         # Lint both backend and frontend
npm install          # Install dependencies (runs preinstall script)

Documentation

Comprehensive documentation is available in the /docs directory:

Getting Started

Prerequisites - System requirements and dependencies
Installation - Docker, manual, and PM2 installation guides
Configuration - Environment setup and configuration options

User Guide

Dashboard Basics - Learn to use the dashboard
Widgets Guide - Complete widget documentation
Settings - Customize your dashboard

Developer Guide

Introduction - Architecture and development overview
Extension Structure - Create custom widgets
API Reference - Frontend and backend APIs
Theming Guide - Customize colors and styles

Contributing

How to Contribute - Contribution guidelines
Code of Conduct - Community standards
Development Setup - Setup your dev environment

Extensions

Extension Development - Complete extension development documentation

For a complete overview, visit the Documentation Home.

Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'feat: add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Contribution Guidelines

Follow the existing code style and conventions
Write clear, descriptive commit messages
Add tests for new features when applicable
Update documentation as needed
Ensure all tests pass before submitting PR

Reporting Issues

Please report bugs and request features through GitHub Issues.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

Material-UI - For the excellent React component library
The Homelab Community - For inspiration and feedback
Open Source Contributors - For making this project possible

Made with ❤️ for the homelab community

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
.github		.github
docs		docs
extensions		extensions
public/uploads		public/uploads
src		src
.dockerignore		.dockerignore
.env		.env
.gitignore		.gitignore
.gitignore copy		.gitignore copy
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
DOCKER.md		DOCKER.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.rpi.yml		docker-compose.rpi.yml
docker-compose.yml		docker-compose.yml
error.md		error.md
esbuild.config.js		esbuild.config.js
eslint.backend.config.mjs		eslint.backend.config.mjs
eslint.frontend.config.mjs		eslint.frontend.config.mjs
nodemon.json		nodemon.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.backend.json		tsconfig.backend.json
tsconfig.frontend.json		tsconfig.frontend.json
tsconfig.frontend.tsbuildinfo		tsconfig.frontend.tsbuildinfo
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

License

QuantomDevs/QuantomOS

Folders and files

Latest commit

History

Repository files navigation

QuantomOS

Table of Contents

About QuantomOS

Key Features

Features

Dashboard & Widgets

Customization

Privacy & Security

Technology Stack

Backend

Frontend

Other Tools

Getting Started

Prerequisites

Installation

Running in Development Mode

Building for Production

Docker Support

Supported Architectures

Raspberry Pi Deployment

Using Docker Compose

Building Docker Images

Updating

Via Portainer:

Via Docker CLI:

Usage

Accessing QuantomOS

Installing as PWA

Project Structure

Configuration

Environment Variables

Configuration Files

Customizing the Dashboard

Creating Custom Extensions

Development

Local Development

Code Style and Conventions

Project Scripts

Documentation

Getting Started

User Guide

Developer Guide

Contributing

Extensions

Contributing

Contribution Guidelines

Reporting Issues

License

Acknowledgments

About

Resources

License

Code of conduct

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Languages

Packages