WPetition/DOCKER_README.md

Docker Setup Guide

Overview

This project uses Docker Compose to run both the frontend and API in containers with Nginx as a unified gateway.

Architecture

┌─────────────────────────────────────────┐
│  Browser (localhost:8080)               │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│  Nginx Container                        │
│  - Serves static frontend files         │
│  - Proxies /api/* to backend            │
│  - Proxies /swagger to backend          │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│  .NET API Container                     │
│  - ASP.NET Core 9.0                     │
│  - Connects to MongoDB on host          │
└─────────────────────────────────────────┘

Prerequisites

• Docker Desktop installed and running
• MongoDB running on your host machine (port 27017)
• Port 9755 available on your host

Quick Start

1. Build and Start Containers

docker compose build
docker compose up -d

2. Access the Application

• Frontend: http://localhost:9755
• API (via proxy): http://localhost:9755/api/*
• Swagger UI: http://localhost:9755/swagger

3. View Logs

# View all logs
docker compose logs -f

# View specific service logs
docker compose logs -f nginx
docker compose logs -f submission.api

4. Stop Containers

docker compose down

Making Changes

Frontend Changes (HTML/CSS/JS)

1. Edit files in the Frontend/ directory
2. Rebuild the nginx container:

   docker compose build nginx && docker compose up -d
   

API Changes (.NET/C# Code)

1. Edit files in the Submission.Api/ directory
2. Rebuild the API container:

   docker compose build submission.api && docker compose up -d
   

Both Frontend and API Changed

docker compose build && docker compose up -d

Common Commands

Container Management

# Start containers
docker compose up -d

# Stop containers
docker compose down

# Restart containers
docker compose restart

# View running containers
docker compose ps

# Remove all containers and volumes
docker compose down -v

Logs and Debugging

# Follow all logs
docker compose logs -f

# View last 50 lines of API logs
docker compose logs --tail=50 submission.api

# View last 50 lines of Nginx logs
docker compose logs --tail=50 nginx

# Execute command inside API container
docker compose exec submission.api /bin/bash

Rebuilding

# Rebuild all containers
docker compose build

# Rebuild with no cache (clean build)
docker compose build --no-cache

# Rebuild specific service
docker compose build nginx
docker compose build submission.api

Configuration

MongoDB Connection

The API connects to MongoDB on your host machine using host.docker.internal:27017.

To change the MongoDB connection:

1. Edit compose.yaml
2. Update the MongoDbSettings__ConnectionString environment variable
3. Restart containers

environment:
  - MongoDbSettings__ConnectionString=mongodb://host.docker.internal:27017

Port Configuration

The application is exposed on port 9755. To change this:

1. Edit compose.yaml
2. Update the nginx ports mapping:

   ports:
     - "9755:80"  # Change 9755 to your desired port
   

3. Restart containers

API Base URL (Frontend)

The frontend API configuration is in Frontend/index.html at line 105:

const API_CONFIG = {
    baseUrl: ''  // Empty for same-origin requests
};

This is set to empty because Nginx proxies all /api/* requests to the backend.

File Structure

.
├── compose.yaml                    # Docker Compose configuration
├── nginx/
│   ├── Dockerfile                  # Nginx container definition
│   └── nginx.conf                  # Nginx configuration
├── Frontend/                       # Static frontend files
│   ├── index.html
│   ├── style.css
│   └── fonts/
└── Submission.Api/
    ├── Dockerfile                  # API container definition
    └── ...                         # .NET source files

Troubleshooting

MongoDB Connection Issues

Problem: API can't connect to MongoDB on host

Solution:

1. Verify MongoDB is running on host: mongosh --eval "db.version()"
2. Check MongoDB is listening on 0.0.0.0:27017 not just 127.0.0.1
3. Check Windows Firewall isn't blocking the connection
4. Verify the connection string in compose.yaml uses host.docker.internal

Port 9755 Already in Use

Problem: Error binding to port 9755

Solution:

1. Find what's using the port: netstat -ano | findstr :9755
2. Either stop that process or change the port in compose.yaml

Container Won't Start

Problem: Container crashes on startup

Solution:

# Check logs for errors
docker compose logs submission.api

# Rebuild with no cache
docker compose build --no-cache

# Remove old containers and rebuild
docker compose down
docker compose up -d

Changes Not Reflected

Problem: Code changes don't appear after rebuild

Solution:

# Force rebuild and restart
docker compose down
docker compose build --no-cache
docker compose up -d

Nginx 502 Bad Gateway

Problem: Nginx can't reach the API

Solution:

1. Check API container is running: docker compose ps
2. Check API logs: docker compose logs submission.api
3. Verify API is listening on port 8080
4. Check both containers are on the same network

Production Deployment

For production deployment:

1. Update API base URL: Change port 8080 to 80 (or use a reverse proxy)
2. MongoDB: Use a proper MongoDB connection string with authentication
3. HTTPS: Add SSL certificates to Nginx configuration
4. Environment variables: Use .env file for sensitive configuration
5. Logging: Configure proper log aggregation
6. Health checks: Add Docker health checks to compose.yaml

Example Production Changes

# compose.yaml
services:
  nginx:
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./ssl:/etc/nginx/ssl:ro

  submission.api:
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - MongoDbSettings__ConnectionString=${MONGODB_CONNECTION_STRING}

Additional Resources

• Docker Compose Documentation
• Nginx Documentation
• ASP.NET Core in Docker

Support

For issues or questions:

1. Check container logs: docker compose logs -f
2. Verify all services are running: docker compose ps
3. Review this documentation
4. Check Docker Desktop is running and healthy