gitea/docs/content/doc/installation/from-source.en-us.md

date	title	slug	weight	toc	draft	menu
2016-12-01T16:00:00+02:00	Installation from source	install-from-source	10	false	false	sidebar parent name weight identifier installation From source 30 install-from-source

Installation from source

You should install go 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.

Next, install Node.js with npm which is
required to build the JavaScript and CSS files. The minimum supported Node.js
version is {{< min-node-version >}} and the latest LTS version is recommended.

Note: When executing make tasks that require external tools, like
make misspell-check, Gitea will automatically download and build these as
necessary. To be able to use these, you must have the "$GOPATH/bin" directory
on the executable path. If you don't add the go bin directory to the
executable path, you will have to manage this yourself.

Note 2: Go version {{< min-go-version >}} or higher is required. However, it is recommended to
obtain the same version as our continuous integration, see the advice given in
Hacking on
Gitea

Table of Contents

{{< toc >}}

Download

First, we must retrieve the source code. Since, the advent of go modules, the
simplest way of doing this is to use Git directly as we no longer have to have
Gitea built from within the GOPATH.

git clone https://github.com/go-gitea/gitea

(Previous versions of this document recommended using go get. This is
no longer necessary.)

Decide which version of Gitea to build and install. Currently, there are
multiple options to choose from. The main branch represents the current
development version. To build with main, skip to the build section.

To work with tagged releases, the following commands can be used:

git branch -a
git checkout v{{< version >}}

To validate a Pull Request, first enable the new branch (xyz is the PR id;
for example 2663 for #2663):

git fetch origin pull/xyz/head:pr-xyz

To build Gitea from source at a specific tagged release (like v{{< version >}}), list the
available tags and check out the specific tag.

List available tags with the following.

git tag -l
git checkout v{{< version >}}  # or git checkout pr-xyz

Build

To build from source, the following programs must be present on the system:

• go {{< min-go-version >}} or higher, see here
• node {{< min-node-version >}} or higher with npm, see here
• make, see [here]({{< relref "doc/developers/hacking-on-gitea.en-us.md" >}}#installing-make)

Various make tasks
are provided to keep the build process as simple as possible.

Depending on requirements, the following build tags can be included.

• bindata: Build a single monolithic binary, with all assets included.
• sqlite sqlite_unlock_notify: Enable support for a
  SQLite3 database. Suggested only for tiny
  installations.
• pam: Enable support for PAM (Linux Pluggable Authentication Modules). Can
  be used to authenticate local users or extend authentication to methods
  available to PAM.
• gogit: (EXPERIMENTAL) Use go-git variants of Git commands.

Bundling assets into the binary using the bindata build tag is recommended for
production deployments. It is possible to serve the static assets directly via a reverse proxy,
but in most cases it is not necessary, and assets should still be bundled in the binary.
You may want to exclude bindata while developing/testing Gitea.
To include assets, add the bindata tag:

TAGS="bindata" make build

In the default release build of our continuous integration system, the build
tags are: TAGS="bindata sqlite sqlite_unlock_notify". The simplest
recommended way to build from source is therefore:

TAGS="bindata sqlite sqlite_unlock_notify" make build

The build target is split into two sub-targets:

• make backend which requires Go {{< min-go-version >}} or greater.
• make frontend which requires Node.js {{< min-node-version >}} or greater.

If pre-built frontend files are present it is possible to only build the backend:

TAGS="bindata" make backend

Test

After following the steps above, a gitea binary will be available in the working directory.
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.

./gitea web

Changing default paths

Gitea will search for a number of things from the CustomPath. By default this is
the custom/ directory in the current working directory when running Gitea. It will also
look for its configuration file CustomConf in CustomPath/conf/app.ini, and will use the 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`_.

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

• 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\"
• To change the default PID file location use -X \"code.gitea.io/gitea/modules/setting.PIDFile=/run/gitea.pid\"

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.

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 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.

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.