RPJosh
/
authelia
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
authelia/docs/content/en/contributing/development/build-and-test.md

6.1 KiB
Raw Blame History

title description lead date draft images menu weight toc aliases
Building and Testing Building and Testing Authelia. This section covers the build process and how to perform tests in development. 2022-06-15T17:51:47+10:00 false
contributing
parent
development
240 true
/docs/contributing/build-and-dev.html

Authelia is built a React frontend user portal bundled in a Go application which acts as a basic webserver for the React assets and a dedicated API.

The GitHub repository comes with a CLI dedicated to developers called authelia-scripts which can be setup by looking at Reference: authelia-scripts.

In order to build and contribute to Authelia, you need to make sure that you have looked at the Environment guide to configure your development environment.

Get started

In order to ease development, Authelia uses the concept of suites to run Authelia from source code so that your patches are included. This is a kind of virtual environment running Authelia in a complete ecosystem (LDAP, Redis, SQL server). Note that Authelia is hot-reloaded in the environment so that your patches are instantly included.

The next command starts the suite called Standalone:

authelia-scripts suites setup Standalone

Most of the suites are using docker-compose to bootstrap the environment. Therefore, you can check the logs of all application by running the following command on the component you want to monitor.

docker logs authelia_authelia-backend_1 -f

Then, edit the code and observe how Authelia is automatically reloaded.

Unit tests

To run the unit tests, run:

authelia-scripts unittest

Integration tests

Integration tests are located under the internal/suites directory and are based on Selenium. A suite is a combination of environment and tests. Executing a suite therefore means starting the environment, running the tests and tearing down the environment. Each step can be run independently:

# List the available suites
$ authelia-scripts suites list
Standalone
DuoPush
LDAP
Traefik

# Start the environment of Standalone suite.
$ authelia-scripts suites setup Standalone

# Run the tests related to the currently running suite.
$ authelia-scripts suites test

# Tear down the environment
$ authelia-scripts suites teardown Standalone

In order to test all suites (approx 30 minutes), you need to make sure there is no currently running sui te and then you should run:

authelia-scripts suites test

Also, you don't need to start the suite before testing it. Given you're not running any suite, just use the following command to test the Standalone suite.

authelia-scripts suites test Standalone

The suite will be spawned, tests will be run and then the suite will be torn down automatically.

Manually Building

Binary

If you want to manually build the binary from source you will require the open source software described in the Development Environment documentation. Then you can follow the below steps on Linux (you may have to adapt them on other systems).

Basic Steps

Clone the Repository:

git clone https://github.com/authelia/authelia.git

Download the Dependencies:

cd authelia && go mod download
cd web && pnpm install
cd ..

Build the Web Frontend:

cd web && pnpm build
cd ..

Build the Binary (with debug symbols):

CGO_ENABLED=1 CGO_CPPFLAGS="-D_FORTIFY_SOURCE=2 -fstack-protector-strong" CGO_LDFLAGS="-Wl,-z,relro,-z,now" \
go build -ldflags "-linkmode=external" -trimpath -buildmode=pie -o authelia ./cmd/authelia

Build the Binary (without debug symbols):

CGO_ENABLED=1 CGO_CPPFLAGS="-D_FORTIFY_SOURCE=2 -fstack-protector-strong" CGO_LDFLAGS="-Wl,-z,relro,-z,now" \
go build -ldflags "-linkmode=external -s -w" -trimpath -buildmode=pie -o authelia ./cmd/authelia

Reproducible Builds

Authelia allows production of reproducible builds that were built using our pipeline. The only variables injected into a build are from commit information other than the exceptions listed in this section. This means that we can provide the exact build commands for any given build with very limited input from users. The elements injected into the binary as part of the build process (using linker flags) are:

  • Commit SHA1
  • Commit Date (using the RFC1123 layout strictly using the UTC timezone)
  • Latest Tag
  • Tag State (i.e. if the HEAD commit has the latest tag)
  • Working Tree State (dirty, clean, etc)
  • Branch Name
  • Build Number

The exceptions of this list which cannot be obtained from commit information (but can be supplied by an environment variable or CLI argument):

  • Build Number
Instructions

To perform a reproducible build users should follow these steps:

  1. Run the authelia build-info command which contains useful information for reproducing the build including:
    1. The Build Number field.
    2. The Build Go Version field.
  2. Install all of the required dependencies. It's recommended if you're looking for a reproducible build that you use the same Go version from step 1.
  3. Run the following command from the root of the repository to output the build commands (where 100 is the number from step 1):
go run ./cmd/authelia-scripts build --print --build-number 100

The output of the above command may be ran to perform all of the build steps manually.

Important Note: If you wish to use gox to build Authelia please run the go run ./cmd/authelia-scripts build --print --buildkite --build-number 100 command instead of the above command (i.e. adding the --buildkite flag).