From 2ba7b757c8cc436b4e09d2c5f3e1e59f873fe856 Mon Sep 17 00:00:00 2001 From: James Elliott Date: Mon, 8 May 2023 16:15:02 +1000 Subject: [PATCH] docs: add note about reproducibility state Signed-off-by: James Elliott --- cmd/authelia-scripts/cmd/types.go | 2 +- .../development/build-and-test.md | 33 +++++++++++-------- .../contributing/development/environment.md | 2 ++ 3 files changed, 22 insertions(+), 15 deletions(-) diff --git a/cmd/authelia-scripts/cmd/types.go b/cmd/authelia-scripts/cmd/types.go index 8191db932..2f7c3b268 100644 --- a/cmd/authelia-scripts/cmd/types.go +++ b/cmd/authelia-scripts/cmd/types.go @@ -85,7 +85,7 @@ func (b Build) XFlags() []string { fmt.Sprintf(fmtLDFLAGSX, "BuildBranch", b.Branch), fmt.Sprintf(fmtLDFLAGSX, "BuildTag", b.Tag), fmt.Sprintf(fmtLDFLAGSX, "BuildCommit", b.Commit), - fmt.Sprintf(fmtLDFLAGSX, "BuildDate", b.Date.Format(time.RFC1123)), + fmt.Sprintf(fmtLDFLAGSX, "BuildDate", b.Date.Format(time.RFC3339)), fmt.Sprintf(fmtLDFLAGSX, "BuildState", b.State()), fmt.Sprintf(fmtLDFLAGSX, "BuildExtra", b.Extra), fmt.Sprintf(fmtLDFLAGSX, "BuildNumber", strconv.Itoa(b.Number)), diff --git a/docs/content/en/contributing/development/build-and-test.md b/docs/content/en/contributing/development/build-and-test.md index 64e3af591..a9df8fc2f 100644 --- a/docs/content/en/contributing/development/build-and-test.md +++ b/docs/content/en/contributing/development/build-and-test.md @@ -141,19 +141,24 @@ go build -ldflags "-linkmode=external -s -w" -trimpath -buildmode=pie -o autheli #### Reproducible Builds -*__Please Note:__ The reproducibility instructions only apply for v4.38.0 or above. Users interested in reproducibility -of previous versions will have to carefully modify the linker flags to match the values outputted from the -`authelia build-info` command. In particular the Build Date was set as the actual time previously rather than the -commit time. In addition to this the ability to print the commands did not exist until just before this tag. If you have -trouble reproducing a build please let us know so we can figure it out, assist you, and document it.* +*__Important Note:__ At the time of this writing an unknown variance exists between our build system and the builds +produced via these instructions. We are investigating the cause and are intending to release proper instructions once +the underlying cause is identified.* -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: +*__Please Note:__ The reproducibility instructions only apply for v4.38.0 or above. +Users interested in reproducibility of previous versions will have to carefully modify the linker flags to match the +values outputted from the `authelia build-info` command. In particular the Build Date was set as the actual time +previously rather than the commit time. In addition to this the ability to print the commands did not exist until just +before this tag. If you have trouble reproducing a build please let us know so we can figure it out, assist you, and +document it.* + +Authelia intends to allow 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) +- Commit Date (using the RFC3339 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) @@ -167,6 +172,10 @@ variable or CLI argument): ##### Instructions +*__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).* + 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: @@ -183,10 +192,6 @@ 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/ diff --git a/docs/content/en/contributing/development/environment.md b/docs/content/en/contributing/development/environment.md index 356ea2e42..29c77401a 100644 --- a/docs/content/en/contributing/development/environment.md +++ b/docs/content/en/contributing/development/environment.md @@ -24,6 +24,7 @@ In order to build and contribute to __Authelia__, you need to make sure the foll * [go] *(v1.20 or greater)* * [gcc] * [gomock] + * [gox] (if you wish to use it to cross compile) * Frontend Development * [Node.js] *(v18 or greater)* * [pnpm] @@ -96,6 +97,7 @@ listed subdomains from your browser, and they will be served by the reverse prox [Buildkite]: https://buildkite.com/ [React]: https://reactjs.org/ [go]: https://go.dev/dl/ +[gox]: https://github.com/authelia/gox [gomock]: https://github.com/golang/mock [Node.js]: https://nodejs.org/en/download/ [pnpm]: https://pnpm.io/installation