diff --git a/developer/from-source.md b/developer/from-source.md new file mode 100644 index 00000000..824468ca --- /dev/null +++ b/developer/from-source.md @@ -0,0 +1,118 @@ +--- +layout: '~/layouts/Markdown.astro' +title: 'Compiling from source' +license: 'Apache-2.0' +origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/installation/from-source.en-us.md' +--- + +# Installation from source + +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). + +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 +version is 16 and the latest LTS version is recommended. + +**Note**: When executing make tasks that require external tools, like +`make misspell-check`, Forgejo 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 1.20 or higher is required. However, it is recommended to +obtain the same version as our continuous integration, see the advice given in +[Hacking on Forgejo]({{< relref "doc/development/hacking-on-forgejo.en-us.md" >}}) + +## 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 +Forgejo built from within the GOPATH. + +```bash +git clone https://codeberg.org/forgejo/forgejo +``` + +Decide which version of Forgejo to build and install. Currently, there are +multiple options to choose from. The `forgejo` branch represents the current +development version. + +To work with tagged releases, the following commands can be used: + +```bash +git branch -a +git checkout v1.20.0-5 +``` + +To build Forgejo from source at a specific tagged release (like v1.20.0-5), list the +available tags and check out the specific tag. + +List available tags with the following. + +```bash +git tag -l +git checkout v1.20.0-5 +``` + +## Build + +To build from source, the following programs must be present on the system: + +- `go` v1.20 or higher, see [here](https://golang.org/dl/) +- `node` 16 or higher with `npm`, see [here](https://nodejs.org/en/download/) +- `make` + +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](https://sqlite.org/) database. Suggested only for small + 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. + +Using the `bindata` build tag is required for production +deployments. You could exclude `bindata` when you are +developing/testing Forgejo or able to separate the assets correctly. + +To include all assets, use the `bindata` tag: + +```bash +TAGS="bindata" make build +``` + +In the default release build of the continuous integration system, the build +tags are: `TAGS="bindata sqlite sqlite_unlock_notify"`. The simplest +recommended way to build from source is therefore: + +```bash +TAGS="bindata sqlite sqlite_unlock_notify" make build +``` + +The `build` target is split into two sub-targets: + +- `make backend` which requires [Go v1.20](https://golang.org/dl/) or greater. +- `make frontend` which requires [Node.js 16](https://nodejs.org/en/download/) or greater. + +If pre-built frontend files are present it is possible to only build the backend: + +```bash +TAGS="bindata" make backend +``` + +Webpack source maps are by default enabled in development builds and disabled in production builds. They can be enabled by setting the `ENABLE_SOURCEMAP=true` environment variable. + +## Test + +After following the steps above, a `forgejo` binary will be available in the working directory. +It can be tested from this directory or moved to a directory with test data. When Forgejo is +launched manually from command line, it can be killed by pressing `Ctrl + C`. + +```bash +./forgejo web +``` diff --git a/developer/index.md b/developer/index.md index 33c703f3..c0f3c49b 100644 --- a/developer/index.md +++ b/developer/index.md @@ -12,6 +12,7 @@ their needs. - [Governance](GOVERNANCE) - [Sustainability and funding](https://codeberg.org/forgejo/sustainability/src/branch/master/README) - For contributors + - [Compiling from source](from-source) - [Developer Certificate of Origin (DCO)](DCO) - [Development workflow](WORKFLOW) - [code.forgejo.org](code-forgejo-org)