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 18 and the latest LTS version is recommended.
Go version 1.22 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
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 release/v1.22
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 v1.22.4), list the available tags and check out the specific tag.
List available tags with the following.
git tag -l
git checkout v1.22.4 # or git checkout pr-xyz
Build
To build from source, the following programs must be present on the system:
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. Required for production build.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 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:
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 1.22 or greater.make frontend
which requires Node.js 18 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
useLDFLAGS="-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/cmd.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.
Adding bash/zsh autocompletion (from 1.19)
A script to enable bash-completion can be found at 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
.
Similarly, a script for zsh-completion can be found at 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.
Compile or cross-compile using Linux with Zig
Follow Getting Started of Zig to install zig.
- Compile (Linux ➝ Linux)
CC="zig cc -target x86_64-linux-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
CGO_LDFLAGS="-linkmode=external -v"
GOOS=linux \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
- Cross-compile (Linux ➝ Windows)
CC="zig cc -target x86_64-windows-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
GOOS=windows \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
Compile or cross-compile with Zig using Windows
Compile with GIT BASH
.
- Compile (Windows ➝ Windows)
CC="zig cc -target x86_64-windows-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
GOOS=windows \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
- Cross-compile (Windows ➝ Linux)
CC="zig cc -target x86_64-linux-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
CGO_LDFLAGS="-linkmode=external -v"
GOOS=linux \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
Source Maps
By default, gitea generates reduced source maps for frontend files to conserve space. This can be controlled with the ENABLE_SOURCEMAP
environment variable:
ENABLE_SOURCEMAP=true
generates all source maps, the default for development buildsENABLE_SOURCEMAP=reduced
generates limited source maps, the default for production buildsENABLE_SOURCEMAP=false
generates no source maps