next.orly.dev/scripts/GITEA_SSH_SETUP.md

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:

# 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:

[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

sudo systemctl restart gitea

Step 3: Verify Configuration

Check that Gitea is no longer listening on port 2222:

# 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)

# 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:

   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

# 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

# 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

cd /path/to/your/repo
git remote add origin git@your-server.com:mleku/repo-name.git

Push/Pull

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:

# 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:

   ssh-add -l
   ssh-add ~/.ssh/id_ed25519  # Add if not listed
   

3. Test with verbose output:

   ssh -vvv -T git@your-server.com
   

"Could not resolve hostname"

Problem: DNS or hostname issue

Solutions:

1. Use IP address instead:

   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:

   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:

[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:

# 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:

# 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:

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:

# 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.