1--- 2date: "2016-12-01T16:00:00+02:00" 3title: "Installation from source" 4slug: "install-from-source" 5weight: 10 6toc: false 7draft: false 8menu: 9 sidebar: 10 parent: "installation" 11 name: "From source" 12 weight: 30 13 identifier: "install-from-source" 14--- 15 16# Installation from source 17 18You should [install go](https://golang.org/doc/install) and set up your go 19environment correctly. In particular, it is recommended to set the `$GOPATH` 20environment variable and to add the go bin directory or directories 21`${GOPATH//://bin:}/bin` to the `$PATH`. See the Go wiki entry for 22[GOPATH](https://github.com/golang/go/wiki/GOPATH). 23 24Next, [install Node.js with npm](https://nodejs.org/en/download/) which is 25required to build the JavaScript and CSS files. The minimum supported Node.js 26version is {{< min-node-version >}} and the latest LTS version is recommended. 27 28**Note**: When executing make tasks that require external tools, like 29`make misspell-check`, Gitea will automatically download and build these as 30necessary. To be able to use these, you must have the `"$GOPATH/bin"` directory 31on the executable path. If you don't add the go bin directory to the 32executable path, you will have to manage this yourself. 33 34**Note 2**: Go version {{< min-go-version >}} or higher is required. However, it is recommended to 35obtain the same version as our continuous integration, see the advice given in 36<a href='{{< relref "doc/developers/hacking-on-gitea.en-us.md" >}}'>Hacking on 37Gitea</a> 38 39**Table of Contents** 40 41{{< toc >}} 42 43## Download 44 45First, we must retrieve the source code. Since, the advent of go modules, the 46simplest way of doing this is to use Git directly as we no longer have to have 47Gitea built from within the GOPATH. 48 49```bash 50git clone https://github.com/go-gitea/gitea 51``` 52 53(Previous versions of this document recommended using `go get`. This is 54no longer necessary.) 55 56Decide which version of Gitea to build and install. Currently, there are 57multiple options to choose from. The `main` branch represents the current 58development version. To build with main, skip to the [build section](#build). 59 60To work with tagged releases, the following commands can be used: 61 62```bash 63git branch -a 64git checkout v{{< version >}} 65``` 66 67To validate a Pull Request, first enable the new branch (`xyz` is the PR id; 68for example `2663` for [#2663](https://github.com/go-gitea/gitea/pull/2663)): 69 70```bash 71git fetch origin pull/xyz/head:pr-xyz 72``` 73 74To build Gitea from source at a specific tagged release (like v{{< version >}}), list the 75available tags and check out the specific tag. 76 77List available tags with the following. 78 79```bash 80git tag -l 81git checkout v{{< version >}} # or git checkout pr-xyz 82``` 83 84## Build 85 86To build from source, the following programs must be present on the system: 87 88- `go` {{< min-go-version >}} or higher, see [here](https://golang.org/dl/) 89- `node` {{< min-node-version >}} or higher with `npm`, see [here](https://nodejs.org/en/download/) 90- `make`, see <a href='{{< relref "doc/developers/hacking-on-gitea.en-us.md" >}}#installing-make'>here</a> 91 92Various [make tasks](https://github.com/go-gitea/gitea/blob/main/Makefile) 93are provided to keep the build process as simple as possible. 94 95Depending on requirements, the following build tags can be included. 96 97- `bindata`: Build a single monolithic binary, with all assets included. 98- `sqlite sqlite_unlock_notify`: Enable support for a 99 [SQLite3](https://sqlite.org/) database. Suggested only for tiny 100 installations. 101- `pam`: Enable support for PAM (Linux Pluggable Authentication Modules). Can 102 be used to authenticate local users or extend authentication to methods 103 available to PAM. 104* `gogit`: (EXPERIMENTAL) Use go-git variants of Git commands. 105 106Bundling assets into the binary using the `bindata` build tag is recommended for 107production deployments. It is possible to serve the static assets directly via a reverse proxy, 108but in most cases it is not necessary, and assets should still be bundled in the binary. 109You may want to exclude bindata while developing/testing Gitea. 110To include assets, add the `bindata` tag: 111 112```bash 113TAGS="bindata" make build 114``` 115 116In the default release build of our continuous integration system, the build 117tags are: `TAGS="bindata sqlite sqlite_unlock_notify"`. The simplest 118recommended way to build from source is therefore: 119 120```bash 121TAGS="bindata sqlite sqlite_unlock_notify" make build 122``` 123 124The `build` target is split into two sub-targets: 125 126- `make backend` which requires [Go {{< min-go-version >}}](https://golang.org/dl/) or greater. 127- `make frontend` which requires [Node.js {{< min-node-version >}}](https://nodejs.org/en/download/) or greater. 128 129If pre-built frontend files are present it is possible to only build the backend: 130 131```bash 132TAGS="bindata" make backend 133``` 134 135## Test 136 137After following the steps above, a `gitea` binary will be available in the working directory. 138It can be tested from this directory or moved to a directory with test data. When Gitea is 139launched manually from command line, it can be killed by pressing `Ctrl + C`. 140 141```bash 142./gitea web 143``` 144 145## Changing default paths 146 147Gitea will search for a number of things from the `CustomPath`. By default this is 148the `custom/` directory in the current working directory when running Gitea. It will also 149look for its configuration file `CustomConf` in `$CustomPath/conf/app.ini`, and will use the 150current working directory as the relative base path `AppWorkPath` for a number configurable 151values. Finally the static files will be served from `StaticRootPath` which defaults to the `AppWorkPath`. 152 153These values, although useful when developing, may conflict with downstream users preferences. 154 155One option is to use a script file to shadow the `gitea` binary and create an appropriate 156environment before running Gitea. However, when building you can change these defaults 157using the `LDFLAGS` environment variable for `make`. The appropriate settings are as follows 158 159- To set the `CustomPath` use `LDFLAGS="-X \"code.gitea.io/gitea/modules/setting.CustomPath=custom-path\""` 160- For `CustomConf` you should use `-X \"code.gitea.io/gitea/modules/setting.CustomConf=conf.ini\"` 161- For `AppWorkPath` you should use `-X \"code.gitea.io/gitea/modules/setting.AppWorkPath=working-path\"` 162- For `StaticRootPath` you should use `-X \"code.gitea.io/gitea/modules/setting.StaticRootPath=static-root-path\"` 163- To change the default PID file location use `-X \"code.gitea.io/gitea/modules/setting.PIDFile=/run/gitea.pid\"` 164 165Add as many of the strings with their preceding `-X` to the `LDFLAGS` variable and run `make build` 166with the appropriate `TAGS` as above. 167 168Running `gitea help` will allow you to review what the computed settings will be for your `gitea`. 169 170## Cross Build 171 172The `go` compiler toolchain supports cross-compiling to different architecture targets that are supported by the toolchain. See [`GOOS` and `GOARCH` environment variable](https://golang.org/doc/install/source#environment) for the list of supported targets. Cross compilation is helpful if you want to build Gitea for less-powerful systems (such as Raspberry Pi). 173 174To cross build Gitea with build tags (`TAGS`), you also need a C cross compiler which targets the same architecture as selected by the `GOOS` and `GOARCH` variables. For example, to cross build for Linux ARM64 (`GOOS=linux` and `GOARCH=arm64`), you need the `aarch64-unknown-linux-gnu-gcc` cross compiler. This is required because Gitea build tags uses `cgo`'s foreign-function interface (FFI). 175 176Cross-build Gitea for Linux ARM64, without any tags: 177 178``` 179GOOS=linux GOARCH=arm64 make build 180``` 181 182Cross-build Gitea for Linux ARM64, with recommended build tags: 183 184``` 185CC=aarch64-unknown-linux-gnu-gcc GOOS=linux GOARCH=arm64 TAGS="bindata sqlite sqlite_unlock_notify" make build 186``` 187 188Replace `CC`, `GOOS`, and `GOARCH` as appropriate for your architecture target. 189 190You will sometimes need to build a static compiled image. To do this you will need to add: 191 192``` 193LDFLAGS="-linkmode external -extldflags '-static' $LDFLAGS" TAGS="netgo osusergo $TAGS" make build 194``` 195 196This can be combined with `CC`, `GOOS`, and `GOARCH` as above. 197