From 9f7433d4f35013492bb5066800092b73faccb44e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E1=B4=9C=C9=B4=E1=B4=8B=C9=B4=E1=B4=A1=E1=B4=8F=C9=B4?= Date: Tue, 18 Feb 2020 22:34:21 +0800 Subject: [PATCH] docs: add local development [CI SKIP] --- README.md | 1 + README_ZH.md | 1 + docs/local_development.md | 144 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 146 insertions(+) create mode 100644 docs/local_development.md diff --git a/README.md b/README.md index ff8c612af..10ba190f3 100644 --- a/README.md +++ b/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 diff --git a/README_ZH.md b/README_ZH.md index e65f9d9fa..3d1c5c73d 100644 --- a/README_ZH.md +++ b/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)配置开发环境 ## 主要特性 diff --git a/docs/local_development.md b/docs/local_development.md new file mode 100644 index 000000000..ea5e48655 --- /dev/null +++ b/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 '';" + ``` + +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 = +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 +```