Skip to content

custom-environment.md

Latest commit

 

History

History
109 lines (70 loc) · 5.07 KB

custom-environment.md

File metadata and controls

109 lines (70 loc) · 5.07 KB
Raw

Building Sleeper in a custom environment

Sleeper's build and deployment scripts have a small set of configuration points for users whose environments need to substitute the default build inputs. This page lists every such point in one place: what it does, and a worked example.

None of these are needed for a default build.

Container images

--override-base-image-dir, --override-base-image-dir-by-image (on setDeployConfig.sh)

You can override the directory used as the Docker build context for the Sleeper base Docker image. This image is used as the base image for most of the other Docker images built during a Sleeper deployment. By default the base image is built from scripts/docker/base. Pass a different directory containing your own Dockerfile to substitute a custom base image.

You can also add a separate base Docker image for a specific image, referenced by the deployment name or image name documented in Docker images deployed in Sleeper.

Either of these options will apply when you run scripts/deploy/deployNew.sh, scripts/deploy/deployExisting.sh, scripts/deploy/uploadArtefacts.sh, or scripts/dev/publishDocker.sh, as the configuration is persisted in scripts/templates/deployConfig.json.

This override only applies to local builds — it cannot be combined with --image-location repository or --image-repository-prefix.

Here's an example:

./scripts/deploy/setDeployConfig.sh \
    --image-location localBuild \
    --override-base-image-dir /path/to/my/base \
    --override-base-image-dir-by-image bulk-import-runner=/path/to/other/base

See publishing artefacts for the full publish flow.

Rust build

The Rust components are built inside Docker containers via rust/build-in-docker.sh (this script is called in-directly from Maven during a normal Sleeper build process), with the builder images themselves produced by rust/builders/buildAll.sh (or buildAllSccache.sh). The configuration points below affect either the building of those builder images or how the Rust workload runs inside them.

The variables below should be set via environment variables as shown.

RUSTUP_DIST_SERVER and RUSTUP_UPDATE_ROOT

Override the upstream servers used by rustup when installing the Rust toolchain into the builder images.

Example:

export RUSTUP_DIST_SERVER=https://rustup.internal.example.com
export RUSTUP_UPDATE_ROOT=https://rustup.internal.example.com/rustup
./rust/builders/buildAll.sh

Either variable can be set independently. If both are unset, the builder images are built against the public rustup servers.

EXTRA_CARGO_CONFIG

Appends arbitrary TOML to the Cargo configuration used for the current Rust build. The content is appended to the configuration from rust/.cargo/config.toml without modifying the checked‑in file.

Use this to point cargo at an internal crates.io mirror, configure a private registry, set source replacement rules, or any other per-environment cargo setting that should not be committed.

Example — replace the default crates.io source with an internal mirror

Let's say we need to re-direct crates.io to an internal mirror at https://crates.internal.example.com/index. We might want the following in our config.toml:

[source.crates-io]
replace-with = "internal-mirror"

[source.internal-mirror]
registry = "https://crates.internal.example.com/index"

Setting the EXTRA_CARGO_CONFIG environment variable as follows will append the configuration to the end of the Cargo configuration.

export EXTRA_CARGO_CONFIG='[source.crates-io]\nreplace-with = "internal-mirror"\n\n[source.internal-mirror]\nregistry = "https://crates.internal.example.com/index"'
./rust/build-in-docker.sh x86_64

SKIP_DOCKER_PULL

When set to any non-empty value, rust/build-in-docker.sh does not run docker pull against the builder image before running the build. The build still uses whatever image is locally tagged.

Useful when you have built the builder image locally and do not want it overwritten by a pull, or when the public registry is unreachable and the image has been loaded by some other means.

Example:

./rust/builders/buildAll.sh                # builds and tags the image locally
export SKIP_DOCKER_PULL=true
./rust/build-in-docker.sh x86_64           # uses the local image, no pull

certs/ directory

Drop PEM-encoded CA certificate files into the certs/ directory at the repository root if the Rust builder image needs to trust a private certificate authority. Any file extension may be used — .crt, .pem, .cer, etc.

Files placed here (other than the placeholder README.md) are picked up by rust/builders/buildAll.sh and rust/builders/buildAllSccache.sh and installed as trusted CA certificates inside the builder container. Nothing is installed on the host.

If certs/ only contains the placeholder README.md, the builder images are built without any custom CA trust changes.

Example:

cp my-corporate-root-ca.crt certs/
./rust/builders/buildAll.sh