192 lines
6.1 KiB
Markdown
192 lines
6.1 KiB
Markdown
---
|
|
title: "Building and Testing"
|
|
description: "Building and Testing Authelia."
|
|
lead: "This section covers the build process and how to perform tests in development."
|
|
date: 2022-06-15T17:51:47+10:00
|
|
draft: false
|
|
images: []
|
|
menu:
|
|
contributing:
|
|
parent: "development"
|
|
weight: 240
|
|
toc: true
|
|
aliases:
|
|
- /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](reference-authelia-scripts.md) which can be setup by looking at
|
|
[Reference: authelia-scripts](reference-authelia-scripts.md).
|
|
|
|
In order to build and contribute to __Authelia__, you need to make sure that you have looked at the
|
|
[Environment](environment.md) 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*:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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](./environment.md#setup) documentation. Then you can follow the below steps on Linux (you may
|
|
have to adapt them on other systems).
|
|
|
|
#### Basic Steps
|
|
|
|
Clone the Repository:
|
|
|
|
```bash
|
|
git clone https://github.com/authelia/authelia.git
|
|
```
|
|
|
|
Download the Dependencies:
|
|
|
|
```bash
|
|
cd authelia && go mod download
|
|
cd web && pnpm install
|
|
cd ..
|
|
```
|
|
|
|
Build the Web Frontend:
|
|
|
|
```bash
|
|
cd web && pnpm build
|
|
cd ..
|
|
```
|
|
|
|
Build the Binary (with debug symbols):
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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](https://gitihub.com/authelia/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).*
|
|
|
|
[suites]: ./integration-suites.md
|
|
[React]: https://reactjs.org/
|
|
[go]: https://go.dev/dl/
|
|
[Node.js]: https://nodejs.org/en/download/
|
|
[Docker]: https://docs.docker.com/get-docker/
|
|
[Docker Compose]: https://docs.docker.com/compose/install/
|
|
[golangci-lint]: https://golangci-lint.run/usage/install/
|
|
[goimports-reviser]: https://github.com/incu6us/goimports-reviser#install
|