Browse Source

docs: add local development

[CI SKIP]
ᴜɴᴋɴᴡᴏɴ 4 years ago
parent
commit
9f7433d4f3
3 changed files with 146 additions and 0 deletions
  1. 1 0
      README.md
  2. 1 0
      README_ZH.md
  3. 144 0
      docs/local_development.md

+ 1 - 0
README.md

@@ -29,6 +29,7 @@ The Gogs (`/gɑgz/`) project aims to build a simple, stable and extensible self-
 - Want to try it before doing anything else? Do it [online](https://try.gogs.io/gogs/gogs)!
 - Having trouble? Help yourself with [troubleshooting](https://gogs.io/docs/intro/troubleshooting.html) or ask questions on [user forum](https://discuss.gogs.io/).
 - Want to help with localization? Check out the [localization documentation](https://gogs.io/docs/features/i18n.html).
+- Ready to get hands dirty? Read [our guide](docs/local_development.md) to set up your development environment.
 
 ## Features
 

+ 1 - 0
README_ZH.md

@@ -13,6 +13,7 @@ Gogs(`/gɑgz/`)项目旨在打造一个以最简便的方式搭建简单、
 - 想要先睹为快?直接去[在线体验](https://try.gogs.io/gogs/gogs)吧!
 - 使用过程中遇到问题?尝试[故障排查](https://gogs.io/docs/intro/troubleshooting.html)或者前往[用户论坛](https://discuss.gogs.io/)获取帮助
 - 希望帮助多国语言的翻译吗?请查看[本地化文档](https://gogs.io/docs/features/i18n.html)
+- 准备搞点事情?请阅读[开发指南](docs/local_development.md)配置开发环境
 
 ## 主要特性
 

+ 144 - 0
docs/local_development.md

@@ -0,0 +1,144 @@
+# 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
+```