Skip to main content
While the project doesn’t include a docker-compose.yml file by default, the Makefile includes commands for managing Docker Compose services, primarily for running MongoDB locally.

​
Docker Requirements

You’ll need Docker and Docker Compose installed:
  • Docker Desktop (includes Docker Compose)
  • Or Docker Engine + Docker Compose plugin

​
Creating docker-compose.yml

Create a backend/docker-compose.yml file to run MongoDB locally: 
version: '3.8'

services:
  mongodb:
    image: mongo:7.0
    container_name: go-react-scaffold-mongo
    restart: unless-stopped
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: password
    volumes:
      - mongodb_data:/data/db
    networks:
      - app-network

  # Optional: Redis for session storage
  redis:
    image: redis:7-alpine
    container_name: go-react-scaffold-redis
    restart: unless-stopped
    ports:
      - "6379:6379"
    networks:
      - app-network

volumes:
  mongodb_data:
    driver: local

networks:
  app-network:
    driver: bridge

​
Makefile Docker Commands

The backend/Makefile provides convenient commands for managing Docker services:

​
Start Services

make docker-run
Starts all services defined in docker-compose.yml. This command:
  • Tries docker compose up (Docker Compose V2)
  • Falls back to docker-compose up (Docker Compose V1) if V2 is not available
  • Runs in attached mode (shows logs in terminal)
For background mode, modify the command: 
# Run in detached mode
docker compose up -d
# or
make docker-run -d

​
Stop Services

make docker-down
Stops and removes all containers defined in docker-compose.yml. This command:
  • Tries docker compose down (Docker Compose V2)
  • Falls back to docker-compose down (Docker Compose V1)
  • Preserves volumes (data persists)
To remove volumes and delete all data, use:
docker compose down -v

​
Environment Configuration

Update your backend/.env to connect to the Docker MongoDB instance: 
# Without authentication
MONGODB_URI=mongodb://localhost:27017

# With authentication (if configured)
MONGODB_URI=mongodb://admin:password@localhost:27017

# Redis
REDIS_URL=redis://localhost:6379

​
Docker Compose V1 vs V2

The Makefile commands automatically handle both versions:
  • V2 (newer): docker compose - Plugin-based, included in Docker Desktop
  • V1 (older): docker-compose - Standalone binary
You can check which version you have: 
# Check for V2
docker compose version

# Check for V1
docker-compose --version

​
Useful Docker Commands

View running containers: 
docker ps
View logs: 
# All services
docker compose logs

# Specific service
docker compose logs mongodb

# Follow logs
docker compose logs -f
Connect to MongoDB shell: 
docker exec -it go-react-scaffold-mongo mongosh
Restart services: 
docker compose restart
Remove everything (containers, volumes, networks): 
docker compose down -v

​
MongoDB Data Persistence

Data is persisted in a named Docker volume (mongodb_data). This means:
  • Data survives container restarts
  • Data survives docker-down and docker-run cycles
  • Data is only deleted with docker compose down -v or manual volume deletion
View volumes: 
docker volume ls
Inspect volume: 
docker volume inspect mongodb_data

​
Production Considerations

The Docker setup described here is for local development only. For production:
  1. Use a managed MongoDB service (MongoDB Atlas, AWS DocumentDB)
  2. Implement proper authentication and authorization
  3. Use environment-specific credentials
  4. Enable SSL/TLS for database connections
  5. Configure backups and monitoring
  6. Use container orchestration (Kubernetes, ECS, etc.)

​
Troubleshooting

​
Port Already in Use

If port 27017 or 6379 is already in use: 
services:
  mongodb:
    ports:
      - "27018:27017"  # Use different host port
Update your .env: 
MONGODB_URI=mongodb://localhost:27018

​
Permission Denied

On Linux, you may need to add your user to the docker group: 
sudo usermod -aG docker $USER
# Log out and back in for changes to take effect

​
Container Won’t Start

Check logs for errors: 
docker compose logs mongodb
Common issues:
  • Port conflict (see above)
  • Insufficient disk space
  • Corrupted volume (remove and recreate)

​
Clean Slate

To completely reset: 
# Stop everything
make docker-down

# Remove volumes
docker volume rm mongodb_data

# Start fresh
make docker-run

Build docs developers (and LLMs) love

Get started for freeTalk to us