Skip to main content

​
Prerequisites

  1. Gogs requires use of one of the following database backends:
    • MySQL, >= 5.7
    • MariaDB, >= 10.3
    • PostgreSQL, >= 9.6
    • SQLite 3
  2. Git, >= 1.8.3, on both server and client side
  3. SSH server
    • Only required when enable Git over SSH, e.g., git clone git@gogs.example.com:...
    • Builtin SSH server is also available
For Windows users:
  • When using builtin SSH server, you still need to have ssh-keygen installed and available via the %PATH% environment variable.
  • Use OpenSSH on Windows 10 or newer.
  • Cygwin OpenSSH or Copssh are available on older versions of Windows.

​
Initialize database

If you choose to use MySQL, MariaDB or PostgreSQL as your database backend, you need to first complete the initial database creation.
Create a database user and database:
psql -c "CREATE USER gogs WITH PASSWORD '{YOUR_PASSWORD}';"
psql -c "CREATE DATABASE gogs OWNER gogs ENCODING 'UTF8';"

​
Installation methods

All release archives containing pre-built binaries are available in dl.gogs.io and GitHub releases.
For Windows users:Release archives containing mws come with built-in Windows service support. If you prefer to manage the service using NSSM, download the standard version instead.
Once extracted the archive, run gogs web to start the server. Use gogs web --help to see all available options.

​
Configuration

Gogs requires a custom/conf/app.ini before it can start, which overlays the shipped defaults, so it only needs the keys you actually want to change. For example, pointing Gogs at a local PostgreSQL database and serving it at https://gogs.example.com: 
RUN_MODE = prod

[server]
EXTERNAL_URL = https://gogs.example.com/
DOMAIN       = gogs.example.com

[database]
TYPE     = postgres
HOST     = 127.0.0.1:5432
NAME     = gogs
USER     = gogs
PASSWORD = ${GOGS_DATABASE_PASSWORD}

[security]
SECRET_KEY = ${GOGS_SECURITY_SECRET_KEY}
SECRET_KEY can be any unguessable string, e.g., a UUID from uuidgenerator.net. Gogs refuses to start while it is still using the unsafe default.
${...} references in any value expand from the process environment at startup, which keeps secrets out of app.ini on disk. Export them from the shell that launches gogs web, or under a service manager use the equivalent (e.g., systemd Environment= directives). Plain literal values work too, e.g., PASSWORD = hunter2.
By default, the custom/ directory is expected to sit next to the gogs binary. To put it elsewhere, set the GOGS_CUSTOM environment variable, e.g., GOGS_CUSTOM=/etc/gogs. See configuration primer to learn more about how the configuration system works. Whoever signs up while there are no other users becomes the admin. Alternatively, the admin user can be created from the command line. The command must run on the same server as Gogs because it connects to the database directly and reads the same custom/conf/app.ini: 
gogs admin create-user \
  --name admin \
  --password ${PASSWORD} \
  --email admin@example.com \
  --admin \
  --config custom/conf/app.ini