Setup

Montuer natively facilitates the Setup CI job with the sole purpose to setup the repository for development and testing, building the releasable version, package and sign the release version. This section covers entirely on setting up Setup job.

The objective of the job is simple: to setup the repository all the way for other CI jobs without minimal to no further instructions.

Overall Configurations

To configure the job for execution, you need to supply and modify .configs/monteur/setup/config.toml file. These are the various settings for customizations.

Downloads

To configure the download behavior, you can include or modify the existing [Downloads] table. Here is an example:

1
2
3
[Downloads]
Limit = 3
Timeout = 120000000000 # nanosecond

Limit

The Limit is to instruct Monteur to control the maximum number of download task at a time.

The data type is number above 0 (unsigned integer).

Monteur executes download tasks asynchonously so it will cause a spike of download bandwidth should there be many downloads. Hence, the Limit is set in place to ensure Monteur does not cause a network distruption.

Timeout

The Timeout is to instruct a sourcing task to stop and to report itself as error due to unknown long waiting time. The unit is nanosecond so 2 minutes is 120 * 1000 * 1000 * 1000.

The data type is positive (above or equal to 0) 64-bit integer.

Setting the value to 0 will revert to default timeout which is 2 minutes.

Program Configurations

Monteur accepts one program configuration file per dependent program type (e.g. one go.toml for Go programming language). However, the internal operations allow many programs to be setup simultenously and asynchonously (e.g. go.toml, hugo.toml, golangci-lint.toml, …). Each program configuration file shares the same file structure.

Storing Location

All program configuration files SHALL be stored inside .configs/monteur/setup/jobs/ directory.

File Nature

The configuration file MUST have the file extension. Otherwise, it will be ignored. Currently the following formats are supported sorted by priority sequences:

  1. TOML (program.toml) - https://github.com/toml-lang/toml

The filename does not affect any of the parsed configurations so feel free to name it according to your own pattern.

Data Structure

Each configuration file follows the following data structure:

[Metadata]

This table houses all the information about the program metadata such as its name, description, and how to source the program. Here is an example:

1
2
3
4
5
6
[Metadata]
Name = 'Go'
Description = """
Go programming language for compiling Go source codes.
"""
Type = 'https-download'

The Name field will be used for various internal configurations so Monteur recommends keeping it concise and without any weird symbol (space will be replaced by short dash).

The Description is mainly for logging and the config file comprehension purposes. You can write a short description for it.

Among the supported sourcing Type values are:

[Variables]

This table houses all the data that are subjected to change overtime. It takes a key-value combination to house your value for later use. Here is an example:

1
2
3
[Variables]
Version = '1.17.3'
BaseURL = 'https://golang.org/dl/'

Note that the values SHALL be a non-formatting value (e.g. without {{- .SomeKey -}}). To use those, see [FMTVariables] section.

The values can be any data types as long as it is sensible for direct replacement in a variable formatting activities.

[FMTVariables]

This table houses all Formattable Variables Definition (e.g. {{- .Version -}}) specific to this setup recipe. It shall appears onto all listed packages. Example:

1
SourceDir = '{{- .WorkingDir -}}/public'

All formatted variables are either create or overwrite to the existing variables list.

[[Dependencies]]

The [Dependencies] is an array of program data for checking all required programs only for Setup job. Therefore, it has extra square braces when defining its data.

It is compliant to Monteur’s internal Dependencies Checking function.

Here is an example for defining a list of dependencies:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
[[Dependencies]]
Name = 'Hugo'
Condition = 'all-all'
Type = 'command'
Command = 'hugo'

[[Dependencies]]
Name = 'Git'
Condition = 'all-all'
Type = 'command'
Command = 'git'

[Sources.OS-ARCH]

The [Sources.OS-ARCH] table is a list of sourcing instructions for Monteur to source the program across various operating system (OS) and CPU architecture (ARCH).

Here is an example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
[Sources.all-all]
Format = 'tar.gz'
URL = '{{- .BaseURL -}}{{- .Archive -}}'
Method = 'GET'
[Sources.all-all.Checksum]
Type = 'sha256'
Format = 'hex'

[Sources.darwin-amd64]
Archive = 'go{{- .Version -}}.darwin-amd64.{{- .Format -}}'
[Sources.darwin-amd64.Checksum]
Value = '765c021e372a87ce0bc58d3670ab143008dae9305a79e9fa83440425529bb636'

[Sources.darwin-arm64]
Archive = 'go{{- .Version -}}.darwin-arm64.{{- .Format -}}'
[Sources.darwin-arm64.Checksum]
Value = 'ffe45ef267271b9681ca96ca9b0eb9b8598dd82f7bb95b27af3eef2461dc3d2c'

...

