Complete Guide: Gitea Setup & Proxmox GitOps (Backup & Restore)

## Complete Guide: Gitea Setup & Proxmox GitOps (Backup & Restore)

and Step-by-Step Guide: Automated Gitea S3 Backup to TrueNAS SCALE (RustFS)##

Introduction:

Hello fellow homelabbers,

I hope this guide proves useful to you. If not, consider it personal documentation for my future self to look back on how, what, and why things were configured this way.

I designed this setup because I operate a Proxmox cluster alongside a standalone Proxmox server. The cluster runs a Gitea VM, while the standalone server hosts RustFS as an app on TrueNAS SCALE. Beyond standard VM and LXC backups, backing up the Proxmox hosts themselves is critical. This specific architecture provides a highly resilient strategy for that scenario.

Why I use gitea (lightweight)!

Let's dive straight into the deployment.

Part 1: Gitea Installation & Configuration

1. Create the LXC Container/ or standalone linux laptop

1. Open the Proxmox Web UI and click Create CT.

2. General: Check the Unprivileged container box. Name the container (e.g., gitea) and set a secure root password.

3. Template: Select a clean Debian 12 or 13 template.

4. Resources: Allocate a minimum of 10 GB to 20 GB of disk space, 1–2 CPU cores, and 1024 MB RAM.

5. Network: Attach to vmbr0 (typically), and assign either a static IP address or configure DHCP.

6. Boot up the container.

2. Prepare the System & Download Gitea Binary

bash

# Update the system and install base packages

apt update && apt upgrade -y

apt install git sqlite3 gnupg2 -y

# Create the Gitea system user and home directory manually

adduser --system --shell /bin/bash --gecos 'Git Version Control' --group --disabled-password git

mkdir -p /home/git/.ssh

chown -R git:git /home/git

chmod 700 /home/git/.ssh

# Download the Gitea binary (Version 1.27.0)

wget -O gitea https://dl.gitea.com/gitea/1.27.0/gitea-1.27.0-linux-amd64

apt install cosign

verify:

cosign verify-blob gitea-1.27.0-linux-amd64 --bundle gitea-1.27.0-linux-amd64.sigstore.json --certificate-oidc-issuer=https://token.actions.githubusercontent.com/ --certificate-identity-regexp="https://github.com/go-gitea/gitea/.github/workflows/release-.*"

chmod +x gitea

chmod +x /usr/local/bin/gitea

# Create data directories and configure permissions

mkdir -p /var/lib/gitea/{custom,data,log}

chown -R git:git /var/lib/gitea/

chmod -R 750 /var/lib/gitea/

mkdir /etc/gitea

chown root:git /etc/gitea

chmod 770 /etc/gitea

3. Configure the Background Service (Systemd) & Container SSH

While still inside the Gitea container, create the systemd service file:

bash

nano /etc/systemd/system/gitea.service

Paste the following configuration:

ini

[Unit]

Description=Gitea (Git with a cup of tea)

After=network.target

[Service]

Type=simple

User=git

Group=git

WorkingDirectory=/var/lib/gitea/

ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini

Restart=always

Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea

[Install]

WantedBy=multi-user.target

(Save using Ctrl+O, press Enter, and exit using Ctrl+X).

Next, expose the Linux SSH port to recognize Gitea keys:

bash

nano /etc/ssh/sshd_config

Append the following lines to the bottom of the file:

text

PubkeyAuthentication yes

AuthorizedKeysFile .ssh/authorized_keys /home/git/.ssh/authorized_keys

Enable and start all required services:

bash

systemctl daemon-reload

systemctl enable --now gitea

systemctl restart sshd

4. Complete the Web Installation

1. Open your web browser and navigate to http://<GITEA_IP>:3000.

2. Database Type: Select SQLite3.

3. Gitea Base URL: Change this to the actual IP address of your Gitea container.

4. Scroll down, expand the Administrator Account Settings, and create your admin user. (Ensure you check the option to make the instance private for enhanced security).

