Gitea adds repository browsing, user permissions and Pull Requests to a shared Git service. Run it with PostgreSQL in a separate Docker Compose project. Complete initial setup through the administrator PC before deciding how the team will reach the service.
The target is separate Linux lab VM with Docker Engine and Compose plugins ready. Docker is not installed simply by installing the Git client of Rocky or Ubuntu. You can use Docker Desktop’s Linux container environment on Windows, but installing Docker itself and verifying its execution on Windows is outside the scope of this article.
Git · GitOps All Series · 15 / 24
On this page
1. Determine the version and permanent data location
Confirmed Gitea 28.1.0 in official release on October 18, 2026. DB uses PostgreSQL 17 series. The Gitea image specifies the release number, and the DB fixes the major version to avoid unintended major transitions. Before operation, check again for security notices and supported versions at the time of use.
mkdir -p ~/git-server-lab
cd ~/git-server-lab
docker version
docker compose version
umask 077
printf 'GITEA_DB_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .envThe created .env contains the actual secret value. Do not commit or attach to shared materials. To avoid losing the value, store it with restricted access to the server recovery archive. Docker command permissions are effectively tied to elevated privileges on the host, so manage your account carefully.
2. Save the Compose file
Save the following contents to compose.yaml. Because we use a named volume, persistent data remains in the Docker volume even if you don’t see DB files under the current directory. Be careful not to forget this path and leave it out of the backup.
name: maruops-git-lab
services:
gitea:
image: docker.gitea.com/gitea:28.1.0
restart: unless-stopped
environment:
USER_UID: '1000'
USER_GID: '1000'
GITEA__database__DB_TYPE: postgres
GITEA__database__HOST: db:5432
GITEA__database__NAME: gitea
GITEA__database__USER: gitea
GITEA__database__PASSWD: ${GITEA_DB_PASSWORD:?Set GITEA_DB_PASSWORD}
GITEA__server__DOMAIN: localhost
GITEA__server__ROOT_URL: http://localhost:13000/
GITEA__server__SSH_DOMAIN: localhost
GITEA__server__SSH_PORT: '12222'
GITEA__service__DISABLE_REGISTRATION: 'true'
ports:
- '127.0.0.1:13000:3000'
- '127.0.0.1:12222:22'
volumes:
- gitea-data:/data
depends_on:
db:
condition: service_healthy
db:
image: postgres:17
restart: unless-stopped
environment:
POSTGRES_DB: gitea
POSTGRES_USER: gitea
POSTGRES_PASSWORD: ${GITEA_DB_PASSWORD:?Set GITEA_DB_PASSWORD}
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U gitea -d gitea']
interval: 5s
timeout: 5s
retries: 20
volumes:
- postgres-data:/var/lib/postgresql/data
volumes:
gitea-data:
postgres-data:For the host, use 13000 and 12222, and within the container, connect to 3000 and 22, respectively. The VM’s SSH management port and Gitea’s SSH port have different purposes. DB’s 5432 port is not exposed to the host.
3. Get started and create an initial administrator
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=80 giteaconfig --quiet checks for missing grammar and variables. docker compose config If the entire output is shared externally, the secret values of environment variables may be exposed. Check the status to see if the DB is healthy, and open http://localhost:13000/ in your browser.
If you ran it in a VM, localhost on your PC is not that VM. Open an SSH tunnel on your PC and connect. If you also plan to use Git SSH, forward both ports together.
ssh -N -L 13000:127.0.0.1:13000 -L 12222:127.0.0.1:12222 labadmin@192.168.56.40The DB host on the installation screen is db:5432, and the DB/user name is gitea. In the Create administrator account section, specify the actual administrator and unique password. Retain the subscription disable setting and complete the installation. The app URL uses the tunnel connection address http://localhost:13000/ in this step.
4. Create an empty repository and upload the code
It’s a good idea to use a regular work account separate from the administrator to check permissions. Register your public key in your account’s SSH key settings and create an empty repository named gitops-demo. Enter your account name in YOUR_USER below.
cd ~/git-lab/gitops-demo
git remote add gitea ssh://git@localhost:12222/YOUR_USER/gitops-demo.git
git push gitea mainCheck the server host key fingerprint first. If you see commits and files on the web screen, storage transfer and inquiry have been connected. For PR practice, you can try pushing a feature branch and opening a request targeting main.
What changes when you reveal it to the team
127.0.0.1 binding does not accept external connections. When switching to Teams, bind to trusted addresses and configure HTTPS reverse proxy, internal DNS, and firewall permissions together. ROOT_URL, DOMAIN, SSH_DOMAIN, and SSH_PORT must match the address where the user actually connects.
localhost in a container or Kubernetes Pod does not point to a Gitea VM. Before connecting Jenkins and Argo CD, you must be able to access the actual address from the execution location. Rather than turning off TLS verification, set the correct CA and server name.
Shutdown proceeds with docker compose down and the volume remains. down -v can erase persistent volumes, so it is not habitually attached to the cleanup command. The criteria for configuration are Gitea Docker Installation and Database Preparation Guide.
Previous · [Git and GitOps 14] Build a Local Git Server with Bare Repositories and SSH · Next · [Git and GitOps 16] Back Up and Restore Gitea Beyond the Repository Files · Series list and example files
.jpg){kind=link}