retail-store-sample-app: a deliberately over-engineered demo of containers on AWS

Five services in three languages, split on purpose

The AWS Containers Retail Sample is a demo store: product catalog, shopping cart and checkout, wrapped in a store front that also exposes container and application topology pages, themes and a generative AI chat bot. The structure is the lesson. The README states the application has been deliberately over-engineered to generate multiple decoupled components, because those components generally have different infrastructure dependencies and may support multiple backends. The Cart service is the worked example: it can sit on MongoDB or DynamoDB.

The component table makes the split concrete. UI is Java, catalog is Go, cart is Java, orders is Java and checkout is Node. Each component has a published container image in the public registry and a Helm chart, and each is linked from the same table, so a reader can see the deployment artifacts next to the source directory for each service. The repository topics list kubernetes, docker, docker-compose, golang, java, javascript and microservices-architecture, and the top-level tree includes src/, terraform/, oss/, samples/, scripts/ and docs/.

It is worth naming what this is not. The repository description calls it a sample application for demonstrating container platforms and related technology, and the README is more direct still: the project is intended for educational purposes only and not for production use. That line sits above the architecture diagram, and it is the single most important sentence for anyone considering adoption.

Observability is wired in, not bolted on

Two of the listed features matter more than a shopping cart does. All components are instrumented for Prometheus metrics and OpenTelemetry OTLP tracing, and there is support for Istio on Kubernetes. The repository also ships a load generator which exercises all of the infrastructure.

That combination changes what the demo is for. A service that emits metrics and spans is a service you can show a load generator's traffic against, so you can watch request rates, latency and error counts change under load rather than describing them. Combined with the topology pages in the store front, a demo can be driven end to end: generate traffic, watch the metrics, then look at the traces and the topology view.

The Istio support is the third leg. A service mesh is hard to demonstrate on a laptop with two processes, so a Kubernetes deployment with Istio in the path lets you show mesh behaviour against the same application code. The educational claim holds together because the instrumentation is present in every component rather than in one demo service.

Running the whole store in one container with docker

The quickest path needs Docker installed locally and nothing else. The documentation describes this deployment method as running the application as a single container on your local machine, so the multi-service architecture is collapsed into one image for the first run. That is a deliberate simplification for a first look, not the architecture you would deploy.

docker run -it --rm -p 8888:8080 public.ecr.aws/aws-containers/retail-store-sample-ui:1.0.0

Port 8888 on the host maps to port 8080 in the container. Open http://localhost:8888 in a browser and the store front appears. Ctrl+C stops the container, and because the run uses --rm the container is removed as it exits, so nothing is left behind to clean up by hand. Note the image tag is pinned at 1.0.0 in this example even though the repository's recent releases are v1.6.3, v1.6.2 and v1.6.1, so the tag you copy is a starting point rather than the newest published build.

Docker Compose pulls the real service topology back apart

The Compose path is where the components and their persistence backends appear. The documentation tells you to download the latest Compose file and run it, and the database password is supplied through the DB_PASSWORD environment variable inline on the command.

wget https://github.com/aws-containers/retail-store-sample-app/releases/latest/download/docker-compose.yaml
DB_PASSWORD='<some password>' docker compose --file docker-compose.yaml up

Once it is up, http://localhost:8888 again is the entry point. Stopping is Ctrl+C, and the cleanup command removes the containers and their related resources:

docker compose -f docker-compose.yaml down

One detail worth understanding before you try it: DB_PASSWORD is read from the environment, so the value has to be set for the containers to start, and the placeholder in the documentation is literally <some password>. If you copy the line without replacing it, the components that expect a database credential will fail to come up, and the failure will look like an application problem rather than a missing variable.

The repository's own package.json shows how the maintainers run the same stack locally, with a longer command that builds and waits for readiness:

    "compose:up": "docker compose --project-directory src/app up --build --detach --wait --wait-timeout 120",
    "compose:down": "docker compose --project-directory src/app down",

