How to Self-Host Gogs with Docker Compose

What Is Gogs?

Gogs is a lightweight, self-hosted Git service written in Go. It’s one of the simplest Git hosting solutions available — a single binary that runs on minimal hardware. Gogs was the project that Gitea forked from in 2016, and while Gitea has since surpassed it in features and community size, Gogs remains a solid option for anyone who wants bare-bones Git hosting without the overhead. It replaces GitHub, GitLab, or Bitbucket for basic repository management.

Official site: gogs.io

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 512 MB of free RAM (minimum)
• 1 GB of free disk space
• A domain name (optional, for remote access)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  gogs:
    image: gogs/gogs:0.14.2
    container_name: gogs
    restart: unless-stopped
    ports:
      - "3000:3000"
      - "2222:22"
    volumes:
      - gogs_data:/data
    environment:
      - TZ=UTC
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - gogs

  postgres:
    image: postgres:16-alpine
    container_name: gogs-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: gogs
      POSTGRES_PASSWORD: change_this_strong_password
      POSTGRES_DB: gogs
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U gogs"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - gogs

volumes:
  gogs_data:
  postgres_data:

networks:
  gogs:

Important: Change POSTGRES_PASSWORD to a strong, unique password before starting.

Start the stack:

docker compose up -d

Initial Setup

1. Open http://your-server-ip:3000 in your browser
2. Gogs presents a first-run installation wizard
3. Configure the database:
   • Database Type: PostgreSQL
   • Host: postgres:5432
   • User: gogs
   • Password: the password you set in POSTGRES_PASSWORD
   • Database Name: gogs
4. Set the application URL to your domain or IP (e.g., http://git.yourdomain.com)
5. Configure the SSH port to 2222 if using the Docker port mapping above
6. Create your admin account at the bottom of the form
7. Click “Install Gogs”

Configuration

Key settings are in /data/gogs/conf/app.ini inside the container. Mount or edit this file to customize:

Setting	Default	What It Does
APP_NAME	Gogs	Name shown in the UI and page titles
RUN_MODE	dev	Set to prod for production (disables debug output)
ROOT_URL	http://localhost:3000/	Public URL — must match your domain
SSH_PORT	22	External SSH port (set to 2222 to match Docker mapping)
DISABLE_REGISTRATION	false	Set to true after creating your accounts
REQUIRE_SIGNIN_VIEW	false	Set to true to hide repos from anonymous visitors

To edit the config:

docker exec -it gogs vi /data/gogs/conf/app.ini
docker restart gogs

After creating your accounts, disable public registration:

[service]
DISABLE_REGISTRATION = true
REQUIRE_SIGNIN_VIEW  = true

Reverse Proxy

Place Gogs behind a reverse proxy for HTTPS access. Example Nginx Proxy Manager configuration:

Field	Value
Domain	git.yourdomain.com
Scheme	http
Forward Host	gogs (container name)
Forward Port	3000
SSL	Request a new certificate

Update ROOT_URL in app.ini to match your domain:

[server]
ROOT_URL = https://git.yourdomain.com/

For more reverse proxy options: Reverse Proxy Setup

Backup

Gogs data lives in two places:

What	Where	Contains
Application data	gogs_data volume	Repositories, avatars, attachments, config
Database	postgres_data volume	Users, issues, pull requests, settings

Back up the database:

docker exec gogs-db pg_dump -U gogs gogs > gogs_backup.sql

Back up the data volume:

docker run --rm -v gogs_data:/data -v $(pwd):/backup alpine \
  tar czf /backup/gogs-data-$(date +%Y%m%d).tar.gz -C /data .

For a complete backup strategy: Backup Strategy

Troubleshooting

SSH Clone Not Working

Symptom: ssh: connect to host ... port 22: Connection refused when cloning via SSH.

Fix: Gogs in Docker maps SSH to port 2222 by default. Use the SSH URL with the custom port:

git clone ssh://git@your-server:2222/username/repo.git

Also verify SSH_PORT in app.ini matches your Docker port mapping.

Database Connection Failed During Setup

Symptom: “Database connection failed” error on the install page.

Fix: Use postgres (the service name) as the database host, not localhost. Ensure the PostgreSQL container is healthy:

docker compose ps

502 Bad Gateway After Reverse Proxy Setup

Symptom: Reverse proxy returns 502 errors.

Fix: Ensure ROOT_URL in app.ini matches your public URL exactly (including https:// and trailing slash). Restart Gogs after changing the config.

Webhook Delivery Failures

Symptom: Webhooks show “delivery failed” in the repository settings.

Fix: If Gogs runs in a Docker network, it cannot reach localhost URLs on the host. Use the host’s internal IP or the container name of the target service instead.

Resource Requirements

Resource	Usage
RAM	~50-80 MB idle, ~150 MB under moderate load
CPU	Very low — single Go binary
Disk	~200 MB for the application, plus repository storage

Gogs is one of the lightest Git servers available. It runs comfortably on a Raspberry Pi.

Gogs vs Gitea vs Forgejo

Feature	Gogs	Gitea	Forgejo
Language	Go	Go	Go
RAM (idle)	~50 MB	~100 MB	~100 MB
CI/CD	No	Gitea Actions	Forgejo Actions
Package registry	No	Yes	Yes
Container registry	No	Yes	Yes
OAuth2 provider	No	Yes	Yes
Contributors	~50	~900+	~200+
Maintained by	Single developer	Community	Community (Codeberg)

Verdict: Gogs makes sense if you want the absolute lightest Git hosting with no extra features. If you need CI/CD, package registries, or a larger community, Gitea or Forgejo are better choices. Gogs hasn’t kept pace with its fork — most new deployments should start with Forgejo unless RAM is severely constrained.

Related

• Gitea: Self-Hosted Git Server
• Forgejo: Community Git Forge
• GitLab CE: Self-Hosted DevOps
• Gitea vs Gogs
• Best Self-Hosted Git Platforms
• Self-Hosted GitHub Alternatives
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy