> ## Documentation Index
> Fetch the complete documentation index at: https://gogs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Get your own Git service up and running in minutes

## 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

<Note>
  **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](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse) on Windows 10 or newer.
  * [Cygwin OpenSSH](http://docs.oracle.com/cd/E24628_01/install.121/e22624/preinstall_req_cygwin_ssh.htm) or [Copssh](https://www.itefix.net/copssh) are available on older versions of Windows.
</Note>

## Initialize database

If you choose to use MySQL, MariaDB or PostgreSQL as your database backend, you need to first complete the initial database creation.

<Tabs>
  <Tab title="PostgreSQL">
    Create a database user and database:

    ```bash theme={null}
    psql -c "CREATE USER gogs WITH PASSWORD '{YOUR_PASSWORD}';"
    psql -c "CREATE DATABASE gogs OWNER gogs ENCODING 'UTF8';"
    ```
  </Tab>

  <Tab title="MySQL / MariaDB">
    Use the [bundled script](https://github.com/gogs/gogs/blob/main/scripts/mysql.sql) to create the database with proper encoding. The script detects MariaDB and applies the appropriate InnoDB settings for older releases automatically:

    ```zsh theme={null}
    mysql -u root -p < scripts/mysql.sql
    ```

    In `app.ini`, set `[database] TYPE = mysql` for both MySQL and MariaDB. Gogs talks to MariaDB through the MySQL wire protocol.
  </Tab>
</Tabs>

## Installation methods

<Tabs>
  <Tab title="Pre-built binary">
    All release archives containing pre-built binaries are available in [dl.gogs.io](https://dl.gogs.io) and [GitHub releases](https://github.com/gogs/gogs/releases).

    <Note>
      **For Windows users:**

      Release archives containing `mws` come with built-in Windows service support. If you prefer to manage the service using [NSSM](https://nssm.cc), download the standard version instead.
    </Note>

    Once extracted the archive, run `gogs web` to start the server. Use `gogs web --help` to see all available options.
  </Tab>

  <Tab title="Docker">
    Two types of Docker images are provided:

    1. [docker-next](https://github.com/gogs/gogs/blob/main/docker-next/README.md): The modern, non-root, and cloud-native version, but with no container options.
    2. [docker](https://github.com/gogs/gogs/blob/main/docker/README.md): The traditional, root-privileged version, with extensive container options.
  </Tab>

  <Tab title="Packages">
    <Warning>
      All packages listed below are packaged by third-party maintainers. Use at your own risk.
    </Warning>

    | Source                                                                  | Description     | Note                                                                                                   |
    | ----------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------ |
    | Arch User Repository ([link](https://aur.archlinux.org/packages/gogs/)) | Stable releases | Detailed instructions available in the [Arch Linux Wiki entry](https://wiki.archlinux.org/title/Gogs). |
  </Tab>
</Tabs>

## 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`:

```ini theme={null}
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](https://www.uuidgenerator.net). Gogs refuses to start while it is still using the unsafe default.

<Note>
  `${...}` 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`.
</Note>

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](/fine-tuning/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`:

```zsh theme={null}
gogs admin create-user \
  --name admin \
  --password ${PASSWORD} \
  --email admin@example.com \
  --admin \
  --config custom/conf/app.ini
```