some more gitea
This commit is contained in:
343
scripts/GITEA_SSH_SETUP.md
Normal file
343
scripts/GITEA_SSH_SETUP.md
Normal file
@@ -0,0 +1,343 @@
|
||||
# Gitea SSH Setup Guide
|
||||
|
||||
This guide explains how to configure Gitea to use your system's SSH server on port 22 instead of running its own SSH server on port 2222.
|
||||
|
||||
## Overview
|
||||
|
||||
By default, Gitea runs its own SSH server on port 2222 to avoid conflicts with the system SSH server. However, you can configure it to use the system SSH daemon on port 22, which provides:
|
||||
|
||||
- **Single SSH Port**: No need to remember port 2222
|
||||
- **Standard Git URLs**: Use standard `git@host:repo.git` format
|
||||
- **Centralized SSH Management**: All SSH traffic through system sshd
|
||||
- **Better Integration**: Works seamlessly with existing SSH infrastructure
|
||||
|
||||
## Quick Setup (Automated)
|
||||
|
||||
Use the provided script to configure everything automatically:
|
||||
|
||||
```bash
|
||||
# Run as the gitea user (mleku)
|
||||
./scripts/gitea-ssh-setup.sh
|
||||
```
|
||||
|
||||
The script will:
|
||||
- Configure Gitea to use system SSH
|
||||
- Update `app.ini` with correct SSH settings
|
||||
- Back up your existing configuration
|
||||
- Display next steps
|
||||
|
||||
## Manual Setup
|
||||
|
||||
If you prefer to configure manually, follow these steps:
|
||||
|
||||
### Step 1: Update Gitea Configuration
|
||||
|
||||
Edit `/home/mleku/gitea/custom/conf/app.ini` and update the `[server]` section:
|
||||
|
||||
```ini
|
||||
[server]
|
||||
# ... other settings ...
|
||||
|
||||
# Disable Gitea's built-in SSH server
|
||||
START_SSH_SERVER = false
|
||||
|
||||
# SSH domain (use your server's hostname or IP)
|
||||
SSH_DOMAIN = your-server.com
|
||||
|
||||
# SSH port (system SSH port)
|
||||
SSH_PORT = 22
|
||||
|
||||
# Don't disable SSH protocol support
|
||||
DISABLE_SSH = false
|
||||
```
|
||||
|
||||
### Step 2: Restart Gitea
|
||||
|
||||
```bash
|
||||
sudo systemctl restart gitea
|
||||
```
|
||||
|
||||
### Step 3: Verify Configuration
|
||||
|
||||
Check that Gitea is no longer listening on port 2222:
|
||||
|
||||
```bash
|
||||
# Should not show Gitea on port 2222
|
||||
sudo netstat -tlnp | grep 2222
|
||||
|
||||
# System SSH should be on port 22
|
||||
sudo netstat -tlnp | grep :22
|
||||
```
|
||||
|
||||
## Adding SSH Keys to Gitea
|
||||
|
||||
Once configured, users need to add their SSH public keys to Gitea:
|
||||
|
||||
### Generate SSH Key (if needed)
|
||||
|
||||
```bash
|
||||
# Generate a new ED25519 key (recommended)
|
||||
ssh-keygen -t ed25519 -C "your-email@example.com"
|
||||
|
||||
# Or generate RSA key (older systems)
|
||||
ssh-keygen -t rsa -b 4096 -C "your-email@example.com"
|
||||
```
|
||||
|
||||
### Add Key to Gitea
|
||||
|
||||
1. **Copy your public key:**
|
||||
```bash
|
||||
cat ~/.ssh/id_ed25519.pub
|
||||
# or
|
||||
cat ~/.ssh/id_rsa.pub
|
||||
```
|
||||
|
||||
2. **Add to Gitea:**
|
||||
- Log in to Gitea web interface
|
||||
- Click your avatar → **Settings**
|
||||
- Navigate to **SSH / GPG Keys**
|
||||
- Click **Add Key**
|
||||
- Paste your public key
|
||||
- Give it a name (e.g., "My Laptop")
|
||||
- Click **Add Key**
|
||||
|
||||
### Test SSH Connection
|
||||
|
||||
```bash
|
||||
# Test SSH authentication
|
||||
ssh -T git@your-server.com
|
||||
|
||||
# Expected output:
|
||||
# Hi there, username! You've successfully authenticated, but Gitea does not provide shell access.
|
||||
```
|
||||
|
||||
## Using SSH with Git
|
||||
|
||||
Once SSH is configured and your key is added, you can use standard Git SSH URLs:
|
||||
|
||||
### Clone Repository
|
||||
|
||||
```bash
|
||||
# Standard SSH URL format
|
||||
git clone git@your-server.com:username/repo-name.git
|
||||
|
||||
# Example
|
||||
git clone git@your-server.com:mleku/orly.git
|
||||
```
|
||||
|
||||
### Add Remote to Existing Repository
|
||||
|
||||
```bash
|
||||
cd /path/to/your/repo
|
||||
git remote add origin git@your-server.com:mleku/repo-name.git
|
||||
```
|
||||
|
||||
### Push/Pull
|
||||
|
||||
```bash
|
||||
git push origin main
|
||||
git pull origin main
|
||||
```
|
||||
|
||||
## Update Migration Script for SSH
|
||||
|
||||
If you want to use SSH for repository migration instead of HTTP, update the environment:
|
||||
|
||||
```bash
|
||||
# Don't set VPS_HOST - SSH will use standard port 22
|
||||
export GITEA_TOKEN="your-token"
|
||||
export GITEA_URL="http://your-server:3000" # Still needed for API
|
||||
|
||||
# Update migration script to use SSH
|
||||
# (You would need to modify the script to support this)
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Permission denied (publickey)"
|
||||
|
||||
**Problem**: SSH key not added or not being used
|
||||
|
||||
**Solutions**:
|
||||
1. Verify key is added to Gitea: Settings → SSH/GPG Keys
|
||||
2. Ensure SSH agent has your key:
|
||||
```bash
|
||||
ssh-add -l
|
||||
ssh-add ~/.ssh/id_ed25519 # Add if not listed
|
||||
```
|
||||
3. Test with verbose output:
|
||||
```bash
|
||||
ssh -vvv -T git@your-server.com
|
||||
```
|
||||
|
||||
### "Could not resolve hostname"
|
||||
|
||||
**Problem**: DNS or hostname issue
|
||||
|
||||
**Solutions**:
|
||||
1. Use IP address instead:
|
||||
```bash
|
||||
git clone git@192.168.1.100:mleku/repo.git
|
||||
```
|
||||
2. Add entry to `/etc/hosts`:
|
||||
```
|
||||
192.168.1.100 your-server.com
|
||||
```
|
||||
|
||||
### SSH Uses Wrong Port
|
||||
|
||||
**Problem**: Git trying to use port 2222
|
||||
|
||||
**Solutions**:
|
||||
1. Verify `app.ini` has `SSH_PORT = 22`
|
||||
2. Restart Gitea: `sudo systemctl restart gitea`
|
||||
3. Check repository remote URL:
|
||||
```bash
|
||||
git remote -v
|
||||
# Should show: git@host:user/repo.git (not port 2222)
|
||||
```
|
||||
|
||||
### Gitea Still Listening on Port 2222
|
||||
|
||||
**Problem**: Built-in SSH server still running
|
||||
|
||||
**Solutions**:
|
||||
1. Verify `START_SSH_SERVER = false` in `app.ini`
|
||||
2. Restart Gitea: `sudo systemctl restart gitea`
|
||||
3. Check logs: `sudo journalctl -u gitea -f`
|
||||
|
||||
## SSH Configuration Files
|
||||
|
||||
### Gitea Configuration
|
||||
|
||||
Location: `/home/mleku/gitea/custom/conf/app.ini`
|
||||
|
||||
Relevant settings:
|
||||
```ini
|
||||
[server]
|
||||
START_SSH_SERVER = false # Don't run built-in SSH
|
||||
SSH_DOMAIN = localhost
|
||||
SSH_PORT = 22 # System SSH port
|
||||
DISABLE_SSH = false # Allow SSH protocol
|
||||
```
|
||||
|
||||
### System SSH Configuration
|
||||
|
||||
Location: `/etc/ssh/sshd_config`
|
||||
|
||||
No changes needed - Gitea works with standard SSH configuration.
|
||||
|
||||
## Advanced: SSH Config File
|
||||
|
||||
For convenience, add an SSH config entry:
|
||||
|
||||
Create/edit `~/.ssh/config`:
|
||||
|
||||
```
|
||||
Host gitea
|
||||
HostName your-server.com
|
||||
User git
|
||||
Port 22
|
||||
IdentityFile ~/.ssh/id_ed25519
|
||||
|
||||
Host gitea-vpn
|
||||
HostName 10.0.0.1
|
||||
User git
|
||||
Port 22
|
||||
IdentityFile ~/.ssh/id_ed25519
|
||||
```
|
||||
|
||||
Usage:
|
||||
```bash
|
||||
# Clone using SSH alias
|
||||
git clone gitea:mleku/repo.git
|
||||
|
||||
# Or VPN alias
|
||||
git clone gitea-vpn:mleku/repo.git
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### SSH Key Best Practices
|
||||
|
||||
1. **Use ED25519 keys** (modern, secure, fast)
|
||||
2. **Protect private keys** with passphrase
|
||||
3. **Use different keys** for different servers
|
||||
4. **Rotate keys** periodically
|
||||
5. **Remove old keys** from Gitea when no longer needed
|
||||
|
||||
### Firewall Configuration
|
||||
|
||||
Ensure port 22 is accessible:
|
||||
|
||||
```bash
|
||||
# UFW
|
||||
sudo ufw allow 22/tcp
|
||||
|
||||
# iptables
|
||||
sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT
|
||||
```
|
||||
|
||||
### Restrict SSH Access
|
||||
|
||||
In `/etc/ssh/sshd_config`:
|
||||
|
||||
```
|
||||
# Only allow specific users
|
||||
AllowUsers mleku git
|
||||
|
||||
# Disable password authentication (keys only)
|
||||
PasswordAuthentication no
|
||||
PubkeyAuthentication yes
|
||||
|
||||
# Disable root login
|
||||
PermitRootLogin no
|
||||
```
|
||||
|
||||
Restart SSH:
|
||||
```bash
|
||||
sudo systemctl restart sshd
|
||||
```
|
||||
|
||||
## Comparison: Built-in vs System SSH
|
||||
|
||||
| Feature | Built-in SSH (Port 2222) | System SSH (Port 22) |
|
||||
|---------|--------------------------|----------------------|
|
||||
| Port | 2222 | 22 |
|
||||
| Configuration | Gitea-managed | System sshd |
|
||||
| URLs | `git@host:2222/user/repo.git` | `git@host:user/repo.git` |
|
||||
| Setup | Automatic | Requires configuration |
|
||||
| Isolation | Separate from system | Shared with system |
|
||||
| Management | Via Gitea | Via sshd config |
|
||||
|
||||
## Migration: 2222 → 22
|
||||
|
||||
If you already have repositories using port 2222, update them:
|
||||
|
||||
```bash
|
||||
# Update single repository
|
||||
cd /path/to/repo
|
||||
git remote set-url origin git@your-server.com:mleku/repo.git
|
||||
|
||||
# Bulk update script
|
||||
for repo in ~/Documents/github/*/; do
|
||||
cd "$repo"
|
||||
if git remote get-url origin | grep -q ":2222/"; then
|
||||
new_url=$(git remote get-url origin | sed 's/:2222\//:/g')
|
||||
git remote set-url origin "$new_url"
|
||||
echo "Updated: $(basename $repo)"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
## Summary
|
||||
|
||||
Using system SSH with Gitea provides a cleaner, more standard Git experience:
|
||||
|
||||
✅ Standard SSH port (22)
|
||||
✅ Standard Git URLs (`git@host:user/repo.git`)
|
||||
✅ Centralized SSH management
|
||||
✅ Works with existing SSH infrastructure
|
||||
✅ No special port forwarding needed
|
||||
|
||||
The trade-off is slightly more complex initial setup compared to using Gitea's built-in SSH server.
|
||||
Reference in New Issue
Block a user