The --wait flag and the 120 second timeout are the interesting part: they make the command fail fast if a dependency never becomes healthy, instead of leaving you to guess which container is stuck.

Kubernetes deployment through a single remote manifest

For a cluster, the prerequisites are a Kubernetes cluster and kubectl installed locally. The manifest is fetched straight from the release assets, so you are applying whatever the latest published release contains rather than a file from your checkout.

kubectl apply -f https://github.com/aws-containers/retail-store-sample-app/releases/latest/download/kubernetes.yaml
kubectl wait --for=condition=available deployments --all

The second command is the one that carries the real work. Waiting for all deployments to become available tells you when the pods are up, which avoids the situation where you open the load balancer URL while a backend is still starting. The frontend URL comes from the service named ui:

kubectl get svc ui

Removal uses the same manifest, so the teardown matches what was applied:

kubectl delete -f https://github.com/aws-containers/retail-store-sample-app/releases/latest/download/kubernetes.yaml

Since the store front is a Java service and the checkout is Node, a cluster deployment also gives you several runtimes to look at in one place, which is usually the point of running this in Kubernetes rather than on a laptop.

Four Terraform targets, from a full EKS stack to App Runner

The repository ships four Terraform entry points, and the difference between them is where the dependencies live. Amazon EKS deploys the application using other AWS services for dependencies such as RDS and DynamoDB. Amazon EKS (Minimal) uses in-cluster dependencies instead of RDS, DynamoDB and the rest. Amazon ECS deploys to ECS with those same external AWS services. AWS App Runner is the fourth option, also with external AWS dependencies.

That minimal variant is the interesting one for learning, because it removes the managed service dependencies and keeps the stateful pieces inside the cluster. It is also the closest to what a small self-hosted deployment would look like, which makes it a better fit for a demo that must run without a large AWS footprint.

The infrastructure choices are layered on top of the same application images. The Helm chart links in the component table exist precisely so a platform team can install a single service rather than the whole bundle, which is the natural first step when you want to look at one component in isolation.

What a demo app costs you to keep

Two kinds of cost show up in the tree. The first is the obvious one: you are running a store front, a catalog, a cart, an orders service and a checkout service, plus MariaDB or MySQL, DynamoDB or Redis, plus the mesh and metrics stack if you enable them. For a workshop laptop that is the Compose path; for anything with a load balancer and real cloud dependencies, the cost moves to your cloud bill.

The second cost is maintenance, and the top-level files give a fair picture of it. There is a CHANGELOG.md, a release-please configuration with a manifest, a.mergify.yml for merge automation, renovate.json for dependency updates, lefthook.yml for git hooks, nx.json and.mise.toml for the build tooling, and a yarn.lock with the package manager pinned at [email protected]. The package.json itself declares the project as private with name store and version 0.0.1, and its workspace is oss/attribution. The release-please setup is why the tags carry v prefixes and why the release dates in the repository line up with commit history.

The repository is not archived and the last push was on 2026-10-20, with v1.6.3 on 2026-09-25, v1.6.2 on 2026-07-28 and v1.6.1 on 2026-05-27. Renovate and release automation mean you are not expected to hand-patch dependencies, but you are also inheriting a toolchain where the sample app, not your product, sets the pace of upgrades. The licence is MIT-0, which is a permissive grant with no warranty and no patent clause, so the code is easy to fork into something of your own.

Editorial conclusion

Use retail-store-sample-app when you need a working multi-service topology with real persistence backends, tracing and instrumentation to point a workshop or a proof of concept at. Do not use it as a production base: the README states the project is intended for educational purposes only and not for production use. Before you build on it, run the Docker Compose path with DB_PASSWORD set, check the container images exist for your CPU architecture, and read the terraform/eks/minimal option if you want dependencies inside the cluster rather than in RDS or DynamoDB.

Frequently asked questions

Official sources

1. aws-containers/retail-store-sample-app on GitHub
2. Issues
3. License: MIT-0
4. README
5. Releases