96 lines
2.8 KiB
Markdown
96 lines
2.8 KiB
Markdown
# 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)
|