hyperswitch/docs/building_docker_images.md

Building Docker Images

Cargo Features

The Hyperswitch application server makes extensive use of Cargo features to selectively toggle certain features and integrations. The list of features can be found in the [features] section in the crates/router/Cargo.toml file.

Of these features, the noteworthy ones are the default and release features:

• default: This feature set enables a basic set of necessary features for both development and production environments, such as the transactional APIs, APIs used by the control center, Stripe compatibility, automatic payment retries, in-memory caching, etc.

• release: This feature set enables some additional features that are suitable for production environments, such as AWS KMS integration, AWS S3 integration, AWS SES integration, etc.

Refer to the documentation on cargo features to understand how to select features with Cargo, when building the application server.

Building with the Dockerfile

The Docker images for the application server and other components can be built using the Dockerfile using the below commands, substituting the Docker image tags with suitable values:

• router:

  docker build \
    --load \
    --file Dockerfile \
    --build-arg "BINARY=router" \
    --tag hyperswitch-router \
    .
  

• consumer:

  docker build \
    --load \
    --file Dockerfile \
    --build-arg "BINARY=scheduler" \
    --build-arg "SCHEDULER_FLOW=consumer" \
    --tag hyperswitch-consumer \
    .
  

• producer:

  docker build \
    --load \
    --file Dockerfile \
    --build-arg "BINARY=scheduler" \
    --build-arg "SCHEDULER_FLOW=producer" \
    --tag hyperswitch-producer \
    .
  

• drainer:

  docker build \
    --load \
    --file Dockerfile \
    --build-arg "BINARY=drainer" \
    --tag hyperswitch-drainer \
    .
  

When our Docker images are built using the Dockerfile, the cargo command being run is:

cargo build --release --features release ${EXTRA_FEATURES}

• The --release flag specifies that optimized release binaries must be built. Refer to the cargo build manual page for more information.

• The --features release flag specifies that the release feature set must be enabled for the build. Since we do not specify the --no-default-features flag to the cargo build command, the build would have the default and release features enabled.

• In case you create your own features sets and want to enable them, you can use the ${EXTRA_FEATURES} build argument to specify any additional features that would have to be passed to the cargo build command. The build argument could look as follows: EXTRA_FEATURES="--features feature1,feature2,feature3", with actual feature names substituted in the command.

Image Variants on Docker Hub

As of writing this document, we have two image variants available on our Docker Hub repositories:

• release: These images contain only the tag that was built, and no other suffixes, like the v1.105.1 and v1.107.0 Docker images.

• standalone: These images contain the tag that was built with a standalone suffix, like the v1.105.1-standalone and v1.107.0-standalone Docker images.

The primary difference is that our standalone Docker images do not have some features enabled by default in order to support hosting of Hyperswitch outside AWS. As of writing this document, the standalone images exclude the email and recon features from the release feature set, while the release images are built from the Dockerfile without any changes to the codebase after the tag is checked out.

If you are building custom images and would like to mirror the behavior of our standalone images, then you'd have to remove the email and recon features from the release feature set.

Frequently Asked Questions

What machine specifications would I need to build release images?

Building release (optimized) images needs significant amount of resources, and we'd recommend using a machine with at least 8 cores and 16 GB of RAM for this purpose. Rust is known to have long compile times, and a codebase of this size will require a significant time to build, around 45-60 minutes for the above configuration.

Build seems to be stuck at "Compiling router/scheduler/analytics/..."

The compilation process involves compiling all of our dependencies and then compiling our workspace (first-party) crates, among which the biggest one (in terms of lines of code) is the router crate. Once all the dependencies of the router crate have been built, one of the last ones being built is the router crate itself.

As mentioned above, building release images takes a significant amount of time. It is normal to see nothing else being printed after a line which says Compiling router / scheduler / analytics / .... We'd suggest waiting for a while. If you're still concerned that the compilation process has been stuck for far too long, you can check if at least one CPU is being utilized by cargo / docker using a tool like htop (if you can access the machine which is building the code). Worst case, you can proceed to kill the compilation process and try again.