# Gitea

## Overview

Gitea is the self-hosted Git platform used by Silver Solutions.

It provides:

* Git repository hosting
* Pull requests
* Issue tracking
* Wiki support
* Releases
* CI/CD integration
* Package registry support

Gitea serves as the central source control platform for SilverLinux infrastructure and application development.

---

## Service Information

### URL

```text
https://git.silveressence.net
```

### Container Name

```text
gitea
```

### Image

```text
gitea/gitea:latest
```

### Docker Networks

```text
proxy
internal
```

---

## Purpose

Gitea is used for:

* Source control
* Infrastructure repositories
* Application repositories
* Pull requests
* Issue management
* Release management
* Gitea Actions CI/CD pipelines

---

## Database

Database:

```text
gitea
```

Database Host:

```text
postgres
```

Database User:

```text
postgres
```

Current password source:

```text
POSTGRES_ROOT_PASSWORD
```

Stored in:

```text
/srv/secrets/company.env
```

Future improvement:

Create a dedicated Gitea database user and password.

---

## Email Configuration

Sender Address:

```text
noreply@silveressence.net
```

Purpose:

* Password reset emails
* Account notifications
* Repository notifications
* User invitations

SMTP configuration is loaded from:

```text
/srv/secrets/company.env
```

Variables:

```text
SMTP_HOST
SMTP_PORT
SMTP_USERNAME
SMTP_PASSWORD
```

---

## Authentication

### Current

* Local user accounts
* Email login
* Password login

### Disabled

OpenID authentication is disabled.

Reason:

OpenID is not required and increases the attack surface.

### Planned

Future authentication providers:

* Google OAuth2
* GitHub OAuth2

Purpose:

* Easier onboarding of freelancers
* Easier onboarding of external collaborators
* Reduced password management

---

## SSH Access

SSH Domain:

```text
git.silveressence.net
```

SSH Port:

```text
2222
```

Clone example:

```bash
git clone ssh://git@git.silveressence.net:2222/username/repository.git
```

---

## Data Storage

Application Data:

```text
/srv/docker/gitea/data
```

Contains:

* Repositories
* Attachments
* Configuration
* Actions data
* Package registry data
* User information

This directory is critical and must be included in backups.

---

## Gitea Actions

Gitea Actions is enabled in `app.ini` and available globally.

Status:

```text
Operational
```

### Global Runner

| Property | Value |
| --- | --- |
| Location | `/srv/docker/gitea-runner` |
| Image | `gitea/act_runner:latest` |
| Name | `silverlinux-runner` |
| Type | Global Runner |
| Status | Operational |

Labels:

* `ubuntu-latest`
* `ubuntu-24.04`
* `ubuntu-22.04`

The runner registration token is loaded from `GITEA_RUNNER_REGISTRATION_TOKEN` in `/srv/secrets/company.env`.

### Package Publishing

Silver 2.0 uses `.gitea/workflows/package.yml` to build and publish NuGet packages to BaGet. A push to `net-8-version` triggers packaging when the commit message contains `[Package]`.

The publishing credential is stored as the repository Actions secret `BAGET_API_KEY`.

---

## Secrets

Gitea and its Actions runner use infrastructure secrets stored in:

```text
/srv/secrets/company.env
```

Variables:

```text
POSTGRES_ROOT_PASSWORD

SMTP_HOST
SMTP_PORT
SMTP_USERNAME
SMTP_PASSWORD

GITEA_RUNNER_REGISTRATION_TOKEN
```

The Gitea container uses the database and SMTP variables. The Actions runner uses `GITEA_RUNNER_REGISTRATION_TOKEN`.

Future variables:

```text
GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET

GITHUB_CLIENT_ID
GITHUB_CLIENT_SECRET
```

---

## Docker Configuration

Volume Mapping:

```text
/srv/docker/gitea/data:/data
```

Port Mapping:

```text
2222:22
```

Networks:

```text
proxy
internal
```

HTTP traffic is routed through Nginx Proxy Manager.

---

## Administration

View Logs:

```bash
docker logs gitea
```

Restart Service:

```bash
docker restart gitea
```

Open Shell:

```bash
docker exec -it gitea bash
```

---

## Backup Requirements

The following items must be backed up:

### Database

```text
gitea
```

### Application Data

```text
/srv/docker/gitea/data
```

### Secrets

```text
/srv/secrets/company.env
```

Without these items, a complete restoration is not possible.

---

## Recovery Checklist

To restore Gitea:

1. Restore PostgreSQL database.
2. Restore Gitea data directory.
3. Restore company.env secrets.
4. Deploy Docker Compose stack.
5. Verify SMTP configuration.
6. Verify SSH access.
7. Verify access through Nginx Proxy Manager.

---

## Future Roadmap

### Short Term

* Enable 2FA for administrator accounts
* Configure backup automation
* Configure Google OAuth2
* Configure GitHub OAuth2

### Long Term

* Deploy applications directly from Gitea
* Expand package publishing to additional repositories

---

## Related Services

* PostgreSQL
* Nginx Proxy Manager
* OpenProject
* Portainer
* BaGet
* Gitea Actions Runner

---

## Related Documentation

* docs/server.md
* docs/security.md
* docs/secrets.md
* docs/backups.md
* postgres/README.md
* docs/cicd.md