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**
   ```powershell
   # 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**
   ```powershell
   # 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**
   ```powershell
   # Test port connection
   Test-NetConnection -ComputerName your-domain -Port 222
   ```

2. **Check SSH Config**
   ```powershell
   # 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**
   ```powershell
   # 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**
   ```powershell
   # 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**
   ```powershell
   # 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**
   ```bash
   # Verify container is running
   docker ps | grep forgejo
   
   # Check container logs
   docker compose logs | grep ssh
   ```

2. **Verify Port Mapping**
   ```bash
   # Check port mappings
   docker port forgejo
   ```

3. **Check SSH Service**
   ```bash
   # 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](https://forgejo.org/docs/)
- [OpenSSH Documentation](https://www.openssh.com/manual.html)
- [Git Documentation](https://git-scm.com/doc)
- [Docker Documentation](https://docs.docker.com/)