AzharStore Runbook¶

This runbook provides step-by-step procedures for common operational tasks for the AzharStore Medusa backend.

Table of Contents¶

Initial Setup
Starting the Application
Stopping the Application
Database Operations
Admin User Management
Data Migration
Backup and Restore
Monitoring and Logs
Troubleshooting
Deployment

Initial Setup¶

1. Clone the Repository¶

git clone <repository-url>
cd az-main

2. Configure Environment Variables¶

cp .env.example .env

Edit .env with your configuration:

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/medusa

# Redis
REDIS_URL=redis://localhost:6379

# CORS
STORE_CORS=http://localhost:3000
ADMIN_CORS=http://localhost:9000

# Secrets
JWT_SECRET=your-jwt-secret-change-this
COOKIE_SECRET=your-cookie-secret-change-this

# Admin
ADMIN_EMAIL=admin@azhar.store
ADMIN_PASSWORD=your-admin-password-change-this

3. Start Services¶

docker compose up -d

4. Run Database Migrations¶

docker compose exec medusa npx medusa db:migrate

5. Seed Admin User¶

docker compose exec medusa npx ts-node scripts/seed-admin.ts

Starting the Application¶

Start All Services¶

docker compose up -d

Start Specific Services¶

# Start only backend
docker compose up -d postgres redis medusa

# Start only frontend
docker compose up -d store

# Start only database
docker compose up -d postgres redis

Start in Development Mode¶

# Backend development (without Docker)
cd backend
npm install
npm run dev

# Frontend development (without Docker)
cd frontend/store
npm install
npm run dev

Stopping the Application¶

Stop All Services¶

docker compose down

Stop and Remove Volumes¶

docker compose down -v

Stop Specific Services¶

docker compose stop medusa
docker compose stop store
docker compose stop postgres
docker compose stop redis

Database Operations¶

Run Migrations¶

docker compose exec medusa npx medusa db:migrate

Create a New Migration¶

docker compose exec medusa npx medusa db:create

Access PostgreSQL Shell¶

docker compose exec postgres psql -U postgres -d medusa

Backup Database¶

docker compose exec postgres pg_dump -U postgres medusa > backup.sql

Restore Database¶

cat backup.sql | docker compose exec -T postgres psql -U postgres medusa

View Database Tables¶

docker compose exec postgres psql -U postgres -d medusa -c "\dt"

Inspect Custom Tables¶

# Advertisement table
docker compose exec postgres psql -U postgres -d medusa -c "SELECT * FROM advertisement;"

# Settings table
docker compose exec postgres psql -U postgres -d medusa -c "SELECT * FROM setting;"

# Translation table
docker compose exec postgres psql -U postgres -d medusa -c "SELECT * FROM translation;"

Admin User Management¶

Create Admin User¶

docker compose exec medusa npx ts-node scripts/seed-admin.ts

This uses the ADMIN_EMAIL and ADMIN_PASSWORD from .env.

Reset Admin Password¶

Access PostgreSQL:

docker compose exec postgres psql -U postgres -d medusa

