forgejo-ssh-script/troubleshooting.md

Forgejo SSH Troubleshooting Guide

Overview

This guide covers common issues and solutions when setting up SSH access to Forgejo, particularly in a Docker-based deployment.

Environment Setup

Server Side

• Forgejo running in Docker container
• SSH port mapped from container port 22 to host port 222
• Direct SSH access (not through proxy)
• Git clone URL format: ssh://git@your-domain:222/username/repo.git

Client Side

• Windows 11 Pro
• OpenSSH client
• PowerShell 7+
• Git for Windows

Common Issues and Solutions

1. SSH Key Authentication

Symptoms

• "Permission denied (publickey)" errors
• Repeated passphrase prompts
• Failed Git operations

Solutions

1. Verify SSH Key Setup

   # Check if key exists
   ls ~/.ssh/id_ed25519
   
   # Generate new key if needed
   ssh-keygen -t ed25519 -C "your@email.com"
   

2. Add Key to Forgejo

   • Copy public key content
   • Add to Forgejo web interface (Settings > SSH Keys)
   • Verify key using challenge token

3. Configure SSH Agent

   # Start SSH agent
   Start-Service ssh-agent
   
   # Set to start automatically
   Set-Service -Name ssh-agent -StartupType Automatic
   
   # Add key to agent
   ssh-add ~/.ssh/id_ed25519
   
   # Verify key is loaded
   ssh-add -l
   

2. SSH Connection Issues

Symptoms

• Connection timeouts
• Port access denied
• Authentication failures

Solutions

1. Verify Port Access

   # Test port connection
   Test-NetConnection -ComputerName your-domain -Port 222
   

2. Check SSH Config

   # View SSH config
   cat ~/.ssh/config
   
   # Example config
   Host your-domain
       HostName your-domain
       Port 222
       User your-username
       IdentityFile ~/.ssh/id_ed25519
       PreferredAuthentications publickey
   

3. Test SSH Connection

   # Basic test
   ssh -T git@your-domain -p 222
   
   # Verbose test
   ssh -vvv -T git@your-domain -p 222
   

3. Git Configuration

Symptoms

• Git operations fail
• Wrong SSH implementation used
• Authentication issues

Solutions

1. Configure Git SSH Command

   # Check current setting
   git config --get core.sshCommand
   
   # Set to Windows SSH
   git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"
   

2. Verify Repository URL

   # Check remote URL
   git remote -v
   
   # Update if needed
   git remote set-url origin ssh://git@your-domain:222/username/repo.git
   

4. Docker-Specific Issues

Symptoms

• Container SSH service not responding
• Port mapping issues
• Container configuration problems

Solutions

1. Check Container Status

   # Verify container is running
   docker ps | grep forgejo
   
   # Check container logs
   docker compose logs | grep ssh
   

2. Verify Port Mapping

   # Check port mappings
   docker port forgejo
   

3. Check SSH Service

   # Verify SSH service is running
   docker exec forgejo ps aux | grep sshd
   

Best Practices

SSH Key Management

1. Use ED25519 keys for better security
2. Always use a passphrase
3. Add keys to SSH agent for persistence
4. Regularly rotate keys

Git Configuration

1. Use consistent SSH implementation
2. Configure Git to use system SSH
3. Use correct repository URL format
4. Keep Git and SSH clients updated

Docker Setup

1. Use proper port mappings
2. Configure container for SSH access
3. Monitor container logs
4. Regular container updates

Troubleshooting Steps

1. Basic Checks

1. Verify SSH key exists and is loaded
2. Check SSH agent is running
3. Confirm port 222 is accessible
4. Verify Git configuration

2. Connection Testing

1. Test basic SSH connection
2. Check verbose SSH output
3. Verify port connectivity
4. Test Git operations

3. Server Verification

1. Check container status
2. Verify SSH service
3. Check container logs
4. Verify port mappings

4. Client Configuration

1. Verify SSH config
2. Check Git settings
3. Test SSH agent
4. Verify key permissions

Common Error Messages

"Permission denied (publickey)"

• Key not added to Forgejo
• Wrong key being used
• SSH agent not running
• Key not loaded in agent

"Connection refused"

• Port 222 not accessible
• Container not running
• Firewall blocking access
• Wrong port mapping

"Host key verification failed"

• Known hosts file issue
• Server key changed
• Wrong host configuration

Prevention Tips

1. Document all configurations
2. Use consistent naming
3. Regular security updates
4. Monitor system logs
5. Backup SSH keys
6. Test after changes

Additional Resources

• Forgejo Documentation
• OpenSSH Documentation
• Git Documentation
• Docker Documentation