README.md 4.25 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:*
14
- Build version `1.1.14` for `aarch64`
15

16
`./build.sh aarch64 1.1.14`
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:*
29
- Extract borg `1.1.14` binary for `aarch64` to `borg-aarch64` in current folder
30

31
`./extract.sh aarch64 1.1.14 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 42 43 44
These base images are based on BorgBackup versions:
- 1.1.14 *(for versions 1.1.14 and later)*
- 1.1.10 *(for versions 1.1.10 to 1.1.13)*
- 1.1.0 *(for versions 1.1.0 to 1.1.9)*
45 46 47 48 49 50

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

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

*Examples:*
51 52
- Build base image for `aarch64`:

53 54
`./build-base.sh aarch64`

noplanman's avatar
noplanman committed
55 56 57 58 59 60 61 62 63 64 65 66
## 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`)

67
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`.
68

69 70
The build then starts off with the prebuilt base image, speeding up the build tremendously.

71
Builds are based on the Python 3.5 images on Debian Stretch (1.1.14 and later) and Jessie (1.1.0 to 1.1.13).
72

noplanman's avatar
noplanman committed
73 74 75 76 77 78
### 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.

79 80 81 82 83
## Verify PGP Signature

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

84
Using version `1.1.14` for `armv7` as an example:
85

86
1. Simply download the desired binary (`borg-1.1.14-armv7`) and it's corresponding signature file (`borg-1.1.14-armv7.asc`).
87 88 89
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:
90
    - `gpg --verify borg-1.1.14-armv7.asc borg-1.1.14-armv7`
91 92
4. Whoop!

noplanman's avatar
noplanman committed
93 94 95 96
## License

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

noplanman's avatar
noplanman committed
97 98 99
[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"
100 101
[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
102
[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
103
[WTFPL]: http://www.wtfpl.net/about/ "Do What the Fuck You Want to Public License"
104
[LICENSE]: https://git.feneas.org/borg-binary-builder/borg-binaries/blob/master/LICENSE "View License"