Skip to content

Latest commit

 

History

History
350 lines (259 loc) · 8.83 KB

DOCKER.md

File metadata and controls

350 lines (259 loc) · 8.83 KB

Docker Deployment Guide

This guide explains how to run TreeBASE using Docker with support for rapid JSP development.

Prerequisites

  • Docker 20.10 or later (includes Docker Compose v2)
  • At least 4GB of free RAM
  • At least 10GB of free disk space

Note: This guide uses docker compose (with a space), which is the modern Docker Compose v2 syntax. If you have an older standalone docker-compose (with a hyphen), the commands will also work.

Quick Start - Development Mode with JSP Hot-Reload

This is the recommended approach for UI development as it allows you to edit JSP files locally and see changes immediately:

# Option 1: Use the quick-start script (easiest)
./docker/quick-start.sh

# Option 2: Manual start
docker compose --profile development up

# Wait for the build to complete (first time takes 5-10 minutes)
# Once you see "Tomcat started", access the application at:
# http://localhost:8080/treebase-web/

Editing JSP Files

  1. Edit any JSP file in treebase-web/src/main/webapp/ using your favorite editor
  2. Save the file
  3. Refresh your browser - that's it!

For example, to modify the homepage:

# Edit the index page
vim treebase-web/src/main/webapp/index.jsp

# Or use your preferred editor
code treebase-web/src/main/webapp/index.jsp

The changes will be reflected immediately without rebuilding or restarting Docker containers.

What Can You Edit Live?

✅ JSP files - Instant refresh on save
✅ CSS files - Instant refresh
✅ JavaScript files - Instant refresh
✅ Images and static resources - Instant refresh
❌ Java source files - Requires container restart

To rebuild after Java changes:

docker compose --profile development restart web-dev

Production Mode

For a production-like deployment with a fully self-contained image:

# Build and start production environment
docker compose --profile production up --build

This creates an optimized Docker image with the WAR file built inside.

Architecture Overview

Development Setup

  • Mounts local treebase-web/src/main/webapp/ directory as a Docker volume
  • Tomcat automatically recompiles JSP files when they change
  • Includes Maven and build tools inside container
  • PostgreSQL database runs in a separate container

Production Setup

  • Multi-stage Docker build
  • WAR file compiled during image creation
  • No external file dependencies
  • Optimized runtime-only image

Common Commands

Start Services

# Development mode (with JSP hot-reload)
docker compose --profile development up

# Production mode
docker compose --profile production up

# Run in background (detached mode)
docker compose --profile development up -d

Stop Services

docker compose down

# Also remove volumes (database data will be lost!)
docker compose down -v

View Logs

# All services
docker compose --profile development logs -f

# Just web application
docker compose --profile development logs -f web-dev

# Just database
docker compose logs -f postgres

Rebuild Application

# Clean rebuild (development mode)
docker compose --profile development down -v
docker compose --profile development up --build

# Rebuild production image
docker compose --profile production build --no-cache

Access Database

# Connect to PostgreSQL
docker exec -it treebase-postgres psql -U treebase -d treebase

# From host (if you have psql installed)
psql -h localhost -U treebase -d treebase
# Password: treebase

Shell Access

# Access web container
docker exec -it treebase-web-dev bash

# Access database container  
docker exec -it treebase-postgres bash

File Structure

.
├── Dockerfile              # Production build (multi-stage)
├── Dockerfile.dev          # Development build with tools
├── docker compose.yml      # Service orchestration
├── .dockerignore          # Files excluded from build
├── DOCKER.md              # This file
└── docker/
    ├── README.md          # Detailed documentation
    ├── context.xml        # Tomcat JNDI configuration
    └── entrypoint-dev.sh  # Development startup script

Configuration

Environment Variables (Optional)

You can customize settings using a .env file:

# Copy the example
cp .env.example .env

# Edit with your preferences
vim .env

