171 lines
4.5 KiB
Markdown
171 lines
4.5 KiB
Markdown
# 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
|
|
|
|
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:
|
|
|
|
```bash
|
|
ssh -i ~/.ssh/id_rsa debian@VM_IP_ADDRESS "sudo /opt/forgejo/scripts/update-forgejo.sh"
|
|
```
|
|
|
|
To view update logs:
|
|
|
|
```bash
|
|
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:
|
|
```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"`
|