docs: add comprehensive troubleshooting guide

2025-06-03 15:36:45 -07:00 · 2025-06-03 15:36:45 -07:00 · 2aa46d62f3
commit 2aa46d62f3
parent 0ecdeadfd5
1 changed files with 223 additions and 0 deletions
--- a/troubleshooting.md
+++ b/troubleshooting.md
@ -0,0 +1,223 @@
+# 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/)