The .env file is automatically loaded by Docker Compose. Variables include:

  • Database credentials
  • Application port
  • Java options
  • Site URLs

Database Settings

Default credentials (development only):

  • Host: localhost:5432
  • Database: treebase
  • Username: treebase
  • Password: treebase

To change credentials, edit:

  • docker compose.yml - environment variables for PostgreSQL
  • docker/context.xml - JDBC connection settings

Application Settings

Configuration is in docker/context.xml:

  • Database connection (JNDI DataSource)
  • Mesquite folder location
  • Site URL
  • SMTP settings for email

Port Mapping

By default, the application runs on port 8080. To use a different port:

# In docker compose.yml, change:
    ports:
      - "9090:8080"  # Use port 9090 instead

Troubleshooting

Problem: Container fails to start

Solution:

# Check logs for errors
docker compose --profile development logs

# Verify Docker is running
docker ps

# Check available resources
docker system df

Problem: JSP changes not appearing

Solutions:

  1. Hard refresh browser (Ctrl+F5 or Cmd+Shift+R)
  2. Clear browser cache
  3. Verify you're editing the correct file in treebase-web/src/main/webapp/
  4. Check file permissions (should be readable)

Problem: Database connection failed

Solutions:

# Verify PostgreSQL is running
docker compose ps postgres

# Check PostgreSQL logs
docker compose logs postgres

# Verify credentials match in docker compose.yml and docker/context.xml

Problem: Out of memory

Solutions:

  • Increase Docker memory allocation (Docker Desktop → Settings → Resources)
  • Increase JVM heap size in docker compose.yml: 
    environment:
  CATALINA_OPTS: "-Xmx1024m ..."  # Increase from 512m

Problem: Build fails downloading dependencies

Solution:

# Clear Maven cache and retry
docker compose --profile development down -v
docker compose --profile development up --build

Problem: Port already in use

Solution:

# Find what's using port 8080
lsof -i :8080  # macOS/Linux
netstat -ano | findstr :8080  # Windows

# Either:
# 1. Stop the other service, or
# 2. Change port in docker compose.yml

Performance Tips

First Run

The development environment builds the entire project on first start. This can take 5-10 minutes depending on:

  • Internet speed (Maven downloads ~200MB of dependencies)
  • CPU speed (compilation)
  • Disk I/O

Subsequent starts are much faster (30 seconds) as dependencies are cached.

Maven Dependency Caching

The maven-repo volume persists Maven dependencies between container restarts, significantly speeding up rebuilds.

JSP Compilation Performance

JSP files are compiled on-demand. First access after editing may take 1-2 seconds, but subsequent requests are instantaneous.

Security Considerations

⚠️ This configuration is for DEVELOPMENT ONLY

For production deployments:

  1. Change all default passwords
  2. Use environment variables for sensitive data
  3. Enable SSL/TLS
  4. Restrict database network access
  5. Review and harden Tomcat security settings
  6. Update all dependencies to latest secure versions
  7. Don't expose database port to public network

Advanced Usage

Custom Database Initialization

Place SQL scripts in the database init directory:

# Add to docker compose.yml volumes:
      - ./my-init-script.sql:/docker-entrypoint-initdb.d/03-custom.sql

Using a Different PostgreSQL Version

# In docker compose.yml:
  postgres:
    image: postgres:14  # or postgres:13, etc.

Multi-stage Development

Run database separately for multiple projects:

# Start only database
docker compose up postgres

# Use from multiple TreeBASE checkouts

Getting Help

  • Validation: Run ./docker/validate-setup.sh to check your setup
  • Testing: See docker/TESTING.md for comprehensive test procedures
  • Quick Start: Run ./docker/quick-start.sh for guided setup
  • Detailed Docs: See docker/README.md for detailed documentation
  • GitHub Issues: https://github.com/TreeBASE/treebase/issues
  • Build Guide: doc/development/BUILDING.md
  • Deployment Guide: doc/development/DEPLOYING.md

Related Documentation