README.md 4.16 KB
Newer Older
noplanman's avatar
noplanman committed
1 2 3 4 5 6 7 8 9 10 11 12 13
# Borg Binary Builder

Build [BorgBackup] binaries on any platform, for any architecture, using docker.

## Usage

### Build image

`./build.sh <arch> [<version>]`

See the [list of available architectures] ([on GitHub][available-architectures-github])

*Examples:*
noplanman's avatar
noplanman committed
14
- Build version `1.1.10` for `aarch64`
15

noplanman's avatar
noplanman committed
16
`./build.sh aarch64 1.1.10`
noplanman's avatar
noplanman committed
17 18

- Build version `1.1.5` for Raspberry Pi 3
19

noplanman's avatar
noplanman committed
20 21 22 23
`./build.sh raspberrypi3 1.1.5`

### Extract borg binary

noplanman's avatar
noplanman committed
24
`./extract.sh <arch> [<version>] [<binary_save_location>]`
noplanman's avatar
noplanman committed
25 26 27 28

**Note:** This will overwrite the file at `binary_save_location` if it already exists!

*Examples:*
noplanman's avatar
noplanman committed
29
- Extract borg `1.1.10` binary for `aarch64` to `borg-aarch64` in current folder
30

noplanman's avatar
noplanman committed
31
`./extract.sh aarch64 1.1.10 borg-aarch64`
noplanman's avatar
noplanman committed
32

noplanman's avatar
noplanman committed
33
- Extract borg `1.1.5` binary for Raspberry Pi 3 to `/homes/lemoi/borg`
34

noplanman's avatar
noplanman committed
35
`./extract.sh raspberrypi3 1.1.5 /homes/lemoi/borg`
noplanman's avatar
noplanman committed
36

37 38 39
### Build base image

To speed up the building process, certain architectures have a prebuilt base image with the development requirements already installed.
40 41

These base images are based on BorgBackup version 1.1.0 *(for versions 1.1.0 to 1.1.9)* and 1.1.10 *(for versions 1.1.10 and later)*.
42 43 44 45 46 47

Adding a new architecture to the base image list and pushing it to docker hub:

`./build-base.sh <arch>`

*Examples:*
48 49
- Build base image for `aarch64`:

50 51
`./build-base.sh aarch64`

noplanman's avatar
noplanman committed
52 53 54 55 56 57 58 59 60 61 62 63
## How this works

### Build

The `build.sh` script downloads the appropriate starter docker image that contains the necessary QEMU binary for building and registers it in the build agent.

For more details, check the [Hypriot blog post] that explains it in more depth.

Then, the docker image is built for the requested architecture.

This is basically done by following the flow of setting up a [BorgBackup development environment] and [creating the standalone binary]. (For more info on this, just have a look at the `Dockerfile`)

64
When using the base images created by `build-base.sh`, instead of using the normal `Dockerfile`, you can set the `BBB_HOT` environment variable to any value, which makes the build script use `Dockerfile.hot`.
65

66 67
The build then starts off with the prebuilt base image, speeding up the build tremendously.

68 69
Builds are based on the Python 3.5 images on Debian Jessie.

noplanman's avatar
noplanman committed
70 71 72 73 74 75
### Extract

The `extract.sh` script extracts the built binary from the image created using `build.sh`.

This basically starts a container from the built image for your selected architecture and writes the binary out to the file path you passed as a parameter.

76 77 78 79 80
## Verify PGP Signature

All automated binary builds can be found on Bintray:
- https://bintray.com/borg-binary-builder/borg-binaries/borg-binaries

noplanman's avatar
noplanman committed
81
Using version `1.1.10` for `armv7` as an example:
82

noplanman's avatar
noplanman committed
83
1. Simply download the desired binary (`borg-1.1.10-armv7`) and it's corresponding signature file (`borg-1.1.10-armv7.asc`).
84 85 86
2. Next we have to import the official PGP public key needed for verification (which you can find in this repo):
    - `gpg --import borg-binary-builder.public.asc`
3. Then verify the downloaded binary with it's signature file:
noplanman's avatar
noplanman committed
87
    - `gpg --verify borg-1.1.10-armv7.asc borg-1.1.10-armv7`
88 89
4. Whoop!

noplanman's avatar
noplanman committed
90 91 92 93
## License

Borg Binary Builder is licensed under the terms of the [WTFPL]. See the [LICENSE] file.

noplanman's avatar
noplanman committed
94 95 96
[BorgBackup]: https://github.com/borgbackup/borg/ "BorgBackup on GitHub"
[BorgBackup development environment]: https://borgbackup.readthedocs.io/en/stable/development.html#building-a-development-environment "BorgBackup development environment"
[creating the standalone binary]: https://borgbackup.readthedocs.io/en/stable/development.html#creating-standalone-binaries "Create standalone binary"
97 98
[list of available architectures]: https://www.balena.io/docs/reference/base-images/base-images/#balena-base-images "List of available Architectures"
[available-architectures-github]: https://github.com/balena-io-library/base-images/tree/master/balena-base-images/python "List of available Architectures on GitHub"
noplanman's avatar
noplanman committed
99
[Hypriot blog post]: https://blog.hypriot.com/post/setup-simple-ci-pipeline-for-arm-images/ "Setup a simple CI pipeline to build Docker images for ARM"
noplanman's avatar
noplanman committed
100
[WTFPL]: http://www.wtfpl.net/about/ "Do What the Fuck You Want to Public License"
101
[LICENSE]: https://git.feneas.org/borg-binary-builder/borg-binaries/blob/master/LICENSE "View License"