LokiCMS Backup GitHub Plugin

Database backup plugin for LokiCMS with GitHub versioning, scheduling, and restore capabilities.

Features

• GitHub Storage: Store backups in a GitHub repository
• Versioning: Full Git history for all backups
• Scheduling: Automatic backups at configurable intervals
• Restore: Restore from any previous backup
• Diff: See changes since last backup
• 7 MCP Tools: Full management via Claude/AI agents

Installation

npm install lokicms-plugin-backup-github

Quick Start

1. Create a GitHub Personal Access Token

1. Go to GitHub Settings > Developer settings > Personal access tokens
2. Create a new token with repo scope
3. Copy the token

2. Register the Plugin

import { createLokiCMS } from 'lokicms';
import backupPlugin from 'lokicms-plugin-backup-github';

const cms = createLokiCMS({
  plugins: [backupPlugin],
  backup: {
    token: process.env.GITHUB_TOKEN,
    owner: 'your-username',
    repo: 'lokicms-backups',
    branch: 'main',
    autoBackup: true,
    intervalMinutes: 60,
  },
});

3. Use via MCP Tools

| Tool | Description | |------|-------------| | backup_status | Get connection status and last backup info | | backup_now | Create immediate backup | | backup_list | List available backups | | backup_restore | Restore from specific backup | | backup_schedule | Configure automatic backups | | backup_diff | Show changes since last backup | | backup_configure | Configure GitHub settings |

Configuration

interface BackupGitHubConfig {
  // Required
  token: string;           // GitHub Personal Access Token
  owner: string;           // GitHub username or organization
  repo: string;            // Repository name

  // Optional
  branch?: string;         // Branch name (default: 'main')
  path?: string;           // Path in repo (default: 'backups')
  autoBackup?: boolean;    // Enable auto-backup (default: false)
  intervalMinutes?: number; // Backup interval (default: 60)
  commitPrefix?: string;   // Commit message prefix
  dataDir?: string;        // Data directory (default: 'data')
  patterns?: string[];     // File patterns (default: ['*.db', '*.json'])
}

MCP Tool Examples

Check Status

{
  "tool": "backup_status",
  "input": {}
}

Create Backup

{
  "tool": "backup_now",
  "input": {
    "message": "Before deploying new features"
  }
}

List Backups

{
  "tool": "backup_list",
  "input": {
    "limit": 10
  }
}

Restore from Backup

{
  "tool": "backup_restore",
  "input": {
    "backupId": "abc123...",
    "confirm": true
  }
}

Configure Schedule

{
  "tool": "backup_schedule",
  "input": {
    "enabled": true,
    "intervalMinutes": 30
  }
}

Check for Changes

{
  "tool": "backup_diff",
  "input": {}
}

Configure GitHub

{
  "tool": "backup_configure",
  "input": {
    "token": "ghp_...",
    "owner": "myuser",
    "repo": "my-backups",
    "createRepo": true
  }
}

API Reference

BackupService

interface BackupService {
  backup(message?: string): Promise<BackupResult>;
  list(limit?: number): Promise<BackupInfo[]>;
  restore(backupId: string): Promise<RestoreResult>;
  diff(): Promise<DiffResult>;
  getBackup(backupId: string): Promise<BackupInfo | null>;
  getLastBackup(): Promise<BackupInfo | null>;
}

Scheduler

interface Scheduler {
  start(): void;
  stop(): void;
  isRunning(): boolean;
  getConfig(): ScheduleConfig;
  setConfig(config: Partial<ScheduleConfig>): void;
  triggerNow(): Promise<void>;
  getNextRun(): number | null;
  getLastRun(): number | null;
}

How It Works

1. Backup: Reads all database files from data/ directory, commits them to GitHub
2. Versioning: Each backup is a Git commit with timestamp and file info
3. Restore: Downloads files from specific commit, creates local backup first
4. Diff: Compares local files with last backup to detect changes

Security

• Store your GitHub token securely (environment variables)
• Use a private repository for backups
• Token only needs repo scope
• Consider using a dedicated backup repository

Best Practices

1. Use a Private Repo: Keep your data secure
2. Set Reasonable Intervals: 30-60 minutes is usually sufficient
3. Test Restores: Periodically verify backups work
4. Monitor Backups: Check status regularly
5. Use Meaningful Messages: Add context to manual backups

License

MIT