2017-11-27 00:44:32 +03:00
---
date: "2016-12-01T16:00:00+02:00"
title: "Installation from source"
slug: "install-from-source"
2023-04-04 16:47:31 +03:00
weight: 30
2020-12-09 09:47:06 +03:00
toc: false
2017-11-27 00:44:32 +03:00
draft: false
menu:
sidebar:
parent: "installation"
name: "From source"
weight: 30
identifier: "install-from-source"
---
# Installation from source
2019-02-12 19:22:01 +03:00
You should [install go ](https://golang.org/doc/install ) and set up your go
environment correctly. In particular, it is recommended to set the `$GOPATH`
environment variable and to add the go bin directory or directories
`${GOPATH//://bin:}/bin` to the `$PATH` . See the Go wiki entry for
[GOPATH ](https://github.com/golang/go/wiki/GOPATH ).
2019-12-05 06:41:38 +03:00
Next, [install Node.js with npm ](https://nodejs.org/en/download/ ) which is
required to build the JavaScript and CSS files. The minimum supported Node.js
2020-03-06 01:36:22 +03:00
version is {{< min-node-version > }} and the latest LTS version is recommended.
2019-12-05 06:41:38 +03:00
2019-02-12 19:22:01 +03:00
**Note**: When executing make tasks that require external tools, like
`make misspell-check` , Gitea will automatically download and build these as
2019-03-10 00:15:45 +03:00
necessary. To be able to use these, you must have the `"$GOPATH/bin"` directory
2019-02-12 19:22:01 +03:00
on the executable path. If you don't add the go bin directory to the
2019-03-10 00:15:45 +03:00
executable path, you will have to manage this yourself.
2019-02-12 19:22:01 +03:00
2020-03-05 03:37:19 +03:00
**Note 2**: Go version {{< min-go-version > }} or higher is required. However, it is recommended to
2019-02-12 19:22:01 +03:00
obtain the same version as our continuous integration, see the advice given in
2023-03-23 18:18:24 +03:00
< a href = '{{< relref "doc/development/hacking-on-gitea.en-us.md" >}}' > Hacking on
2019-02-12 19:22:01 +03:00
Gitea< / a >
2017-11-27 00:44:32 +03:00
2020-12-09 09:47:06 +03:00
**Table of Contents**
2020-12-08 07:52:26 +03:00
{{< toc > }}
2017-11-27 00:44:32 +03:00
## Download
2020-01-29 05:30:02 +03:00
First, we must retrieve the source code. Since, the advent of go modules, the
2021-12-24 06:56:57 +03:00
simplest way of doing this is to use Git directly as we no longer have to have
Gitea built from within the GOPATH.
2017-11-27 00:44:32 +03:00
2019-02-12 19:22:01 +03:00
```bash
2020-01-29 05:30:02 +03:00
git clone https://github.com/go-gitea/gitea
2017-11-27 00:44:32 +03:00
```
2020-01-29 05:30:02 +03:00
(Previous versions of this document recommended using `go get` . This is
no longer necessary.)
2019-02-12 19:22:01 +03:00
Decide which version of Gitea to build and install. Currently, there are
2021-05-04 19:16:23 +03:00
multiple options to choose from. The `main` branch represents the current
development version. To build with main, skip to the [build section ](#build ).
2017-11-27 00:44:32 +03:00
2018-01-09 01:48:42 +03:00
To work with tagged releases, the following commands can be used:
2019-02-12 19:22:01 +03:00
```bash
2017-11-27 00:44:32 +03:00
git branch -a
2019-08-23 04:55:06 +03:00
git checkout v{{< version > }}
2017-11-27 00:44:32 +03:00
```
2019-02-12 19:22:01 +03:00
To validate a Pull Request, first enable the new branch (`xyz` is the PR id;
for example `2663` for [#2663 ](https://github.com/go-gitea/gitea/pull/2663 )):
2017-11-27 00:44:32 +03:00
2019-02-12 19:22:01 +03:00
```bash
2017-11-27 00:44:32 +03:00
git fetch origin pull/xyz/head:pr-xyz
```
2019-08-23 04:55:06 +03:00
To build Gitea from source at a specific tagged release (like v{{< version > }}), list the
2019-02-12 19:22:01 +03:00
available tags and check out the specific tag.
2018-01-09 01:48:42 +03:00
List available tags with the following.
2017-11-27 00:44:32 +03:00
2019-02-12 19:22:01 +03:00
```bash
2017-11-27 00:44:32 +03:00
git tag -l
2019-08-23 04:55:06 +03:00
git checkout v{{< version > }} # or git checkout pr-xyz
2017-11-27 00:44:32 +03:00
```
## Build
2019-12-05 06:41:38 +03:00
To build from source, the following programs must be present on the system:
2020-03-05 03:37:19 +03:00
- `go` {{< min-go-version > }} or higher, see [here ](https://golang.org/dl/ )
2020-03-06 01:36:22 +03:00
- `node` {{< min-node-version > }} or higher with `npm` , see [here ](https://nodejs.org/en/download/ )
2023-03-23 18:18:24 +03:00
- `make` , see [here ]({{< relref "doc/development/hacking-on-gitea.en-us.md" >}}#installing-make )
2019-12-05 06:41:38 +03:00
2021-05-04 19:16:23 +03:00
Various [make tasks ](https://github.com/go-gitea/gitea/blob/main/Makefile )
2019-02-12 19:22:01 +03:00
are provided to keep the build process as simple as possible.
2018-01-09 01:48:42 +03:00
Depending on requirements, the following build tags can be included.
2017-11-27 00:44:32 +03:00
2022-11-18 09:34:39 +03:00
- `bindata` : Build a single monolithic binary, with all assets included. Required for production build.
2020-12-09 09:47:06 +03:00
- `sqlite sqlite_unlock_notify` : Enable support for a
2019-02-12 19:22:01 +03:00
[SQLite3 ](https://sqlite.org/ ) database. Suggested only for tiny
installations.
2020-12-09 09:47:06 +03:00
- `pam` : Enable support for PAM (Linux Pluggable Authentication Modules). Can
2019-02-12 19:22:01 +03:00
be used to authenticate local users or extend authentication to methods
available to PAM.
2022-07-28 04:22:47 +03:00
- `gogit` : (EXPERIMENTAL) Use go-git variants of Git commands.
2019-02-12 19:22:01 +03:00
2022-11-18 09:34:39 +03:00
Bundling all assets (JS/CSS/templates, etc) into the binary. Using the `bindata` build tag is required for
production deployments. You could exclude `bindata` when you are developing/testing Gitea or able to separate the assets correctly.
To include all assets, use the `bindata` tag:
2019-02-12 19:22:01 +03:00
```bash
2019-12-05 06:41:38 +03:00
TAGS="bindata" make build
2019-02-12 19:22:01 +03:00
```
2017-11-27 00:44:32 +03:00
2019-03-10 00:15:45 +03:00
In the default release build of our continuous integration system, the build
2019-02-12 19:22:01 +03:00
tags are: `TAGS="bindata sqlite sqlite_unlock_notify"` . The simplest
recommended way to build from source is therefore:
2017-11-27 00:44:32 +03:00
2019-02-12 19:22:01 +03:00
```bash
2019-12-05 06:41:38 +03:00
TAGS="bindata sqlite sqlite_unlock_notify" make build
2017-11-27 00:44:32 +03:00
```
2020-02-22 12:15:11 +03:00
The `build` target is split into two sub-targets:
2020-03-05 03:37:19 +03:00
- `make backend` which requires [Go {{< min-go-version >}} ](https://golang.org/dl/ ) or greater.
2020-03-06 01:36:22 +03:00
- `make frontend` which requires [Node.js {{< min-node-version >}} ](https://nodejs.org/en/download/ ) or greater.
2020-02-22 12:15:11 +03:00
If pre-built frontend files are present it is possible to only build the backend:
```bash
TAGS="bindata" make backend
2020-02-26 21:28:39 +03:00
```
2020-02-22 12:15:11 +03:00
2017-11-27 00:44:32 +03:00
## Test
2019-03-10 00:15:45 +03:00
After following the steps above, a `gitea` binary will be available in the working directory.
2018-01-09 01:48:42 +03:00
It can be tested from this directory or moved to a directory with test data. When Gitea is
launched manually from command line, it can be killed by pressing `Ctrl + C` .
2017-11-27 00:44:32 +03:00
2019-02-12 19:22:01 +03:00
```bash
2017-11-27 00:44:32 +03:00
./gitea web
```
2019-04-29 21:08:21 +03:00
2020-08-18 14:21:24 +03:00
## Changing default paths
2019-04-29 21:08:21 +03:00
2022-11-10 04:22:31 +03:00
Gitea will search for a number of things from the _`CustomPath`_ . By default this is
2019-04-29 21:08:21 +03:00
the `custom/` directory in the current working directory when running Gitea. It will also
2022-12-14 03:20:36 +03:00
look for its configuration file _`CustomConf`_ in `$(CustomPath)/conf/app.ini` , and will use the
2022-11-10 04:22:31 +03:00
current working directory as the relative base path _`AppWorkPath`_ for a number configurable
values. Finally the static files will be served from _`StaticRootPath`_ which defaults to the _`AppWorkPath`_ .
2019-04-29 21:08:21 +03:00
These values, although useful when developing, may conflict with downstream users preferences.
One option is to use a script file to shadow the `gitea` binary and create an appropriate
environment before running Gitea. However, when building you can change these defaults
using the `LDFLAGS` environment variable for `make` . The appropriate settings are as follows
2022-11-10 04:22:31 +03:00
- To set the _`CustomPath`_ use `LDFLAGS="-X \"code.gitea.io/gitea/modules/setting.CustomPath=custom-path\""`
- For _`CustomConf`_ you should use `-X \"code.gitea.io/gitea/modules/setting.CustomConf=conf.ini\"`
- For _`AppWorkPath`_ you should use `-X \"code.gitea.io/gitea/modules/setting.AppWorkPath=working-path\"`
- For _`StaticRootPath`_ you should use `-X \"code.gitea.io/gitea/modules/setting.StaticRootPath=static-root-path\"`
2023-03-16 10:22:54 +03:00
- To change the default PID file location use `-X \"code.gitea.io/gitea/cmd.PIDFile=/run/gitea.pid\"`
2019-04-29 21:08:21 +03:00
Add as many of the strings with their preceding `-X` to the `LDFLAGS` variable and run `make build`
with the appropriate `TAGS` as above.
Running `gitea help` will allow you to review what the computed settings will be for your `gitea` .
2020-04-11 06:13:31 +03:00
## Cross Build
The `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).
To 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).
Cross-build Gitea for Linux ARM64, without any tags:
```
GOOS=linux GOARCH=arm64 make build
```
Cross-build Gitea for Linux ARM64, with recommended build tags:
```
CC=aarch64-unknown-linux-gnu-gcc GOOS=linux GOARCH=arm64 TAGS="bindata sqlite sqlite_unlock_notify" make build
```
Replace `CC` , `GOOS` , and `GOARCH` as appropriate for your architecture target.
2021-02-08 05:06:21 +03:00
You will sometimes need to build a static compiled image. To do this you will need to add:
```
LDFLAGS="-linkmode external -extldflags '-static' $LDFLAGS" TAGS="netgo osusergo $TAGS" make build
```
This can be combined with `CC` , `GOOS` , and `GOARCH` as above.
2023-02-21 20:32:24 +03:00
### Adding bash/zsh autocompletion (from 1.19)
A script to enable bash-completion can be found at [`contrib/autocompletion/bash_autocomplete` ](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete ). This should be altered as appropriate and can be `source` in your `.bashrc`
or copied as `/usr/share/bash-completion/completions/gitea` .
Similary a script for zsh-completion can be found at [`contrib/autocompletion/zsh_autocomplete` ](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete ). This can be copied to `/usr/share/zsh/_gitea` or sourced within your
`.zshrc` .
YMMV and these scripts may need further improvement.