MuShop is a complete e-commerce platform built as a set of microservices, demonstrating modern cloud-native application development practices. The application has been refactored to be cloud-agnostic, using open-source technologies instead of proprietary cloud services.

New! MuShop now runs on any cloud platform or locally using standard open-source technologies:

• PostgreSQL instead of Oracle Autonomous Database
• MinIO instead of OCI Object Storage
• Apache Kafka instead of OCI Streaming
• NATS for messaging
• Mailhog for SMTP (development)

The easiest way to run MuShop locally is using Docker Compose, which sets up the complete application stack including all microservices and infrastructure components.

• Docker 20.10 or later
• Docker Compose 1.29 or later
• At least 8GB of RAM allocated to Docker
• 10GB of free disk space

# Clone the repository
git clone https://github.com/rishikeshr/oci-cloudnative.git
cd oci-cloudnative

# Start all services (builds images and starts containers)
docker-compose up -d

# Wait for services to be ready (may take 2-3 minutes)
docker-compose ps

# Access the application
open http://localhost:8086

The Docker Compose setup includes:

Application Microservices:

• Storefront (http://localhost:8086) - React-based web UI
• API Gateway (http://localhost:8080) - NGINX reverse proxy
• User Service (http://localhost:3000) - User authentication & management
• Catalogue Service (http://localhost:8081) - Product catalog
• Carts Service (http://localhost:8082) - Shopping cart management
• Orders Service (http://localhost:8083) - Order processing
• Payment Service (http://localhost:8084) - Payment processing
• Fulfillment Service (http://localhost:8085) - Order fulfillment
• Assets Service (http://localhost:3001) - Product images & static assets
• Events Service (http://localhost:8087) - Event streaming integration
• Newsletter Service (http://localhost:3002) - Newsletter subscriptions

Infrastructure Services:

• PostgreSQL (ports 5432-5435) - 4 database instances for different services
• MinIO (http://localhost:9000, Console: http://localhost:9001) - S3-compatible object storage
• Apache Kafka (localhost:9092) - Event streaming
• Zookeeper (localhost:2181) - Kafka coordination
• NATS (localhost:4222) - Messaging for orders/fulfillment
• Mailhog (UI: http://localhost:8025, SMTP: 1025) - Email testing

# Check all services are running
docker-compose ps

# View logs for all services
docker-compose logs -f

# View logs for a specific service
docker-compose logs -f storefront

# Check service health
curl http://localhost:8086  # Storefront
curl http://localhost:3000/health  # User service
curl http://localhost:3002/health  # Newsletter service

1. Browse Products: Navigate to http://localhost:8086
2. Create Account: Click "Sign In" → "Register" to create a user
3. Add to Cart: Browse products and add items to your cart
4. Checkout: Complete the purchase flow
5. Subscribe to Newsletter: Enter email in the newsletter form
6. View Emails: Check http://localhost:8025 (Mailhog) to see subscription emails

PostgreSQL Databases:

# User database
psql -h localhost -p 5432 -U mushop -d mushop_user

# Catalogue database
psql -h localhost -p 5433 -U mushop -d mushop_catalogue

# Carts database
psql -h localhost -p 5434 -U mushop -d mushop_carts

# Orders database
psql -h localhost -p 5435 -U mushop -d mushop_orders

# Password for all: mushop

MinIO Object Storage:

# Access MinIO Console
open http://localhost:9001

# Credentials:
# Username: minioadmin
# Password: minioadmin

Mailhog (Email Testing):

# View sent emails
open http://localhost:8025

Kafka Topics:

# List topics
docker-compose exec kafka kafka-topics \
  --bootstrap-server localhost:9092 --list

# Consume events
docker-compose exec kafka kafka-console-consumer \
  --bootstrap-server localhost:9092 \
  --topic mushop-events --from-beginning

# Stop all services (keeps data)
docker-compose stop

# Start services again
docker-compose start

# Restart a specific service
docker-compose restart storefront

# View resource usage
docker stats

# Rebuild a service after code changes
docker-compose build user
docker-compose up -d user

# Scale a service (e.g., run 3 catalogue instances)
docker-compose up -d --scale catalogue=3

# Stop and remove all containers
docker-compose down

# Remove containers, networks, and volumes (complete cleanup)
docker-compose down -v

# Remove all images as well
docker-compose down -v --rmi all

Services not starting:

# Check logs for errors
docker-compose logs

# Restart all services
docker-compose restart

# Rebuild and restart
docker-compose up -d --build

Database connection errors:

# Check PostgreSQL is ready
docker-compose exec postgres-user pg_isready -U mushop

# Restart database and dependent service
docker-compose restart postgres-user user

Port conflicts:

# If ports are already in use, modify docker-compose.yml
# Change the first port number (host port) to something else
# Example: "8086:80" → "8090:80"

Out of memory:

# Increase Docker memory allocation in Docker Desktop preferences
# Recommended: At least 8GB RAM

📖 See DOCKER-COMPOSE-README.md for complete local development guide and advanced topics

# Using Helm (recommended)
helm install mushop ./deploy/complete/helm-chart/mushop \
  --set global.postgres.host=your-postgres-host \
  --set global.postgres.password=your-password

# Or using kubectl
kubectl apply -f deploy/complete/kubernetes/

📖 See MIGRATION-SUMMARY.md for complete migration details

MuShop can also be deployed on Oracle Cloud Infrastructure using OCI-managed services. Both deployment models can be used with trial subscriptions. However, Oracle Cloud Infrastructure offers an Always Free tier with resources that can be used indefinitely.

Basic: deploy/basic	Complete: deploy/complete
Simplified runtime utilizing only Always Free eligible resources. Deploy using:  1. Terraform  2. Resource Manager following the steps below  3. (Recommended) Button below - launches in Resource Manager directly	Polyglot set of micro-services deployed on Kubernetes, showcasing Oracle Cloud Native technologies and backing services. Deploy using:  1. Helm  2. Terraform  3. Resource Manager  4. (Recommended) Button below - launches in Resource Manager directly

mushop
└── deploy
    ├── basic
    └── complete

This is a Terraform configuration that deploys the MuShop basic sample application on Oracle Cloud Infrastructure and is designed to run using only the Always Free tier resources.

The repository contains the application code as well as the Terraform code to create a Resource Manager stack, that creates all the required resources and configures the application on the created resources. To simplify getting started, the Resource Manager Stack is created as part of each release

The steps below guide you through deploying the application on your tenancy using the OCI Resource Manager.

1. Download the latest mushop-basic-stack-latest.zip file.
2. Login to Oracle Cloud Infrastructure to import the stack

   Home > Developer Services > Resource Manager > Stacks > Create Stack

3. Upload the mushop-basic-stack-latest.zip file that was downloaded earlier, and provide a name and description for the stack
4. Configure the stack
   1. Database Name - You can choose to provide a database name (optional)
   2. Node Count - Select if you want to deploy one or two application instances.
   3. SSH Public Key - (Optional) Provide a public SSH key if you wish to establish SSH access to the compute node(s).
5. Review the information and click Create button.

   The upload can take a few seconds, after which you will be taken to the newly created stack

6. On Stack details page, click on Terraform Actions > Apply

All the resources will be created, and the URL to the load balancer will be displayed as lb_public_url as in the example below.

The same information is displayed on the Application Information tab

Outputs:

autonomous_database_password = <generated>

comments = The application URL will be unavailable for a few minutes after provisioning, while the application is configured

dev = Made with ❤ by Oracle Developers

lb_public_url = http://xxx.xxx.xxx.xxx

The application is being deployed to the compute instances asynchronously, and it may take a couple of minutes for the URL to serve the application.

Even though it is Always Free, you will likely want to terminate the demo application in your Oracle Cloud Infrastructure tenancy. With the use of Terraform, the Resource Manager stack is also responsible for terminating the application.

Follow these steps to completely remove all provisioned resources:

1. Return to the Oracle Cloud Infrastructure Console

Home > Developer Services > Resource Manager > Stacks

1. Select the stack created previously to open the Stack Details view
2. From the Stack Details, select Terraform Actions > Destroy
3. Confirm the Destroy job when prompted

The job status will be In Progress while resources are terminated

1. Once the destroy job has succeeded, return to the Stack Details page
2. Click Delete Stack and confirm when prompted

The following diagram shows the topology created by this stack.

MuShop Complete is a polyglot micro-services application built to showcase a cloud native approach to application development on Oracle Cloud Infrastructure using Oracle's cloud native services. MuShop Complete uses a Kubernetes cluster, and can be deployed using the provided helm charts (preferred), or Kubernetes manifests. It is recommended to use an Oracle Container Engine for Kubernetes cluster, however other Kubernetes distributions will also work.

The helm chart documentation walks through the deployment process and various options for customizing the deployment.

The following diagram shows the topology created by this stack.

This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide

Please consult the security guide for our responsible security vulnerability disclosure process

If you have an issue or a question, please take a look at our FAQs or open an issue.

Copyright (c) 2019 Oracle and/or its affiliates.

Released under the Universal Permissive License v1.0 as shown at https://oss.oracle.com/licenses/upl/.