Skip to main content
[ PIER ]

Gitea with PostgreSQL

Production Gitea — wired to PostgreSQL out of the box.

Service #git#repository#postgresql#devops#code

Gitea (the lightweight self-hosted Git service) paired with a dedicated PostgreSQL backend for production use. Gitea defaults to SQLite which is fine for small teams; PostgreSQL is the recommended backend once you cross a handful of concurrent users, want HA backups, or run Gitea Actions at any volume.

Deploy with Pier

  1. 1 Open the Pier dashboard and click Add service.
  2. 2 Pick Gitea with PostgreSQL from the template list.
  3. 3 Choose the version, set a service name, and Pier provisions the container, storage, and ports automatically.
  4. 4 Attach a domain if you want HTTPS. Traefik auto-provisions the Let's Encrypt certificate.

What is Gitea with PostgreSQL?

Gitea is a lightweight, self-hosted Git service — repos, issues, PRs, code review, releases, package registries, Gitea Actions (GitHub Actions-compatible CI). It defaults to SQLite for simplicity, but Postgres is the recommended backend once you have multiple active users, high webhook volume, or you run Gitea Actions at any volume.

This template runs Gitea plus a dedicated PostgreSQL in one Pier stack with the env wiring already correct. You log in and use Gitea exactly as you would on the standalone template — code, issues, PRs, packages — the backend just performs better under concurrent load.

How Pier deploys it

Pier uses the official gitea/gitea image and postgres:17-alpine for the backend. Default ports — Gitea web on 3000, Gitea SSH on 22 (remapped to a high external port like 222). PostgreSQL stays on the internal Docker network (not exposed).

Persistent volumes — /data for Gitea (repos, uploads, config) and /var/lib/postgresql/data for Postgres. Both survive container restarts and version upgrades.

First-time setup is the standard Gitea install screen on first visit: choose database (pre-filled to point at the bundled Postgres), set admin user, save. Attach a custom domain in Pier for HTTPS via Traefik.

When NOT to use this template

For 1-3 users and small repo counts, the standalone Gitea (SQLite) template is simpler. For full DevOps platforms (Wiki, Pages, Container Registry built-in, advanced security scanning), GitLab CE is more feature-complete but much heavier on resources. For community-governed governance, Forgejo is a Gitea fork worth considering. This template is the right answer for “production Gitea on my own VPS.”

Key features

Production-ready Gitea

Web Git hosting, issues, PRs, code review, releases, packages, Actions — all of Gitea, wired to Postgres for concurrent-write reliability.

Pre-wired DB config

Pier sets the Gitea database type to postgres, plus host/db/user/password env vars. Gitea boots straight into Postgres on first launch.

Same Gitea UI

Repositories, issues, PRs, mirrors, actions, package registries (npm/pypi/maven/docker/...), webhooks, SSH access — all identical to standalone Gitea.

Gitea Actions

Built-in CI/CD compatible with GitHub Actions syntax. Runs in a sandbox per repo; runners are deployed separately.

Backup via PostgreSQL

pg_dump captures the entire Gitea state. Plus the repos volume. Cleaner backup story than SQLite's "stop the world and copy."

Multi-tenant friendly

Organizations, teams, fine-grained ACLs scale comfortably with Postgres. SSO via OAuth2/OIDC/LDAP/SAML.

Use cases

Self-hosted GitHub for a team

A team of 5-500 using Gitea daily for code review, issues, releases. PostgreSQL handles the concurrent issue/PR write load smoothly.

Production internal Git + CI

Add Gitea Actions runners, point CI at PRs, ship to your own registry — all on your VPS, no GitHub Actions minute bills.

Public OSS hosting

Some projects host public repos on their own Gitea instead of GitHub. Postgres handles the visibility/concurrent-read load.

Mirror of GitHub / GitLab

Auto-pull mirrors of upstream repos into your Gitea for offline access or backup. Webhook-driven, no manual sync.

Package registry hub

Internal npm / PyPI / Maven / Docker / Helm registry alongside Git repos. One auth surface, one backup target.

Code examples

Clone over SSH bash 
# SSH port is exposed by Pier (default 222 → maps to internal 22)
git clone ssh://[email protected]:222/alice/myrepo.git
Create a Gitea Action workflow yaml 
# .gitea/workflows/build.yml
name: build
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: go test ./...
Mirror a GitHub repo text 
Migration page in UI:
  Type: Mirror
  URL: https://github.com/orgs/orgname/repo
  Auth: PAT (if private)
  Interval: 1h
Push a Docker image to Gitea's registry bash 
docker login gitea.example.com -u alice -p $PAT
docker tag myapp gitea.example.com/alice/myapp:1.0
docker push gitea.example.com/alice/myapp:1.0

How it compares

vs Gitea with SQLite (standalone template) SQLite Gitea is fine for 1-3 users and small repo counts. Postgres-backed Gitea is the recommended setup once you have concurrent writes, want HA, or run Actions at any volume.
vs GitLab CE GitLab is more powerful (full DevOps platform) but heavyweight (8 GB RAM realistic minimum). Gitea is lightweight (~500 MB RAM); choose by available resources.
vs Forgejo Forgejo is a hard fork of Gitea governed by the community (Codeberg). Same feature set, mostly drop-in compatible. Pick based on preferred governance.
vs GitHub Enterprise SaaS or self-hosted, enterprise pricing. Gitea is the open alternative at zero per-seat cost.

Frequently asked questions

Why PostgreSQL over SQLite?
Under concurrent writes (issue comments, PR updates, webhooks, Actions runs), SQLite becomes the bottleneck. PostgreSQL handles thousands of concurrent connections cleanly.
Can I migrate from SQLite Gitea?
Yes — Gitea ships a `gitea dump` / `gitea migrate` flow. Run dump on SQLite Gitea, deploy the Postgres template, restore the dump pointing at Postgres.
Do I need a separate runner for Gitea Actions?
Yes — act_runner runs as a separate container/binary that connects to Gitea and executes workflows. Pier doesn't bundle it (yet); deploy a runner manually.
SSH access?
Pier exposes SSH on a high port (e.g. 222). Configure your `git remote` to use that port, or set up SSH config aliases.
How does the package registry work?
Gitea's registry supports npm, PyPI, Maven, Composer, NuGet, Cargo, RubyGems, Docker, Helm, container, Conan, generic. Authenticate with personal access tokens.
Backups?
`gitea dump` plus pg_dump of the Postgres backend covers everything. Plus the data volume which contains repos + uploaded files.
SSO / LDAP / SAML?
Yes — all configured in Site Administration → Authentication Sources. Gitea supports OAuth2, OIDC, LDAP, SAML, and basic auth.

Related services

Deploy on your VPS

Gitea (the lightweight self-hosted Git service) paired with a dedicated PostgreSQL backend for production use. Gitea defaults to SQLite which is fine for small teams; PostgreSQL is the recommended backend once you cross a handful of concurrent users, want HA backups, or run Gitea Actions at any volume.

Deploy this service →