mirror of
https://github.com/RayLabsHQ/gitea-mirror.git
synced 2025-12-09 13:06:45 +03:00
111 lines
5.0 KiB
Plaintext
111 lines
5.0 KiB
Plaintext
---
|
||
layout: ../../layouts/UseCaseLayout.astro
|
||
title: "Self-Hosted GitHub Backup on Proxmox LXC | Gitea Mirror Homelab Setup"
|
||
description: "Deploy a dedicated GitHub backup appliance in your Proxmox homelab using the one-line LXC installer. Automatic syncing, snapshot-ready, homelab-optimized."
|
||
canonical: "https://gitea-mirror.com/use-cases/proxmox-lxc-homelab/"
|
||
---
|
||
|
||
# Self-Hosted GitHub Backup on Proxmox LXC
|
||
|
||
## The Homelab GitHub Backup Appliance
|
||
|
||
Running GitHub backups in your homelab means **complete data ownership** without monthly SaaS fees. When most of your infrastructure lives in Proxmox VE, the community LXC script is the fastest path from zero to a dedicated backup appliance.
|
||
|
||
It handles Bun runtime, systemd services, persistent storage, and future upgrades—so you can focus on keeping your GitHub history safe and synced locally. Perfect for homelabbers who want the peace of mind of offline backups without cloud dependencies.
|
||
|
||
## Requirements
|
||
|
||
- Proxmox VE host with the [community-scripts repository](https://community-scripts.github.io/ProxmoxVE/) enabled
|
||
- Storage pool with ~6 GB free (default script allocation) and an available bridge (usually `vmbr0`)
|
||
- GitHub PAT and Gitea token scoped for mirroring
|
||
- DNS or IP address for the container on your LAN
|
||
|
||
## Step-by-step
|
||
|
||
### 1. Launch the installer
|
||
|
||
SSH into the Proxmox host and run:
|
||
|
||
```bash
|
||
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/gitea-mirror.sh)"
|
||
```
|
||
|
||
The helper script prompts for:
|
||
|
||
- **Node**: the Proxmox host that will own the container
|
||
- **Storage**: local-lvm, ZFS dataset, etc.
|
||
- **Network bridge**: e.g. `vmbr0`
|
||
- **IP assignment**: DHCP or static (consider static for a backup appliance)
|
||
- **Container size**: defaults to 2 vCPU, 2 GiB RAM, 6 GiB disk—bump RAM if you mirror large orgs
|
||
|
||
Accept the defaults or adjust as needed. The script downloads the release, installs Bun, seeds systemd, and prints the access URL on completion.
|
||
|
||
### 2. First login and setup
|
||
|
||
1. Browse to `http://<container-ip>:4321`.
|
||
2. Create the admin account (first user = admin).
|
||
3. Enter your GitHub PAT and Gitea API token in the onboarding wizard.
|
||
4. Select the GitHub owners you want mirrored—auto-discovery runs by default once scheduling is enabled, so new repositories appear automatically.
|
||
|
||
### 3. Validate persistence and services
|
||
|
||
Inside the container (`pct enter <CTID>`):
|
||
|
||
```bash
|
||
systemctl status gitea-mirror
|
||
ls /opt/gitea-mirror/data
|
||
```
|
||
|
||
You should see `gitea-mirror.db` and a `repos/` directory. Data lives under `/opt/gitea-mirror/data`; back it up or snapshot the underlying storage pool regularly.
|
||
|
||
### 4. Expose the service (optional)
|
||
|
||
- Add a Proxmox firewall rule or reverse proxy entry (Traefik/Caddy/HAProxy) if you want TLS.
|
||
- Create a DNS record (`mirror.lab.local`) pointed at the container for easier access.
|
||
|
||
### 5. Upgrades & maintenance
|
||
|
||
- Re-run the installer script; it detects existing installs, backs up `/opt/gitea-mirror/data`, downloads the latest release, and restarts the service.
|
||
- Watch for warnings about upgrades from v2 → v3 wiping config—take a snapshot first if you still run v2 artifacts.
|
||
- Check logs with `journalctl -u gitea-mirror -n 200` or `journalctl -u gitea-mirror -f` for live tailing.
|
||
|
||
## Disaster-recovery drill
|
||
|
||
1. In Proxmox, snapshot the container (or use ZFS/BTRFS snapshots on the storage pool).
|
||
2. Stop GitHub access temporarily and clone from the Gitea mirror to confirm the backup works.
|
||
3. Restore the snapshot on a different node to ensure the service boots cleanly with the preserved data volume.
|
||
|
||
<figure class="mt-8 flex flex-col items-center">
|
||
<img
|
||
src="/assets/dashboard_mobile.png"
|
||
alt="Mobile view of the Gitea Mirror dashboard running inside a Proxmox LXC container."
|
||
class="w-full max-w-sm rounded-xl border border-muted shadow-sm"
|
||
loading="lazy"
|
||
/>
|
||
<figcaption class="mt-3 text-sm text-muted-foreground text-center">
|
||
Even inside a lightweight LXC container, the dashboard stays responsive for quick health checks on the go.
|
||
</figcaption>
|
||
</figure>
|
||
|
||
## Troubleshooting
|
||
|
||
- **Port 4321 already used**: change `PORT` in `/opt/gitea-mirror.env` and restart with `systemctl restart gitea-mirror`.
|
||
- **Disk full**: extend the container disk in Proxmox, then run `pct resize <CTID> rootfs +5G`.
|
||
- **Token expired**: log in to the UI → Configuration to update GitHub/Gitea credentials.
|
||
|
||
Looking for a cluster-native deployment? Try the [Helm playbook](../deploy-with-helm-chart).
|
||
|
||
## FAQ
|
||
|
||
### What container size should I start with?
|
||
|
||
The script defaults to 2 vCPU, 2 GiB RAM, 6 GiB disk. Bump RAM for large orgs or many concurrent mirrors; you can resize disk later with `pct resize`.
|
||
|
||
### How do I upgrade the LXC deployment?
|
||
|
||
Re-run the community installer. It detects existing installs, backs up `/opt/gitea-mirror/data`, downloads the latest release, and restarts the service.
|
||
|
||
### How should I back up and restore?
|
||
|
||
Snapshot the container or back up `/opt/gitea-mirror/data`. Restore by attaching the volume to a fresh container and starting the service; your configuration is preserved.
|