ac5tin/muslrust repository overview

master: develop:

This is a fork of clux/muslrust⁠ to build true multi-architecture Docker images for linux/amd64, linux/arm, and linux/arm64 targets.

Images are built by Travis CI and pushed to jenskeiner/muslrust on Docker Hub for every change on master or develop branches, or when a new release tag is created.

Images built from git repository tags just use the tag name on Docker Hub, e.g. jenskeiner/muslrust:1.0.0, with the architecture-specific images adding an appropriate suffix, e.g. jenskeiner/muslrust:1.0.0-linux-amd64.

The latest tags always correspond to the latest images built from master. These should always be identical to the latest tag.

Builds from develop are tagged accordingly, i.e. jenskeiner/muslrust:develop

The text that follows below has been taken from clux/muslrust⁠ with adjustments where necessary.

⁠muslrust

A plain docker environment for building static binaries compiled with rust and linked against musl instead of glibc.

This is useful if you require external C dependencies, and/or need a CI image to compile a musl binary. Locally, you could do e.g. rustup target add x86_64-unknown-linux-musl if you don't need C dependencies and are building on linux/amd64 architecture.

This container comes with a bunch of statically compiled C libraries⁠ using musl-gcc so that we can statically link against these as well.

For embedded targets, consider cross⁠ as a more general solution.

⁠Usage

Pull and run from a rust project root:

docker pull jenskeiner/muslrust
docker run -v $PWD:/volume --rm -t clux/muslrust cargo build

You should have a static executable in the target folder:

ldd target/x86_64-unknown-linux-musl/debug/EXECUTABLE
        not a dynamic executable

From there on, you can include it in a blank docker image, distroless/static, or alpine (if you absolutely need kubectl exec), and you can end up with say:

• 4MB blog image (blank image)⁠.
• 6MB kubernetes controller with actix (distroless/static)⁠

⁠Docker builds

To pin against specific builds, see the available tags⁠ on the docker hub.

⁠C Libraries

The following system libraries are compiled against musl-gcc:

• curl (curl crate⁠)
• openssl (openssl crate⁠)
• pq (pq-sys crate⁠ used by diesel⁠)
• sqlite3 (libsqlite3-sys crate⁠ used by diesel⁠)
• zlib (used by pq and openssl)

We try to keep these up to date.

If it weren't for pq, we could ditch zlib as the flate2 crate bundles miniz.c as the default implementation, and this just works. Similarly, curl is only needed for people using the C bindings to curl over hyper⁠.

If you need extra dependencies, you can follow the builder pattern approach by portier-broker⁠

⁠Developing

Clone, tweak, build, and run tests:

git clone [email protected]:jenskeiner/muslrust.git && cd muslrust
make build
make test

Before we push a new version of muslrust we ensure that we can use and statically link:

• serde
• diesel (postgres and sqlite - see note below for postgres)
• hyper
• curl
• openssl
• flate2
• rand
• rocket (nightly only - some gaps⁠)

⁠SSL Verification

You need to point openssl at the location of your certificates explicitly to have https requests not return certificate errors.

export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
export SSL_CERT_DIR=/etc/ssl/certs

You can also hardcode this in your binary, or, more sensibly set it in your running docker image. The openssl-probe crate⁠ can be also be used to detect where these reside.

⁠Diesel and PQ builds

Works without fork now. See the test/dieselpgcrate⁠ for how to get this working.

For stuff like infer_schema! to work you need to explicitly pass on -e DATABASE_URL=$DATABASE_URL to the docker run. It's probably easier to just make diesel print-schema > src/schema.rs part of your migration setup though.

Note that diesel compiles with openssl statically since 1.34.0, so you need to include the openssl crate before diesel due to pq-sys#25⁠:

extern crate openssl;
#[macro_use] extern crate diesel;

This is true even if you connect without sslmode=require.

⁠Caching Cargo Locally

Repeat builds locally are always from scratch (thus slow) without a cached cargo directory. You can set up a docker volume by just adding -v cargo-cache:/root/.cargo/registry to the docker run command.

You'll have an extra volume that you can inspect with docker volume inspect cargo-cache.

Suggested developer usage is to add the following function to your ~/.bashrc:

musl-build() {
  docker run \
    -v cargo-cache:/root/.cargo/registry \
    -v "$PWD:/volume" \
    --rm -it jenskeiner/muslrust cargo build --release
}

Then use in your project:

$ cd myproject
$ musl-build
    Finished release [optimized] target(s) in 0.0 secs

Second time around this will be quick, and you can even mix it with native cargo build calls without screwing with your cache.

⁠Debugging in blank containers

If you are running a plain alpine/scratch container with your musl binary in there, then you might need to compile with debug symbols, and set ENV RUST_BACKTRACE=full in your Dockerfile.

In alpine, if even this doesn't work (or fails to give you line numbers), try installing the rust package (via apk). This should not be necessary anymore though!

For easily grabbing backtraces from rust docker apps; try adding sentry⁠. It seems to be able to grab backtraces regardless of compile options/evars.

⁠Using muslrust on CI

Due to the current best compatibility with docker caching strategies, recommended CI is Circle. See webapp-rs⁠, operator-rs⁠, or raftcat⁠ for complete life-cycle rust cloud applications running in alpine containers built on CI (first two are demos, second one has more stuff).

⁠Clippy

If you need to install clippy⁠ on a CI build image, you need to build it against the GNU toolchain (see #37⁠):

CARGO_BUILD_TARGET=x86_64-unknown-linux-gnu cargo install clippy

⁠SELinux

On SELinux enabled systems like Fedora, you will need to configure selinux labes⁠. E.g. adding the :Z or :z flags where appropriate: -v $PWD:/volume:Z.