selfhost-cloud-compose-stack/version-control

Gitea Version Control

This directory contains the Docker Compose configuration for Gitea, a self-hosted Git service.

Overview

Gitea is configured with:

• PostgreSQL database backend
• SSH access on port 2222
• HTTPS access via Traefik reverse proxy
• Persistent data storage

SSH Access

Gitea SSH is accessible on port 2222 (mapped from container port 22) to avoid conflicts with the host SSH service.

Prerequisites

1. Generate an SSH key (if you don't have one):

   ssh-keygen -t ed25519 -C "your_email@example.com"
   

2. Add your public key to Gitea:

   • Go to https://git.opencloud.test (or your configured domain)
   • Log in to your account
   • Click your avatar (top right) → Settings
   • Go to SSH / GPG Keys tab
   • Click Add Key
   • Paste your public key (found in ~/.ssh/id_ed25519.pub)
   • Give it a descriptive name
   • Click Add Key

SSH Configuration

To use Git with the standard SSH syntax (without specifying port 2222 each time), add this to your ~/.ssh/config:

Host git.opencloud.test
    Port 2222
    User git
    IdentityFile ~/.ssh/id_ed25519

Replace IdentityFile with the path to your private key if different.

Test SSH Connection

ssh -T git@git.opencloud.test

You should see:

Hi there, <username>! You've successfully authenticated with the key named <key-name>,
but Gitea does not provide shell access.

Using Git with SSH

Once SSH is configured, you can use standard Git commands:

Clone a repository:

git clone git@git.opencloud.test:username/repo.git

Add a remote:

git remote add origin git@git.opencloud.test:username/repo.git

Push changes:

git push origin main

Pull changes:

git pull origin main

Without SSH Config

If you prefer not to modify your SSH config, you can specify the port in the URL:

# Clone
git clone ssh://git@git.opencloud.test:2222/username/repo.git

# Add remote
git remote add origin ssh://git@git.opencloud.test:2222/username/repo.git

# Or test connection
ssh -T -p 2222 git@git.opencloud.test

HTTPS Access

Gitea web interface is available at:

• Local development: https://git.opencloud.test
• Production: https://your-configured-domain

You can also clone repositories via HTTPS if SSH is not available:

git clone https://git.opencloud.test/username/repo.git

Configuration

Key environment variables (configured in .env):

Variable	Description	Default
GITEA_HOST	Domain for Gitea	git.opencloud.test
GITEA_DB	Database name	giteadb
GITEA_DB_USER	Database user	giteauser
GITEA_DB_PASSWORD	Database password	giteapass

Troubleshooting

SSH Connection Refused

If you get "Connection refused":

1. Check that the Gitea container is running: docker ps | grep gitea
2. Verify port mapping: docker ps -f name=gitea --format "{{.Ports}}"
3. Should show: 0.0.0.0:2222->22/tcp

Permission Denied (publickey)

If you get "Permission denied (publickey)":

1. Ensure you've added your SSH public key to your Gitea account
2. Verify the correct key is being used:

   ssh -vT git@git.opencloud.test
   

3. Check your ~/.ssh/config points to the correct IdentityFile

Wrong Port in Git URLs

If you created repositories before configuring SSH, you may need to update the remote URL:

# Check current remote
git remote -v

# Update to use correct format
git remote set-url origin git@git.opencloud.test:username/repo.git

Data Persistence

Gitea data is stored in the Docker volume gitea_data, which includes:

• Git repositories
• SQLite database (if not using PostgreSQL)
• Configuration files
• Avatars and attachments

To backup:

docker run --rm -v gitea_data:/data -v $(pwd)/backup:/backup alpine tar czf /backup/gitea_data.tar.gz -C /data .

To restore:

docker run --rm -v gitea_data:/data -v $(pwd)/backup:/backup alpine tar xzf /backup/gitea_data.tar.gz -C /data

Additional Resources

• Gitea Documentation
• Gitea SSH Configuration