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