GitHub Backup Service

Disclaimers:

AI is responsible for over half of the coding. Also keep in mind that this software is mostly developed for personal use by myself and thus might not receive all feature requests desired.

################################################################

A comprehensive web-based solution for backing up GitHub repositories with scheduling, multiple backup formats, and user management.

Features

• Web UI with Authentication: Secure login system with automatic admin user creation
• Password Reset System: Forgot password functionality with server-logged reset codes
• Repository Management: Add, edit, delete, and manually trigger backups for GitHub repositories
• Multiple Backup Formats: Support for folder structure, ZIP, and TAR.GZ archives
• Flexible Scheduling:
  • Manual backup triggering
  • Predefined schedules: Hourly, Daily (2 AM), Weekly (Sunday 2 AM), Monthly (1st, 2 AM)
  • Custom schedules: Every X days/weeks/months at specified time

• Retention Policies: Configurable backup retention (1-50 versions) with automatic cleanup
• Private Repository Support: Works with GitHub Personal Access Tokens
• Dashboard Overview: Statistics cards showing repository count, active repos, completed and failed jobs
• Job Monitoring:
  • Real-time backup job status tracking (running, completed, failed)
  • Detailed backup job history with timestamps
  • Recent jobs display on dashboard

• User Settings: Change username and password functionality
• Docker Ready: Fully containerized with health checks and proper user permissions

Quick Start

Using Docker Compose (Recommended)

1. Clone the repository:

git clone https://github.com/GitTimeraider/GithubBackup.git
cd GithubBackup

2. Copy and modify the environment file:

cp .env.example .env
# Edit .env with your preferred settings

3. Start the service:

docker-compose up -d

4. Access the web interface at http://localhost:8080

5. Login with default credentials (created automatically):

   • Username: admin
   • Password: changeme
   • ⚠️ Important: Change the default password immediately after first login via Settings

Using Pre-built Docker Image

docker run -d \
  --name github-backup \
  -p 8080:8080 \
  -v ./data:/app/data \
  -v ./backups:/app/backups \
  -v ./logs:/app/logs \
  -e SECRET_KEY=your-secret-key \
  ghcr.io/gittimeraider/githubbackup:latest

Configuration

Environment Variables

Variable	Description	Default
SECRET_KEY	Flask secret key for sessions	dev-secret-key-change-in-production
DATABASE_URL	SQLite database file path	sqlite:////app/data/github_backup.db
PUID	User ID for file permissions	1000
PGID	Group ID for file permissions	1000

GitHub Token Setup

For private repositories, you'll need a GitHub Personal Access Token:

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Generate a new token with repo scope for private repositories
3. Add the token when configuring repositories in the web UI

Backup Formats

• Folder Structure: Preserves the original repository structure
• ZIP Archive: Compressed archive with good compression ratio
• TAR.GZ Archive: Unix-style compressed archive with excellent compression

Scheduling Options

• Manual: Backup only when triggered manually via the web interface
• Hourly: Every hour at minute 0
• Daily: Every day at 2:00 AM
• Weekly: Every Sunday at 2:00 AM
• Monthly: 1st of every month at 2:00 AM
• Custom: Every X days/weeks/months at a specified time
  • Days: 1-365 day intervals
  • Weeks: 1-52 week intervals
  • Months: 1-12 month intervals
  • Custom time selection (24-hour format)

Web Interface

The application provides a modern, responsive web interface with:

Dashboard

• Repository statistics (total, active, completed backups, failed jobs)
• Recent repositories overview with status indicators
• Recent backup jobs with real-time status
• Quick access to add new repositories

Repository Management

• Add repositories with GitHub URL
• Configure backup format (Folder, ZIP, TAR.GZ)
• Set up scheduling (predefined or custom intervals)
• Configure retention policies (1-50 backup versions)
• Edit repository settings
• Manual backup triggering
• Repository activation/deactivation

Backup Jobs

• Real-time job status monitoring
• Complete backup history with timestamps
• Job status indicators (running, completed, failed)
• Auto-refresh for running jobs

User Management

• Secure login system
• Password reset functionality (codes logged to server)
• User settings (change username/password)
• Automatic admin user creation on first run

API Endpoints

• GET /health - Health check endpoint for monitoring
• GET /favicon.ico - Application favicon
• Web interface available at / (requires authentication)

Development

Local Development

1. Install dependencies:

pip install -r requirements.txt

2. Initialize database:

python init_db.py

3. Run the application:

python app.py

Building Docker Image

docker build -t github-backup .

Security Considerations

• Change default credentials: The application creates a default admin user (admin/changeme) - change this immediately
• Change the SECRET_KEY: Use a strong, unique secret key in production
• Use strong passwords: Enforce strong passwords for all user accounts
• GitHub tokens: Personal Access Tokens are stored in the database for private repository access
• Container security: The application runs as non-root user in Docker with configurable PUID/PGID
• Regular updates: Keep the application and dependencies updated for security patches
• Password reset: Reset codes are logged to server logs for manual distribution

Backup Storage

Backups are organized as follows:

/app/backups/
├── user_1/
│   ├── repository1/
│   │   ├── repository1_20241214_020000.zip
│   │   └── repository1_20241213_020000.zip
│   └── repository2/
│       └── repository2_20241214_020000/
└── user_2/
    └── ...

Monitoring

• Web Interface: Real-time backup job status and repository management
• Dashboard: Visual overview of repository count, active repos, and job statistics
• Job History: Complete backup job history with timestamps and status
• Container Health: docker healthcheck github-backup
• Application Logs: docker logs github-backup
• Persistent Logs: Available in /app/logs/ directory inside container
• Health Endpoint: GET /health returns JSON status for external monitoring

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

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