Gogs Install: Deploy Self-Hosted Git Server on Linux | CLI

gogs install is the procedure to deploy the Gogs self-hosted Git service on Linux using a single Go binary, with minimal dependencies. The first command downloads the latest binary:

wget -O gogs.tar.gz https://github.com/gogs/gogs/releases/latest/download/gogs_linux_amd64.tar.gz

gogs install Rapid Reference Cheat Sheet

Advanced Implementation & Parameters

The custom/conf/app.ini file defines all runtime behavior. Key sections:

[server]
DOMAIN = git.example.com
ROOT_URL = https://git.example.com/
HTTP_PORT = 3000
PROTOCOL = https ; or http if behind reverse proxy

[database]
DB_TYPE = postgres
HOST = 127.0.0.1:5432
NAME = gogs
USER = gogs
PASSWORD = strong_password
SSL_MODE = disable

[security]
INSTALL_LOCK = true
SECRET_KEY = random_64_char_string
ENABLE_GZIP = true

Environment variables override config values: GOGS_DB_HOST, GOGS_SERVER_ROOT_URL, etc. For production, always set INSTALL_LOCK = true after initial setup to prevent reinstallation.

Reverse proxy configuration (Nginx)

server {
    listen 443 ssl;
    server_name git.example.com;
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Error Resolution & Troubleshooting

Common Reasons for Failure

• Database connectivity – Gogs cannot reach MySQL/PostgreSQL due to missing drivers or firewall rules.
• Port binding conflict – Default port 3000 is already in use (e.g., by another web app).
• Incorrect file permissions – The Gogs binary or data directory is owned by root instead of the git user.
• Missing system dependencies – git package, openssh-server, or systemd not installed.
• Wrong binary architecture – Downloading amd64 binary on an ARM server (e.g., Raspberry Pi).
• Reverse proxy misconfiguration – Gogs behind Nginx/Caddy without proper ROOT_URL or proxy headers.

How to Install Gogs Correctly

1. Create a system user git with no login shell:

   sudo adduser --disabled-password --gecos 'Gogs' --home /home/git --shell /bin/bash git

2. Download the latest Gogs binary (adjust architecture as needed):

   wget -O gogs_0.13.0_linux_amd64.tar.gz https://github.com/gogs/gogs/releases/download/v0.13.0/gogs_0.13.0_linux_amd64.tar.gz
   sudo tar -xzf gogs_0.13.0_linux_amd64.tar.gz -C /home/git/
   sudo chown -R git:git /home/git/gogs

3. Install required database (here SQLite is simplest):

   sudo apt install -y sqlite3

4. Switch to the git user and start the installer from the web UI:

   sudo -u git /home/git/gogs/gogs web

   Then visit http://YOUR_SERVER_IP:3000 and complete the form.

5. Register Gogs as a systemd service for persistence:

   sudo cp /home/git/gogs/scripts/systemd/gogs.service /etc/systemd/system/
   sudo systemctl enable gogs
   sudo systemctl start gogs

Common Mistakes

• Running the binary as root – Gogs will fail to write to custom/conf/app.ini. Always use sudo -u git.
• Forgetting to set ROOT_URL – Clone and WebHook URLs will be invalid. Set ROOT_URL = https://git.domain.com in the web installer.
• Using MySQL without creating the database first – Gogs does not create it automatically. Run CREATE DATABASE gogs CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;.
• Not opening port 3000 in the firewall – ufw allow 3000/tcp or firewall-cmd --add-port=3000/tcp --permanent.
• Using the wrong binary for the architecture – Verify with uname -m; on ARM64 use linux_arm64.

Production-Grade Implementation

• Least privilege user: The git user should only own /home/git/gogs. No sudo rights.
• Database with SSL: Set SSL_MODE = require for PostgreSQL and HOST = /var/run/postgresql for Unix socket if co-located.
• Automatic backups: Use pg_dump (PostgreSQL) or sqlite3 .dump (SQLite) in cron. Example:
  

  0 4 * * * pg_dump -U gogs gogs > /backups/gogs_$(date +%F).sql

• Monitoring: Expose health endpoint via /?health (Gogs >=0.12) and integrate with Prometheus/Grafana using gogs_exporter.
• Immutable config: Store app.ini in version control and deploy via Ansible. Never edit on production without testing.
• Rate limiting: Place behind Nginx with limit_req_zone to mitigate brute-force login.

wget -O gogs.tar.gz https://github.com/gogs/gogs/releases/latest/download/gogs_linux_amd64.tar.gz && tar -xzf gogs.tar.gz

go get -u gogs.io/gogs

./gogs migrate

ss -tlnp | grep 3000

sed -i 's/3000/3001/' custom/conf/app.ini

./gogs web

version: '3'
services:
  gogs:
    image: gogs/gogs
    ports:
      - "3000:3000"
    volumes:
      - /data/gogs:/data
    restart: always