forgejo-config/DEPLOYMENT_GUIDE.md

Forgejo Deployment Guide

This guide provides detailed step-by-step instructions for deploying the Forgejo git repository on a GCP VM with SSL.

Prerequisites

1. Google Cloud Platform account with project ID: homelab-454516
2. Terraform installed locally
3. Ansible installed locally
4. SSH key pair at ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub
5. DuckDNS account with subdomain: bootknockery.duckdns.org

Deployment Steps

1. Infrastructure Provisioning with Terraform

# Navigate to the terraform directory
cd terraform

# Initialize Terraform
terraform init

# Apply the Terraform configuration
terraform apply

This will create a GCP VM in the us-central1-a zone with the following specifications:

• Machine type: e2-medium
• Disk size: 50GB
• Operating system: Debian

2. Update DuckDNS

Ensure your DuckDNS subdomain (bootknockery.duckdns.org) points to the VM's external IP address.

3. Deploy Forgejo with Ansible

# Navigate to the ansible directory
cd ../ansible

# Run the Ansible playbook
ansible-playbook -i inventory.yml forgejo.yml

This will:

• Install Docker and Docker Compose
• Deploy Forgejo in a Docker container
• Configure Nginx as a reverse proxy
• Set up SSL with Let's Encrypt
• Configure SQLite with WAL mode for better performance

4. Verify the Deployment

1. Access Forgejo via HTTPS:

   https://bootknockery.duckdns.org
   

2. Check that SSL is properly configured:

   ssh -i ~/.ssh/id_rsa debian@VM_IP_ADDRESS "sudo certbot certificates"
   

3. Verify that SQLite WAL mode is active:

   ssh -i ~/.ssh/id_rsa debian@VM_IP_ADDRESS "sudo ls -la /opt/forgejo/data/gitea/gitea.db*"
   

   You should see additional files like gitea.db-wal and gitea.db-shm.

Post-Deployment Configuration

Initial Forgejo Setup

When you first access Forgejo, you'll need to:

1. Set up the admin account
2. Configure the database settings (SQLite is already configured)
3. Set up repository settings

SSH Access for Git Operations

To use Git over SSH:

# Add to ~/.ssh/config
Host bootknockery.duckdns.org
  Port 222
  User git
  IdentityFile ~/.ssh/id_rsa

Then clone repositories using:

git clone git@bootknockery.duckdns.org:username/repository.git

Maintenance Tasks

SSL Certificate Renewal

SSL certificates are automatically renewed weekly. To manually renew:

ssh -i ~/.ssh/id_rsa debian@VM_IP_ADDRESS "sudo /etc/cron.weekly/certbot-renew"

Database Backup

To back up the Forgejo database:

ssh -i ~/.ssh/id_rsa debian@VM_IP_ADDRESS "sudo cp /opt/forgejo/data/gitea/gitea.db ~/backup_gitea.db"
scp -i ~/.ssh/id_rsa debian@VM_IP_ADDRESS:~/backup_gitea.db ./

Updating Forgejo

Forgejo is configured to automatically update to the latest version on a weekly basis.

Automatic Updates

The system includes an automatic update mechanism that:

• Checks for new Forgejo versions every Sunday at 3:00 AM
• Creates a backup before updating
• Updates the Docker image and restarts the service
• Logs all operations to /opt/forgejo/logs/update.log

To manually trigger an update check:

ssh -i ~/.ssh/id_rsa debian@VM_IP_ADDRESS "sudo /opt/forgejo/scripts/update-forgejo.sh"

To view update logs:

ssh -i ~/.ssh/id_rsa debian@VM_IP_ADDRESS "sudo cat /opt/forgejo/logs/update.log"

Manual Updates

If you prefer to update manually:

1. Edit ansible/templates/docker-compose.yml.j2 to update the image version
2. Run the Ansible playbook again:

   cd ansible
   ansible-playbook -i inventory.yml forgejo.yml
   

Troubleshooting

Common Issues

1. Cannot access Forgejo via HTTPS

   • Check Nginx status: ssh -i ~/.ssh/id_rsa debian@VM_IP_ADDRESS "sudo systemctl status nginx"
   • Verify SSL certificates: ssh -i ~/.ssh/id_rsa debian@VM_IP_ADDRESS "sudo ls -la /etc/letsencrypt/live/bootknockery.duckdns.org/"

2. Forgejo container not running

   • Check Docker status: ssh -i ~/.ssh/id_rsa debian@VM_IP_ADDRESS "sudo docker ps"
   • View Forgejo logs: ssh -i ~/.ssh/id_rsa debian@VM_IP_ADDRESS "sudo docker logs forgejo"

3. SSL certificate issues

   • Check certificate logs: ssh -i ~/.ssh/id_rsa debian@VM_IP_ADDRESS "sudo tail -f /var/log/letsencrypt/letsencrypt.log"
   • Force renewal: ssh -i ~/.ssh/id_rsa debian@VM_IP_ADDRESS "sudo /etc/cron.weekly/certbot-renew"

4. Performance issues

   • Verify WAL mode: ssh -i ~/.ssh/id_rsa debian@VM_IP_ADDRESS "sudo ls -la /opt/forgejo/data/gitea/gitea.db*"
   • Check system resources: ssh -i ~/.ssh/id_rsa debian@VM_IP_ADDRESS "top"