# 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):
   ```bash
   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

```bash
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:**
```bash
git clone git@git.opencloud.test:username/repo.git
```

**Add a remote:**
```bash
git remote add origin git@git.opencloud.test:username/repo.git
```

**Push changes:**
```bash
git push origin main
```

**Pull changes:**
```bash
git pull origin main
```

### Without SSH Config

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

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

```bash
# 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:
```bash
docker run --rm -v gitea_data:/data -v $(pwd)/backup:/backup alpine tar czf /backup/gitea_data.tar.gz -C /data .
```

To restore:
```bash
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](https://docs.gitea.io/)
- [Gitea SSH Configuration](https://docs.gitea.io/en-us/install-with-docker/#ssh-container-passthrough)