Local Gitea Deployment (Docker Compose)

A local, self-hosted Gitea 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.

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

2.8 KiB Raw Blame History