Skip to content

AzharStore Infrastructure Setup Guide

This guide covers the complete setup of the AzharStore Medusa v2 backend infrastructure using Docker Compose.

Prerequisites

Before starting, ensure you have the following installed on your system:

  • Docker: Version 20.10 or higher
  • Docker Compose: Version 2.0 or higher
  • Node.js: Version 20 or higher (for local development)
  • Git: For cloning the repository

Verify your installations: 

docker --version
docker compose version
node --version
git --version

Repository Structure

az-main/
├── backend/              # MedusaJS v2 backend
│   ├── src/
│   │   ├── modules/     # Custom modules (advertisement, settings, translation)
│   │   ├── api/         # Custom API routes
│   │   └── workflows/   # Custom workflows
│   ├── scripts/         # Utility scripts (seed-admin, migration)
│   └── Dockerfile
├── frontend/
│   └── store/           # React store frontend
│       └── Dockerfile
├── nginx/
│   └── store.conf       # Nginx configuration
├── docs/                # Documentation
└── docker-compose.yml   # Docker services orchestration

Quick Start

1. Clone the Repository

git clone <repository-url>
cd az-main

2. Configure Environment Variables

Copy the example environment file and fill in your values:

cp .env.example .env

Edit .env and set the following required values:

# Generate secure secrets using: openssl rand -base64 32
JWT_SECRET=your_jwt_secret_minimum_32_characters
COOKIE_SECRET=your_cookie_secret_minimum_32_characters

# Set your admin credentials
MEDUSA_ADMIN_EMAIL=admin@azharstore.com
MEDUSA_ADMIN_PASSWORD=your_secure_admin_password_here

# Set PostgreSQL password
POSTGRES_PASSWORD=your_secure_postgres_password_here

# Update CORS origins for your domain
STORE_CORS=http://localhost:8080,https://your-store-domain.com
ADMIN_CORS=http://localhost:9000,https://your-admin-domain.com

3. Start All Services

docker compose up -d

This command will: - Pull and start PostgreSQL 16 Alpine - Pull and start Redis 7 Alpine - Build and start the Medusa backend - Build and start the React store frontend

4. Verify Services are Healthy

Check that all containers are running:

docker compose ps

Expected output should show all services as "running" or "healthy".

5. Access the Applications

  • Store Frontend: http://localhost:8080
  • Medusa Admin Dashboard: http://localhost:9000/app
  • Backend API Health: http://localhost:9000/health

6. Seed Admin User

The admin user is automatically created on first boot using the credentials from .env. If you need to re-seed:

docker compose exec medusa npm run seed:admin

Service Details

PostgreSQL (postgres)

  • Image: postgres:16-alpine
  • Port: 5432
  • Volume: azharstore_postgres_data (persistent)
  • Purpose: Stores all application data (products, orders, customers, custom modules)

Redis (redis)

  • Image: redis:7-alpine
  • Port: 6379
  • Volume: azharstore_redis_data (persistent)
  • Purpose: Caching and event bus for Medusa

Medusa Backend (medusa)

  • Build: From backend/Dockerfile
  • Port: 9000
  • Depends on: postgres, redis
  • Purpose: E-commerce backend API and admin dashboard

Store Frontend (store)

  • Build: From frontend/store/Dockerfile
  • Port: 8080
  • Depends on: medusa
  • Purpose: Customer-facing React storefront

Common Operations

View Logs

View logs for all services: 

docker compose logs -f

View logs for a specific service: 

docker compose logs -f medusa
docker compose logs -f postgres
docker compose logs -f redis

Stop Services

docker compose down

Stop Services and Remove Volumes

⚠️ Warning: This will delete all data in the database.

docker compose down -v

Restart a Specific Service

docker compose restart medusa

Rebuild a Service

After making changes to the backend code:

docker compose up -d --build medusa

Access Container Shell

Access the Medusa container: 

docker compose exec medusa sh

Access PostgreSQL: 

docker compose exec postgres psql -U medusa -d azharstore

Troubleshooting

Port Already in Use

If you get "port already in use" errors, change the port mappings in docker-compose.yml or stop the conflicting service.

Database Connection Errors

Ensure PostgreSQL is healthy before starting Medusa: 

docker compose ps postgres

Permission Issues

If you encounter permission issues with volumes, ensure Docker has proper access to the mounted directories.

Build Failures

If the build fails, try: 

docker compose down
docker system prune -a
docker compose up -d --build

Production Deployment

For production deployment on a Linux VPS:

  1. Update CORS origins in .env to your production domain
  2. Use strong, randomly generated secrets
  3. Configure SSL/TLS using a reverse proxy (e.g., Nginx with Let's Encrypt)
  4. Set up regular database backups
  5. Configure monitoring and alerting
  6. Review and adjust resource limits in docker-compose.yml

Next Steps

After completing this setup: 1. Proceed to Modules to learn about custom modules 2. Refer to Docker Services for detailed Docker service information 3. Check Environment Variables for complete environment variable reference