Add README.md
This commit is contained in:
@@ -0,0 +1,158 @@
|
||||
# Uzik's Gitea Server
|
||||
|
||||
Self-hosted Git service running [Gitea](https://gitea.com/) via Docker Compose with a PostgreSQL backend.
|
||||
|
||||
---
|
||||
|
||||
## Repository Contents
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `docker-compose.yml` | Defines the `gitea` and `db` (PostgreSQL 14) services |
|
||||
| `app.ini` | Gitea application configuration (production mode) |
|
||||
|
||||
---
|
||||
|
||||
## Stack
|
||||
|
||||
- **Gitea** - latest image from `docker.gitea.com/gitea`
|
||||
- **PostgreSQL 14** - database backend
|
||||
- **LFS** - Git Large File Storage enabled
|
||||
- **Mailer** - SMTP integration enabled
|
||||
- **SSH** - External port `222` forwarded to internal port `22`
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker + Docker Compose installed on the host
|
||||
- A domain name or static IP for `DOMAIN` / `ROOT_URL`
|
||||
- An SMTP server for mailer/registration email support
|
||||
- A reverse proxy (e.g. Nginx Proxy Manager, Caddy, Traefik) terminating HTTPS in front of port `3000`
|
||||
|
||||
---
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Clone / copy this repo onto your server
|
||||
|
||||
```bash
|
||||
git clone <this-repo-url> gitea
|
||||
cd gitea
|
||||
```
|
||||
|
||||
### 2. Set passwords in `docker-compose.yml`
|
||||
|
||||
Replace both placeholder values with the same strong password:
|
||||
|
||||
```yaml
|
||||
- GITEA__database__PASSWD=<set_a_password> # in the gitea service
|
||||
- POSTGRES_PASSWORD=<password_from_above> # in the db service
|
||||
```
|
||||
|
||||
### 3. Configure `app.ini`
|
||||
|
||||
Fill in every `<placeholder>` before first run:
|
||||
|
||||
| Placeholder | Where | Description |
|
||||
|-------------|-------|-------------|
|
||||
| `<your_fqdn_or_IP>` | `[server]` | Public domain or IP (used in 3 fields) |
|
||||
| `<smtp_mail_server_IP_or_FQDN>` | `[mailer]` | Your SMTP server address |
|
||||
| `<from mailer address>` | `[mailer]` | Display address for outgoing mail |
|
||||
| `<sending mailer address>` | `[mailer]` | Auth username for SMTP |
|
||||
| `<'*' for all or IP of your reverse proxy>` | `[security]` | Trusted proxy IP(s) |
|
||||
|
||||
> Secrets (`LFS_JWT_SECRET`, `INTERNAL_TOKEN`, `PASSWD`, `JWT_SECRET`, `SECRET_KEY`) are already populated in the running instance and shown as `<redacted>` in this file. **Do not commit real secrets to version control.**
|
||||
|
||||
### 4. Start the stack
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Gitea will be available at `http://<host>:3000` (or via your reverse proxy at the configured `ROOT_URL`).
|
||||
|
||||
---
|
||||
|
||||
## Ports
|
||||
|
||||
| Port (Host) | Port (Container) | Protocol | Service |
|
||||
|-------------|------------------|----------|---------|
|
||||
| `3000` | `3000` | HTTP | Gitea web UI |
|
||||
| `222` | `22` | SSH | Git over SSH |
|
||||
|
||||
> SSH clone URLs will use port 222: `ssh://git@<domain>:222/<user>/<repo>.git`
|
||||
|
||||
---
|
||||
|
||||
## Persistent Data
|
||||
|
||||
| Host Path | Container Path | Contents |
|
||||
|-----------|----------------|----------|
|
||||
| `./gitea` | `/data` | Gitea repos, config, avatars, LFS, logs |
|
||||
| `./postgres` | `/var/lib/postgresql/data` | PostgreSQL data directory |
|
||||
|
||||
Both directories are created automatically on first run.
|
||||
|
||||
---
|
||||
|
||||
## Notable Configuration
|
||||
|
||||
- **Registration** - disabled by default (`DISABLE_REGISTRATION = true`). Set to `false` to allow public sign-ups.
|
||||
- **Email confirmation** - required for new accounts (`REGISTER_EMAIL_CONFIRM = true`).
|
||||
- **Email privacy** - user email addresses hidden by default (`DEFAULT_KEEP_EMAIL_PRIVATE = true`).
|
||||
- **OpenID / OAuth external login** - disabled.
|
||||
- **CAPTCHA** - enabled on registration.
|
||||
- **Secure cookies** - `COOKIE_SECURE` and `COOKIE_HTTPONLY` both enabled; requires HTTPS.
|
||||
- **Reverse proxy** - `REVERSE_PROXY_LIMIT = 2`; set `REVERSE_PROXY_TRUSTED_PROXIES` to your proxy's IP.
|
||||
- **Landing page** - redirects unauthenticated visitors to the login page.
|
||||
|
||||
---
|
||||
|
||||
## Updating Gitea
|
||||
|
||||
```bash
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
PostgreSQL data and Gitea data persist in the local bind-mount directories.
|
||||
|
||||
---
|
||||
|
||||
## Backups
|
||||
|
||||
Recommended backup targets:
|
||||
|
||||
```
|
||||
./gitea/ # all repos, LFS objects, attachments, avatars
|
||||
./postgres/ # database files (or use pg_dump for a portable SQL backup)
|
||||
```
|
||||
|
||||
For a consistent database dump:
|
||||
|
||||
```bash
|
||||
docker exec gitea-db pg_dump -U gitea gitea > gitea_backup_$(date +%F).sql
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Container won't start / DB connection refused**
|
||||
Make sure both `GITEA__database__PASSWD` and `POSTGRES_PASSWORD` are set to the same value before first run.
|
||||
|
||||
**SSH not working**
|
||||
Ensure port `222` is open in your firewall. Clone with `ssh://git@<domain>:222/...` or configure `~/.ssh/config`:
|
||||
```
|
||||
Host <domain>
|
||||
Port 222
|
||||
```
|
||||
|
||||
**Emails not sending**
|
||||
Check `[mailer]` values in `app.ini` and confirm your SMTP server allows connections from this host on port `587`.
|
||||
|
||||
**Logs**
|
||||
```bash
|
||||
docker logs gitea -f
|
||||
```
|
||||
Reference in New Issue
Block a user