Update the admin user (adjust query based on Medusa's user table structure):

UPDATE user SET password_hash = '<new-hash>' WHERE email = 'admin@azhar.store';

Exit PostgreSQL:
```
\q
```

List Admin Users¶

docker compose exec postgres psql -U postgres -d medusa -c "SELECT id, email FROM user WHERE role = 'admin';"

Data Migration¶

Migrate from Supabase¶

Add Supabase credentials to .env:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-role-key

Run migration script:

docker compose exec medusa npx ts-node scripts/migrate-from-supabase.ts

Verify migration:

docker compose exec medusa npx ts-node scripts/verify-migration.ts

Rollback Migration¶

# Truncate custom tables
docker compose exec postgres psql -U postgres -d medusa -c "TRUNCATE TABLE advertisement, setting, translation CASCADE;"

Backup and Restore¶

Full Backup¶

# Backup database
docker compose exec postgres pg_dump -U postgres medusa > backup-$(date +%Y%m%d).sql

# Backup environment file
cp .env .env.backup

Scheduled Backup (Linux Cron)¶

Add to crontab:

0 2 * * * cd /path/to/az-main && docker compose exec postgres pg_dump -U postgres medusa > /backups/backup-$(date +\%Y\%m\%d).sql

Restore from Backup¶

# Restore database
cat backup-20240101.sql | docker compose exec -T postgres psql -U postgres medusa

# Restore environment file
cp .env.backup .env

Monitoring and Logs¶

View All Logs¶

docker compose logs -f

View Service-Specific Logs¶

# Medusa logs
docker compose logs -f medusa

# PostgreSQL logs
docker compose logs -f postgres

# Redis logs
docker compose logs -f redis

# Store logs
docker compose logs -f store

View Recent Logs (Last 100 lines)¶

docker compose logs --tail=100 medusa

Check Service Health¶

# Check if services are running
docker compose ps

# Check Medusa health
curl http://localhost:9000/health

# Check PostgreSQL connection
docker compose exec postgres pg_isready -U postgres

# Check Redis connection
docker compose exec redis redis-cli ping

Monitor Database Performance¶

# Active queries
docker compose exec postgres psql -U postgres -d medusa -c "SELECT * FROM pg_stat_activity WHERE state = 'active';"

# Table sizes
docker compose exec postgres psql -U postgres -d medusa -c "SELECT schemaname, tablename, pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) FROM pg_tables WHERE schemaname = 'public';"

Troubleshooting¶

Services Won't Start¶

Check Docker logs:
```
docker compose logs
```

Check port conflicts:

netstat -tuln | grep -E '3000|5432|6379|9000'

Restart services:

docker compose down
docker compose up -d

Database Connection Errors¶

Check PostgreSQL is running:
```
docker compose ps postgres
```
Check DATABASE_URL in .env:
```
grep DATABASE_URL .env
```

Test connection:

docker compose exec postgres psql -U postgres -d medusa -c "SELECT 1;"

Redis Connection Errors¶

Check Redis is running:
```
docker compose ps redis
```
Check REDIS_URL in .env:
```
grep REDIS_URL .env
```

Test connection:

docker compose exec redis redis-cli ping

Migration Errors¶

Check migration status:

docker compose exec medusa npx medusa db:migrate --show

Force rollback:

docker compose exec medusa npx medusa db:revert

Re-run migrations:

docker compose exec medusa npx medusa db:migrate

API Errors¶

Check CORS configuration:
```
grep CORS .env
```
Check backend logs:
```
docker compose logs medusa
```

Test API endpoint:

curl http://localhost:9000/store/translations

Frontend Not Loading¶

Check store service:
```
docker compose ps store
```
Check Nginx configuration:
```
docker compose logs store
```

Check API base URL in frontend:

grep VITE_API_BASE_URL frontend/store/.env

Deployment¶

Deploy to Production¶

Prepare Environment Variables

Create production .env file:

cp .env.example .env.production
# Edit with production values

Build Docker Images

docker compose -f docker-compose.yml build

Push to Registry (if using remote registry)

docker tag az-main-medusa:latest your-registry/az-main-medusa:latest
docker push your-registry/az-main-medusa:latest

Deploy to Server

# Copy files to server
scp -r . user@server:/path/to/az-main

# SSH into server
ssh user@server

# Navigate to project
cd /path/to/az-main

# Start services
docker compose -f docker-compose.yml up -d

Verify Deployment

# Check services
docker compose ps

# Check logs
docker compose logs -f

# Test endpoints
curl https://api.azhar.store/store/translations

Update Deployment¶

Pull Latest Code

git pull origin main

Rebuild and Restart

docker compose down
docker compose build
docker compose up -d

Run Migrations

docker compose exec medusa npx medusa db:migrate

Verify

docker compose ps
docker compose logs -f

Rollback Deployment¶

Revert Code

git checkout <previous-commit>

Rebuild and Restart

docker compose down
docker compose build
docker compose up -d

Rollback Database (if needed)

cat backup.sql | docker compose exec -T postgres psql -U postgres medusa

Maintenance Tasks¶

Daily Tasks¶

Check service logs for errors
Monitor disk space usage
Review error rates

Weekly Tasks¶

Review database performance
Check backup integrity
Review security logs

Monthly Tasks¶

Update dependencies
Review and rotate secrets
Audit user access
Test disaster recovery procedures

Security Tasks¶

Rotate Secrets¶

Generate new secrets:

# Generate JWT secret
openssl rand -base64 32

# Generate cookie secret
openssl rand -base64 32

Update .env file with new secrets

Restart services:

docker compose down
docker compose up -d

Update Dependencies¶

cd backend
npm update
npm audit fix
cd ../frontend/store
npm update
npm audit fix

SSL Certificate Renewal¶

If using Let's Encrypt with Certbot:

sudo certbot renew
sudo systemctl reload nginx

Performance Optimization¶

Clear Redis Cache¶

docker compose exec redis redis-cli FLUSHALL

Vacuum Database¶

docker compose exec postgres psql -U postgres -d medusa -c "VACUUM ANALYZE;"

Rebuild Indexes¶

docker compose exec postgres psql -U postgres -d medusa -c "REINDEX DATABASE medusa;"

Emergency Procedures¶

Emergency Shutdown¶

docker compose down

Emergency Restart¶

docker compose up -d

Database Emergency Access¶

docker compose exec postgres psql -U postgres -d medusa

Force Kill Hung Process¶

docker compose kill medusa
docker compose up -d medusa

Contact and Support¶

Documentation: See docs/ directory
Issues: Open a GitHub issue
Emergency: Contact system administrator