docs: add documentation page for building Docker images (#4457)

Co-authored-by: Shakthidhar Bhaskar <[email protected]>

Author: SanchithHegde

.github/PULL_REQUEST_TEMPLATE.md

@@ -54,4 +54,3 @@ Or did you test this change manually (provide relevant screenshots)?
 - [ ] I addressed lints thrown by `cargo clippy`
 - [ ] I reviewed the submitted code
 - [ ] I added unit tests for my changes where possible
-- [ ] I added a [CHANGELOG](/CHANGELOG.md) entry if applicable

docs/building_docker_images.md

@@ -0,0 +1,155 @@
+# Building Docker Images
+
+## Cargo Features
+
+The Hyperswitch application server makes extensive use of
+[Cargo features][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`][router-manifest] 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][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`][dockerfile] using the below commands, substituting the
+Docker image tags with suitable values:
+
+- router:
+
+  ```shell
+  docker build \
+    --load \
+    --file Dockerfile \
+    --build-arg "BINARY=router" \
+    --tag hyperswitch-router \
+    .
+  ```
+
+- consumer:
+
+  ```shell
+  docker build \
+    --load \
+    --file Dockerfile \
+    --build-arg "BINARY=scheduler" \
+    --build-arg "SCHEDULER_FLOW=consumer" \
+    --tag hyperswitch-consumer \
+    .
+  ```
+
+- producer:
+
+  ```shell
+  docker build \
+    --load \
+    --file Dockerfile \
+    --build-arg "BINARY=scheduler" \
+    --build-arg "SCHEDULER_FLOW=producer" \
+    --tag hyperswitch-producer \
+    .
+  ```
+
+- drainer:
+
+  ```shell
+  docker build \
+    --load \
+    --file Dockerfile \
+    --build-arg "BINARY=drainer" \
+    --tag hyperswitch-drainer \
+    .
+  ```
+
+When our Docker images are built using the [`Dockerfile`][dockerfile], the
+`cargo` command being run is:
+
+```shell
+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][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.
+
+[cargo-features]: https://doc.rust-lang.org/cargo/reference/features.html
+[router-manifest]: https://github.com/juspay/hyperswitch/blob/main/crates/router/Cargo.toml
+[dockerfile]: https://github.com/juspay/hyperswitch/blob/main/Dockerfile
+[cargo-build-manual-page]: https://doc.rust-lang.org/cargo/commands/cargo-build.html