From 2aa46d62f39a995d5f8ccac2b6cdcfa0bc2ead42 Mon Sep 17 00:00:00 2001 From: robojerk Date: Tue, 3 Jun 2025 15:36:45 -0700 Subject: [PATCH] docs: add comprehensive troubleshooting guide --- troubleshooting.md | 223 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 troubleshooting.md diff --git a/troubleshooting.md b/troubleshooting.md new file mode 100644 index 0000000..eadc166 --- /dev/null +++ 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/)