# Getting started with developing Gogs

> This document is driven from https://docs.sourcegraph.com/dev/local_development.

Gogs is developed in [Go](https://golang.org/), please take [A Tour of Go](https://tour.golang.org/) if you haven't done so!

## Outline

- [Environment](#environment)
- [Step 1: Install dependencies](#step-1-install-dependencies)
- [Step 2: Initialize your database](#step-2-initialize-your-database)
- [Step 3: Get the code](#step-3-get-the-code)
- [Step 4: Configure database settings](#step-4-configure-database-settings)
- [Step 5: Start the server](#step-5-start-the-server)
- [Other nice things](#other-nice-things)

## Environment

Gogs is built and runs as a single binary and meant to be cross platform. Therefore, you should be able to develop Gogs in any major platforms you prefer.

## Step 1: Install dependencies

Gogs has the following dependencies:

- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) (v1.8.3 or higher)
- [Go](https://golang.org/doc/install) (v1.11 or higher)
- [GNU Make](https://www.gnu.org/software/make/)
- Database upon your choice (pick one, we choose PostgreSQL in this document):
    - [PostgreSQL](https://wiki.postgresql.org/wiki/Detailed_installation_guides) (v9.6 or higher)
    - [MySQL](https://dev.mysql.com/downloads/mysql/) with `ENGINE=InnoDB` (v5.7 or higher)
    - [SQLite3](https://www.sqlite.org/index.html)
    - [MSSQL](https://en.wikipedia.org/wiki/Microsoft_SQL_Server) (SQL Server 2005 or newer)
    - [TiDB](https://github.com/pingcap/tidb)

### macOS

1. Install [Homebrew](https://brew.sh/).
2. Install dependencies:

    ```bash
    brew install go postgresql git go-bindata
    ```

3. Configure PostgreSQL to start automatically:

    ```bash
    brew services start postgresql
    ```

### Ubuntu

1. Update repositories:

    ```bash
    sudo apt-get update
    ```

2. Install dependencies:

    ```bash
    sudo apt install -y make git-all postgresql postgresql-contrib golang-go
    go get -u github.com/kevinburke/go-bindata/...
    ```

3. Configure startup services:

    ```bash
    sudo systemctl enable postgresql
    ```

4.  Ensure `psql`, the PostgreSQL command line client, is on your `$PATH`.
    Homebrew does not put it there by default. Homebrew gives you the command to run to insert `psql` in your path in the "Caveats" section of `brew info postgresql`. Alternatively, you can use the command below. It might need to be adjusted depending on your Homebrew prefix (`/usr/local` below) and shell (bash below).

    ```bash
    hash psql || { echo 'export PATH="/usr/local/opt/postgresql/bin:$PATH"' >> ~/.bash_profile }
    source ~/.bash_profile
    ```

## Step 2: Initialize your database

You need a fresh Postgres database and a database user that has full ownership of that database.

1. Create a database for the current Unix user:

    ```bash
    # For Linux users, first access the postgres user shell
    sudo su - postgres
    ```

    ```bash
    createdb
    ```

2. Create the Gogs user and password:

    ```bash
    createuser --superuser gogs
    psql -c "ALTER USER gogs WITH PASSWORD '<YOUR PASSWORD HERE>';"
    ```

3. Create the Gogs database

    ```bash
    createdb --owner=gogs --encoding=UTF8 --template=template0 gogs
    ```

## Step 3: Get the code

Generally, you don't need a full clone, so set `--depth` to `10`:

```bash
git clone --depth 10 https://github.com/gogs/gogs.git
```

## Step 4: Configure database settings

Create a `custom/conf/app.ini` file inside the repository and put the following configuration (everything under `custom/` directory is used to override default files and is excluded by `.gitignore`):

```ini
[database]
DB_TYPE = postgres
HOST = 127.0.0.1:5432
NAME = gogs
USER = gogs
PASSWD = <YOUR PASSWORD HERE>
SSL_MODE = disable
```

## Step 5: Start the server

```bash
make web
```

## Other nice things

### Offline development

Sometimes you will want to develop Gogs but it just so happens you will be on a plane or a train or perhaps a beach, and you will have no WiFi. And you may raise your fist toward heaven and say something like, "Why, we can put a man on the moon, so why can't we develop high-quality Git hosting without an Internet connection?" But lower your hand back to your keyboard and fret no further, for the year is 2020, and you *can* develop Gogs with no connectivity by setting the following configuration in your `custom/conf/app.ini`:

```ini
[server]
OFFLINE_MODE = true
```