[Sources.windows-arm64]
Format = 'zip'
Archive = 'go{{- .Version -}}.windows-arm64.{{- .Format -}}'
[Sources.windows-arm64.Checksum]
Value = '4e7f9a19af8a96e81b644846f27d739344375f9c69bad2e673406ab8e8a01101'

The [Sources.{OS}-{ARCH}] naming is based on Montuer’s OS-ARCH platform identification values. See Platform Identification for more info.

Monteur allows overwriting to all-all platform ID data for the sole purpose of avoiding duplicating values especially for programs supporting wide arrays of operating system and CPU architectures. Hence, it is always recommended to define the common values into the all-all platform ID before defining the platform specific ones as shown above.

Then, based on the program’s downloadable portal, the specific values are mapped back accordingly. Should there be any conflicting fields from all-all platform ID, it shall be overwritten by the platform specific ones. Based on the example above, to setup the program on windows-arm64 platform, the final Format value is .zip and not the tar.gz.

Monteur also supports checksum function for security and integrity purpose. To declare a checksum, simply states the Checksum after the platform table. Following the example above, it would be: [Sources.darwin-arm64.Checksum]. Similarly, one can also define common checksum settings in the all-all common platform ID for avoiding duplications.

In the end, a source for a platform with an CPU architecture should comply to the following data structure:

1
2
3
4
5
6
7
8
9
[Sources.darwin-amd64]
Format = 'tar.gz'
Archive = 'go{{- .Version -}}.darwin-amd64.{{- .Format -}}'
URL = '{{- .BaseURL -}}{{- .Archive -}}'
Method = 'GET'
[Sources.darwin-amd64.Checksum]
Type = 'sha256'
Format = 'hex'
Value = '765c021e372a87ce0bc58d3670ab143008dae9305a79e9fa83440425529bb636'

Format is to define the downloaded compressed archive format. Currently, Monteur supports the following formats:

Archive is the naming format of the program after being sourced. This is for unarchive purposes and since there is no standardization across all naming conventions, it needs one to define the pattern for it. Variables formatting clauses are allowed for this field.

URL is the location of the source in URI with protocol format. For local directory or files, simply use the local file protocol (file://). Variables formatting cluses are allowed for this field.

Method is the action of sourcing. For https-download type, Method is the case-sensitive HTTP Method.

Checksum.Type is the algorithm used for generating the checksum token. Monteur currently supports the following algorithms:

Checksum.Format is the checksum algorithm format used to parse the given Checksum.Value. Monteur supports the following formats:

Checksum.Value is the checksum value for that particular source in string format.

[[Setup]]

[Setup] is basically an array of instructions for installing the unarchived program into Monteur’s localized binary directory. Hence, this is why it has extra square braces.

Its values are complying to Monteur’s Commands Execution Units. Here is an example:

1
2
3
4
5
[[Setup]]
Type = 'move'
Condition = 'all-all'
Source = '{{- .WorkingDir -}}/go'
Target = '{{- .BinDir -}}/golang'

For programs requiring build from source, you can build your chain of commands here.

[Config]

The config is the last step of Setup job where it generates the config sourcing script specific to the operating system. These scripts are for the customers to source from Monteur’s local filesystem to develop the repository.

Here is an example of a specific config file in linux for Go Programming Language looks like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
[Config]
linux = """
#!/bin/bash
export LOCAL_BIN="${LOCAL_BIN:-{{- .BinDir -}}}"
export GOROOT="${LOCAL_BIN}/golang"
export GOPATH="${LOCAL_BIN}/gopath"
export GOBIN="${GOPATH}/bin"
export GOCACHE="${LOCAL_BIN}/gocache"
export GOENV="${LOCAL_BIN}/goenv"

stop_go() {
        PATH=:${PATH}:
        GOROOT="${GOROOT}/bin"
        PATH=${PATH//:$GOROOT:/:}
        PATH=${PATH//:$GOBIN:/:}
        PATH=${PATH//:$GOPATH:/:}
        PATH=${PATH%:}
        unset GOROOT GOPATH GOBIN GOCACHE GOENV
}

case $1 in
--stop)
        stop_go
        ;;
*)
        export PATH="${PATH}:${GOROOT}/bin:${GOPATH}:${GOBIN}"

        if [ ! -z "$(type -p go)" ] && [ ! -z "$(type -p gofmt)" ]; then
                1>&2 printf "[ DONE  ] localized Go started.\\n"
        else
                1>&2 printf "[ ERROR ] localized Go failed to initalized.\\n"
                stop_go
        fi
        ;;
esac
"""

Monteur will seek out the right config data based on the platfrom OS. Should you need to be specific with a CPU architecture, please script it inside your config file.

Known Templates

Now that you understand how Monteur executes Setup CI Job, fortunately, Monteur maintains a number of recipes for you to kick-start your deployment. Here are some currently maintained templates for different deployments: