# Local Gitea Deployment (Docker Compose)

A local, self-hosted [Gitea](https://docs.gitea.com/) instance running Gitea
**1.27.3** with a **PostgreSQL 14** database, following the official Gitea
Docker installation docs. All credentials, ports, and secrets live in the
`.env` file rather than being hardcoded in the compose file.

## Files

- `docker-compose.yml` — service definitions for Gitea + PostgreSQL
- `.env` — configuration (credentials, ports, secrets)
- `README.md` — this file

## Prerequisites

- Docker Engine with Compose v2 (`docker compose`, included in modern Docker).
  If needed, see the [Compose install instructions](https://docs.docker.com/compose/install/).

## Setup

Do the following before bringing the stack up.

### 1. Generate the security secrets

Run these two commands and paste each result into the matching empty field in
`.env` (`GITEA_SECRET_KEY` and `GITEA_INTERNAL_TOKEN`):

```
docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret SECRET_KEY
docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret INTERNAL_TOKEN
```

> **Do not change `SECRET_KEY` after the first install.** Encrypted data in the
> database cannot be decrypted if you do.

### 2. Change the database password

Replace the placeholder `POSTGRES_PASSWORD` value in `.env` with a strong password.

### 3. Match the UID/GID

The setup uses a host volume (`./gitea`), so set `USER_UID` / `USER_GID` in
`.env` to whoever owns that directory. On Linux:

```
id -u   # -> USER_UID
id -g   # -> USER_GID
```

Wrong volume permissions are the most common reason the container won't start.

## Start

```
docker compose up -d
```

Then open **http://localhost:3000** and finish setup in the browser wizard.

- If the wizard asks for the **database host**, use `db` (the service name), not `localhost`.
- **SSH** is available on host port **222**.
- Data persists in `./gitea` and `./postgres` next to the compose file.

## Common commands

```
docker compose ps        # check status
docker compose logs      # view logs
docker compose down      # stop and remove containers (volumes/data are kept)
```

## Upgrading

```
# Edit the image version in docker-compose.yml if you pin a specific release
docker compose pull      # pull new images
docker compose up -d     # recreate containers with the new images
```

> Make sure your data is volumed outside the container (it is, via `./gitea`
> and `./postgres`) before upgrading.

## Security note

Keep `.env` out of version control — it holds your secrets and database
password. Add it to `.gitignore`:

```
echo ".env" >> .gitignore
```

## Reference

- [Gitea Docs — Installation with Docker](https://docs.gitea.com/installation/install-with-docker/)
- [Gitea Docs — Managing deployments with environment variables](https://docs.gitea.com/installation/install-with-docker/#managing-deployments-with-environment-variables)