173 lines
4.2 KiB
Markdown
173 lines
4.2 KiB
Markdown
# 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)
|