my_openplace/DOCKER.md

Docker Setup Guide

This guide explains how to build and run Openplace using Docker.

Quick Start

Prerequisites

• Docker Engine 20.10+
• Docker Compose 2.0+

Basic Usage

1. Build and start all services:

   docker-compose up -d
   

2. View logs:

   docker-compose logs -f app
   

3. Stop services:

   docker-compose down
   

4. Stop and remove volumes (deletes database):

   docker-compose down -v
   

Configuration

Environment Variables

The easiest way to configure the application is to copy .env.docker to .env:

cp .env.docker .env

Then edit .env to customize:

• PORT - Application port (default: 3000)
• MYSQL_* - Database configuration
• JWT_SECRET - IMPORTANT: Change this in production!

Production Deployment

For production, you should:

1. Change the JWT secret:

   JWT_SECRET="your-secure-random-secret-here"
   

2. Change database passwords:

   MYSQL_ROOT_PASSWORD="secure-root-password"
   MYSQL_PASSWORD="secure-app-password"
   

3. Use a reverse proxy (nginx/traefik) for SSL/HTTPS

4. Set up regular database backups

Docker Commands

Building

# Build the application image
docker-compose build

# Build without cache
docker-compose build --no-cache

Using the precompiled frontend

If you want to serve the legacy bundle in frontend-backup/ instead of rebuilding frontend-src, set the build argument while building the image:

USE_FRONTEND_BACKUP=true docker-compose build

With USE_FRONTEND_BACKUP=true the Dockerfile skips the frontend build step and copies the existing frontend-backup/ files into /app/frontend inside the image.

Running

# Start in foreground
docker-compose up

# Start in background
docker-compose up -d

# Start only specific services
docker-compose up -d mysql

Monitoring

# View logs
docker-compose logs -f

# View app logs only
docker-compose logs -f app

# Check service status
docker-compose ps

Database Management

# Access MySQL shell
docker-compose exec mysql mysql -u openplace -p

# Run migrations
docker-compose exec app pnpm db:push

# Seed database
docker-compose exec app pnpm seed

# Backup database
docker-compose exec mysql mysqldump -u openplace -popenplacepassword openplace > backup.sql

# Restore database
docker-compose exec -T mysql mysql -u openplace -popenplacepassword openplace < backup.sql

Maintenance

# Restart services
docker-compose restart

# Restart specific service
docker-compose restart app

# View resource usage
docker stats openplace-app openplace-mysql

# Clean up unused images
docker image prune

Standalone Docker Build

If you prefer to build without docker-compose:

# Build image
docker build -t openplace:latest .

# Run container (requires existing MySQL)
docker run -d \
  --name openplace \
  -p 3000:3000 \
  -e DATABASE_URL="mysql://user:pass@host:3306/openplace" \
  -e JWT_SECRET="your-secret" \
  openplace:latest

Development with Docker

For development, you may want to mount your source code:

docker-compose -f docker-compose.dev.yml up

Or use the regular local development setup:

pnpm install
pnpm dev

Troubleshooting

Database connection fails

Wait a few seconds for MySQL to initialize on first run. Check logs:

docker-compose logs mysql

Port already in use

Change the port in .env:

PORT=3001

Permission issues

On Linux, you may need to adjust file permissions:

sudo chown -R $(id -u):$(id -g) .

Clear everything and restart

docker-compose down -v
docker-compose up -d --build

Architecture

The Docker setup consists of:

• openplace-app: Node.js application container running the backend
• openplace-mysql: MySQL 8.0 database container
• mysql-data: Persistent volume for database storage
• openplace-network: Bridge network for container communication

The application automatically runs database migrations on startup.