Skip to main content

​
Overview

Voxora uses Docker Compose to run essential services for local development:
  • MongoDB - Primary database
  • Redis - Caching and sessions
  • Mongo Express - Database admin UI
  • MailHog - Email testing

​
Docker Compose Configuration

The configuration file is located at docker/docker-compose.dev.yml:
docker-compose.dev.yml
version: '3.8'

services:
  mongodb:
    image: mongo:latest
    container_name: voxora-mongodb
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: password
      MONGO_INITDB_DATABASE: voxora
    volumes:
      - mongodb_data:/data/db
    networks:
      - voxora-network

  redis:
    image: redis:alpine
    container_name: voxora-redis
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    networks:
      - voxora-network

  mongo-express:
    image: mongo-express:latest
    container_name: voxora-mongo-express
    ports:
      - "8081:8081"
    environment:
      ME_CONFIG_MONGODB_ADMINUSERNAME: admin
      ME_CONFIG_MONGODB_ADMINPASSWORD: password
      ME_CONFIG_MONGODB_URL: mongodb://admin:password@mongodb:27017/
      ME_CONFIG_BASICAUTH_USERNAME: admin
      ME_CONFIG_BASICAUTH_PASSWORD: pass
    depends_on:
      - mongodb
    networks:
      - voxora-network

  mailhog:
    image: mailhog/mailhog
    container_name: voxora-mailhog
    ports:
      - "1025:1025"  # SMTP
      - "8025:8025"  # Web UI
    networks:
      - voxora-network

volumes:
  mongodb_data:
  redis_data:

networks:
  voxora-network:
    driver: bridge

​
Quick Commands

​
Start Services

npm run docker:start
# or
docker-compose -f docker/docker-compose.dev.yml up -d

​
Stop Services

npm run docker:stop
# or
docker-compose -f docker/docker-compose.dev.yml down

​
Restart Services

docker-compose -f docker/docker-compose.dev.yml restart

​
Service Details

​
MongoDB

MongoDB 27017

NoSQL database for storing application data
Connection Details:
  • Host: localhost
  • Port: 27017
  • Username: admin
  • Password: password
  • Database: voxora
Connection String: 
mongodb://admin:password@localhost:27017/voxora?authSource=admin
Useful Commands: 
docker exec -it voxora-mongodb mongosh -u admin -p password
Common MongoDB Commands: 
// Show databases
show dbs

// Use voxora database
use voxora

// Show collections
show collections

// Find all users
db.users.find()

// Find one conversation
db.conversations.findOne()

// Count messages
db.messages.countDocuments()

// Create index
db.messages.createIndex({ conversationId: 1, createdAt: -1 })

​
Redis

Redis 6379

In-memory data store for caching and sessions
Connection Details:
  • Host: localhost
  • Port: 6379
  • Password: None (development only)
Useful Commands: 
docker exec -it voxora-redis redis-cli
Common Redis Commands: 
# List all keys
KEYS *

# Get value
GET session:abc123

# Set value with expiry
SETEX cache:users 3600 "data"

# Delete key
DEL session:xyz789

# Clear all data
FLUSHALL

# Get info
INFO

# Monitor commands
MONITOR

​
Mongo Express

Mongo Express 8081

Web-based MongoDB admin interface
Access: http://localhost:8081 Login Credentials:
  • Username: admin
  • Password: pass
Features:
  • View and edit documents
  • Create/drop databases and collections
  • Import/export data
  • Run queries
  • View indexes

​
MailHog

MailHog 8025

Email testing tool with SMTP server and web UI
Web UI: http://localhost:8025 SMTP Details:
  • Host: localhost
  • Port: 1025
  • No authentication required
Features:
  • View all sent emails
  • Search emails
  • Delete emails
  • Download emails as .eml
Test Sending Email: 
import nodemailer from 'nodemailer';

const transporter = nodemailer.createTransporter({
  host: 'localhost',
  port: 1025,
  secure: false
});

await transporter.sendMail({
  from: 'test@voxora.local',
  to: 'user@example.com',
  subject: 'Test Email',
  html: '<p>Hello from Voxora!</p>'
});

​
Managing Data

​
Backup Data

# Export database
docker exec voxora-mongodb mongodump \
  -u admin -p password \
  --authenticationDatabase admin \
  -d voxora \
  -o /backup

# Copy to host
docker cp voxora-mongodb:/backup ./backup

​
Restore Data

# Copy backup to container
docker cp ./backup voxora-mongodb:/backup

# Restore database
docker exec voxora-mongodb mongorestore \
  -u admin -p password \
  --authenticationDatabase admin \
  -d voxora \
  /backup/voxora

​
Reset Data

This will delete all data! Use with caution.
# Stop services and remove volumes
npm run docker:stop
docker-compose -f docker/docker-compose.dev.yml down -v

# Start fresh
npm run docker:start

​
Health Checks

Check if services are running: 
docker ps
Expected output: 
CONTAINER ID   IMAGE              STATUS          PORTS
abc123...      mongo:latest       Up 5 minutes    0.0.0.0:27017->27017/tcp
def456...      redis:alpine       Up 5 minutes    0.0.0.0:6379->6379/tcp
ghi789...      mongo-express      Up 5 minutes    0.0.0.0:8081->8081/tcp
jkl012...      mailhog/mailhog    Up 5 minutes    0.0.0.0:1025->1025/tcp, 0.0.0.0:8025->8025/tcp

​
Troubleshooting

Find and stop the conflicting process:
# macOS/Linux
lsof -i :27017
kill -9 <PID>

# Or change port in docker-compose.dev.yml
ports:
  - "27018:27017"  # Use 27018 on host
Check logs for errors:
docker logs voxora-mongodb
docker logs voxora-redis
Remove and recreate:
docker-compose -f docker/docker-compose.dev.yml rm -f mongodb
docker-compose -f docker/docker-compose.dev.yml up -d mongodb
Verify container is running:
docker ps | grep mongo
Test connection:
docker exec -it voxora-mongodb mongosh -u admin -p password
Check connection string in .env matches Docker config.
Ensure MongoDB is fully started before Mongo Express:
docker-compose -f docker/docker-compose.dev.yml restart mongo-express
Clean up Docker resources:
# Remove unused images
docker image prune -a

# Remove unused volumes
docker volume prune

# Remove everything unused
docker system prune -a --volumes

​
Production Considerations

Do not use these Docker configurations in production! They are designed for local development only.
For production:

MongoDB Atlas

Use a managed MongoDB service

Redis Cloud

Use a managed Redis service

SendGrid/SES

Use a transactional email service

Cloud Storage

Use S3 or Azure Blob Storage

​
Next Steps

Development Setup

Complete development guide

Environment Variables

Configure your environment

Scripts Reference

All available npm scripts

Deployment

Deploy to production