@riligar/elysia-backup

An open source project by RiLiGar

A powerful Elysia plugin for R2/S3 backup with a beautiful built-in UI dashboard. Designed for Bun runtime with native S3 client for optimal performance.

✨ Features

• 📁 Smart Backup — Backup local directories to R2/S3 with file filtering
• 🔄 Scheduled Backups — Cron-based automatic backups
• 🖥️ Beautiful Dashboard — Modern UI with real-time status
• 🔐 Secure Authentication — Session-based auth with 2FA/TOTP support
• 🧭 Guided Onboarding — Multi-step setup wizard for first-time configuration
• ⬇️ One-Click Restore — Easily restore files from backup
• 🗑️ Backup Management — Delete old backups from the UI
• ⚙️ Runtime Configuration — Update settings without restarting

📦 Installation

bun add @riligar/elysia-backup

Peer Dependencies

bun add elysia @elysiajs/html

🚀 Quick Start

import { Elysia } from 'elysia'
import { r2Backup } from '@riligar/elysia-backup'

const app = new Elysia()
    .use(
        r2Backup({
            sourceDir: './data',
        })
    )
    .listen(3000)

console.log('🦊 Server running at http://localhost:3000')
console.log('📦 Backup UI at http://localhost:3000/backup')

On first run, you'll be guided through an onboarding wizard to configure:

• Storage credentials (R2/S3)
• Backup schedule
• Admin authentication

⚙️ Configuration

Plugin Options

Option	Type	Required	Description
sourceDir	string	✅	Local directory to backup
configPath	string	❌	Path to save runtime config (default: same directory as sourceDir)

Runtime Configuration (via UI or backup-config.json)

Option	Type	Description
bucket	string	R2/S3 bucket name
accessKeyId	string	R2/S3 Access Key ID
secretAccessKey	string	R2/S3 Secret Access Key
endpoint	string	R2/S3 Endpoint URL
prefix	string	Prefix for S3 keys (e.g., backups/)
extensions	string[]	File extensions to include (empty = all files)
cronSchedule	string	Cron expression for scheduled backups
cronEnabled	boolean	Enable/disable scheduled backups
auth.username	string	Admin username
auth.password	string	Admin password
auth.totpSecret	string	TOTP secret for 2FA (optional)

🔌 API Endpoints

The plugin adds the following routes under /backup:

Pages

Method	Path	Description
GET	/backup	Dashboard UI
GET	/backup/login	Login page
GET	/backup/onboarding	First-time setup wizard

Authentication

Method	Path	Description
POST	/backup/auth/login	Authenticate user
POST	/backup/auth/logout	End session

Backup Operations

Method	Path	Description
POST	/backup/api/run	Trigger manual backup
GET	/backup/api/files	List remote backup files
POST	/backup/api/restore	Restore a specific file
POST	/backup/api/delete	Delete a remote backup file
POST	/backup/api/config	Update configuration

Two-Factor Authentication (TOTP)

Method	Path	Description
GET	/backup/api/totp/status	Check 2FA status
POST	/backup/api/totp/generate	Generate new TOTP secret & QR
POST	/backup/api/totp/verify	Verify and enable 2FA
POST	/backup/api/totp/disable	Disable 2FA

☁️ Cloud Deployment (Fly.io, Railway, etc.)

For cloud platforms with ephemeral file systems, mount a persistent volume at your sourceDir path. The configuration file will be automatically saved alongside your data:

import { Elysia } from 'elysia'
import { r2Backup } from '@riligar/elysia-backup'

const app = new Elysia()
    .use(
        r2Backup({
            // Mount your persistent volume here
            // Config will be saved at /data/backup-config.json
            sourceDir: '/data',
        })
    )
    .listen(3000)

This ensures both your backup data and configuration persist across deployments and restarts.

🔐 Security Features

Session-Based Authentication

• Secure session tokens with configurable expiration
• HTTP-only cookies for session management
• Automatic session cleanup

Two-Factor Authentication (TOTP)

• Compatible with any authenticator app (Google Authenticator, Authy, etc.)
• QR code for easy setup
• Backup codes support

📂 Project Structure

src/
├── index.js              # Main plugin entry
├── assets/               # Static assets (favicon, logo)
├── views/
│   ├── LoginPage.js      # Login page
│   ├── DashboardPage.js  # Main dashboard
│   ├── OnboardingPage.js # Setup wizard
│   ├── components/       # UI components
│   │   ├── ActionArea.js
│   │   ├── FilesTab.js
│   │   ├── Footer.js
│   │   ├── Head.js
│   │   ├── Header.js
│   │   ├── LoginCard.js
│   │   ├── OnboardingCard.js
│   │   ├── SecuritySection.js
│   │   ├── SettingsTab.js
│   │   └── StatusCards.js
│   └── scripts/          # Client-side JavaScript
│       ├── backupApp.js
│       ├── loginApp.js
│       └── onboardingApp.js

🤝 Contributing

Contributions are welcome! See our GitHub repository for more information.

📄 License

MIT © RiLiGar

Made with ❤️ by RiLiGar