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

```bash
# 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

```bash
# 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:
   ```bash
   ssh -i ~/.ssh/id_rsa debian@VM_IP_ADDRESS "sudo certbot certificates"
   ```

3. Verify that SQLite WAL mode is active:
   ```bash
   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:

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

Then clone repositories using:
```bash
git clone git@bootknockery.duckdns.org:username/repository.git
```

## Maintenance Tasks

### SSL Certificate Renewal

SSL certificates are automatically renewed weekly. To manually renew:

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

### Database Backup

To back up the Forgejo database:

```bash
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

To update Forgejo to a newer version:

1. Edit `ansible/templates/docker-compose.yml.j2` to update the image version
2. Run the Ansible playbook again:
   ```bash
   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"`