5. Click Install Gitea.

Part 2: Proxmox Host Integration (Backup Setup)

1. Establish the SSH Handshake

Generate a secure SSH key pair if you do not have one already:

bash

ssh-keygen -t rsa -b 4000

(Press Enter three times to accept defaults and skip the passphrase).

View and copy the public key:

bash

cat ~/.ssh/id_rsa.pub

In the Gitea Web UI:

1. Go to Settings (top right dropdown menu under your profile icon).

2. Navigate to SSH / GPG Keys -> Add Key.

3. Name it Proxmox Host, paste the copied public key, and save.

2. Create the Repository and Initialize the First Push

1. In Gitea, click the + icon in the top right corner -> New Repository.

2. Repository Name: proxmox-backup.

3. Check the Private visibility box.

4. Click Create Repository.

Return to your Proxmox Host terminal and run the following:

bash

cd /etc/pve

git init

# Configure Git identity

git config --global [user.email](http://user.email/) "[email protected]"

git config --global [user.name](http://user.name/) "Proxmox Host"

# Link the Gitea repository (Replace <GITEA_IP> with your actual Gitea IP)

git remote add origin git@<GITEA_IP>:spruitmans/proxmox-backup.git

# Stage, commit, and push files

git add .

git commit -m "Initial automated Proxmox backup"

git branch -M main

git push -u origin main

(Type yes when prompted to trust the host).

3. Automate Backups via Cronjob

Set up a nightly automated backup at 02:00 AM to sync any Proxmox configuration updates.

Create the backup script:

bash

nano /usr/local/bin/[proxmox-git-backup.sh](http://proxmox-git-backup.sh/)

Paste the following code logic:

bash

#!/bin/bash

cd /etc/pve

git add .

if ! git diff-index --quiet HEAD --; then

git commit -m "Automated backup on $(date +'%Y-%m-%d %H:%M')"

git push origin main

Make the script executable:

bash

chmod +x /usr/local/bin/[proxmox-git-backup.sh](http://proxmox-git-backup.sh/)

Add the script to the system cron schedule:

bash

crontab -e

Append this line to the bottom of the crontab file:

text

0 2 * * * /usr/local/bin/[proxmox-git-backup.sh](http://proxmox-git-backup.sh/)> /dev/null 2>&1

Part 3: Disaster Recovery – How to Restore Your Backup

If your Proxmox host experiences a catastrophic failure (e.g., OS drive failure), use these steps to restore your network configurations, cluster setups, and VM definitions exactly as they were in under 5 minutes.

1. Fresh Proxmox Base Installation

2. Install Proxmox VE onto the machine using the official ISO.

3. During installation, use the exact same Hostname (e.g., pve1) and same IP address as before. This is critical because Proxmox configurations are bound directly to the hostname.

4. Restore SSH Access in Gitea

Because the installation is fresh, the host needs a new SSH key pair to authenticate with Gitea.

1. Log in to the new Proxmox host via SSH.

2. Generate a new key pair: ssh-keygen -t rsa -b 4000 (press enter 3 times).

3. Output the public key: cat ~/.ssh/id_rsa.pub

4. Delete the old Proxmox key inside your Gitea profile settings and add this new public key.

5. Apply the Restored Configuration

Because the /etc/pve folder in Proxmox utilizes a unique cluster file system (pmxcfs), you cannot clone a git repository directly over it. The backup data must be pulled into a temporary directory first and then copied into place.

Run these commands on the new Proxmox host:

bash

# 1. Download the backup temporarily to the /tmp directory

cd /tmp

git clone git@<gitea-ip>:spruitmans😁/proxmox-backup.git

# 2. Stop the Proxmox cluster service temporarily to prevent file write locks

systemctl stop pve-cluster

# 3. Copy the core configuration files back into the native pve directory

cp -r /tmp/proxmox-backup/* /etc/pve/

# 4. Restart the Proxmox cluster service

systemctl start pve-cluster

4. Finalizing the Recovery

As soon as the pve-cluster service initializes, Proxmox reads the restored setup files instantly. Refresh your Proxmox Web UI to verify:

· All previous storage pools are remapped and connected.

· All virtual machines and containers are populated in the inventory with their original resource IDs (e.g., 112, 200, 203).

Your system paths are fully restored. You can now use the Proxmox GUI to restore the underlying VM virtual disk backups hosted on your TrueNAS /RustFS whatever storage pool.

add on:Step-by-Step Guide: Automated Gitea S3 Backup to TrueNAS SCALE (RustFS)

Step-by-Step Guide: Automated Gitea S3 Backup to TrueNAS SCALE (RustFS)

This guide configures a nightly, full, compressed snapshot (database, repositories, and configurations) of Gitea, sent directly to the TrueNAS SCALE ZFS storage pool using the local S3 API.

Step 1: Prepare RustFS / S3 in TrueNAS SCALE

Before the Gitea container can transmit data, the correct permissions and storage bucket must be configured in your RustFS/MinIO environment

Open the RustFS / MinIO Web UI.Navigate to Buckets in the left menu and click Create Bucket.

Name the bucket: gitea-backups.Navigate to Access Keys in the left menu and click + Add Access Key.

Copy the generated keys immediately to a secure text file; Access Key ID (the username)Secret Access Key (the password)Click Create to permanently activate the keys.

Step 2: Install S3 Tools in the Gitea ContainerLog in to the Console of your Gitea container as the root user via the Proxmox Web UI.Install the official AWS CLI client (the universal tool for communicating with S3 storage):bash apt update && apt install awscli -y

Step 3: Configure the Backup Script

This script forces Gitea to generate a dump within the /tmp directory using the secure git user. The root user then pushes this file directly to TrueNAS via the local IP address, preventing proxy and signature errors.Create the script file inside the container:bash

nano /usr/local/bin/[gitea-s3-backup.sh](http://gitea-s3-backup.sh/)

Paste the following code exactly into the file bash:

#!/bin/bash

# ==========================================

# 1. S3 CREDENTIALS (Direct via RustFS)

# ==========================================

export AWS_ACCESS_KEY_ID="YOUR_EXACT_ACCESS_KEY"

export AWS_SECRET_ACCESS_KEY="YOUR_EXACT_SECRET_KEY"

export AWS_DEFAULT_REGION="us-east-1"

# ==========================================

# 2. CONFIGURATION SETTINGS

# ==========================================

# Use the local IP and S3 port of TrueNAS to bypass proxies

S3_ENDPOINT="http://<LOCAL_TRUENAS_IP>:<PORT>"

S3_BUCKET="gitea-backups"

# Enforce standard S3 behaviors for direct network connections

aws configure set default.s3.signature_version s3v4

aws configure set default.s3.addressing_style path

# ==========================================

# 3. BACKUP PROCESS

# ==========================================

# Navigate to the temporary directory

cd /tmp

# Create the official Gitea dump under the git user

su git -s /bin/bash -c "/usr/local/bin/gitea dump -c /etc/gitea/app.ini"

# Locate the newly created .zip file in /tmp

BACKUP_FILE=$(ls -t gitea-dump-*.zip | head -n 1)

# Upload the file via s3api directly to the TrueNAS RustFS pool

aws --endpoint-url=$S3_ENDPOINT s3api put-object \

--bucket "$S3_BUCKET" \

--key "$BACKUP_FILE" \

--body "$BACKUP_FILE"

# Clean up the temporary file in /tmp to save disk space

rm -f "$BACKUP_FILE"

Important: Update the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and S3_ENDPOINT variables with your specific local network and RustFS details.

Save the file (Ctrl+O, Enter) and exit (Ctrl+X).Make the script executable:bash chmod +x /usr/local/bin/[gitea-s3-backup.sh](http://gitea-s3-backup.sh/)

0 comments

Complete Guide: Gitea Setup & Proxmox GitOps (Backup & Restore)