#Flash Legal - Container Management

✅ FULLY FUNCTIONAL: Complete container management with optimized builds and background execution

#Quick Start

#Essential Commands

# Build and run with Bun (recommended)
./manage c update Dockerfile.bun-optimized

# Build and run with Node.js  
./manage c update Dockerfile

# View logs
./manage c logs

# Stop container
./manage c stop

#Available Dockerfiles

• Dockerfile - Node.js runtime (production ready)
• Dockerfile.bun-clean - Bun runtime (faster, modern)

#Complete Command Reference

Command	Usage	Description
build	./manage c build [Dockerfile]	Build Docker image only
run	./manage c run [Dockerfile]	Build and run container (with cleanup prompt)
update	./manage c update [Dockerfile]	Full update (build + run + cleanup prompt)
stop	./manage c stop	Stop and remove container
logs	./manage c logs	View container logs (Ctrl+C to exit)
shell	./manage c shell	Open shell in running container
cleanup	./manage c cleanup	Interactive cleanup with multiple options
prune	./manage c prune	System prune (remove unused resources)
help	./manage c help	Show detailed help

#Intelligent Cleanup System 🧹

After successful run or update commands, the system automatically prompts for cleanup with these options:

#Cleanup Options

1. Remove old versions only - Keeps current image, removes previous versions
2. Remove ALL flash-legal images - Complete image cleanup (stops container first)
3. System prune - Remove unused containers, networks, and dangling images
4. Full cleanup - Stop container + remove all images + system prune
5. Skip cleanup - Continue without cleanup

#Smart Features

• 🔍 Lists current images with size and creation time
• 🛡️ Protects running containers from accidental removal
• 🎯 Selective removal - only removes what you choose
• ⚠️ Confirmation prompts for destructive operations
• 📊 Progress feedback shows what was removed

#Features

✅ Production-Ready Optimizations

• Multi-stage builds with dependency separation
• Version tagging from package.json (e.g., flash-legal:1.0.0-bun)
• Bun cache optimization (90% faster installs: 4.25s vs 36s)
• Production-only dependencies in final image
• Background container execution (no terminal blocking)
• Auto-detection of Podman/Docker runtime
• Smart error handling with detailed logging

🏗️ Multi-Stage Build Process

1. deps - Install all dependencies with caching
2. proddeps - Install production dependencies only
3. builder - Build the application with Turbo
4. runner - Final minimal runtime image

🏷️ Automatic Multi-Tag Versioning

Each build automatically creates multiple tags for the same image:

Node.js Runtime (Dockerfile):

• flash-legal:1.0.1 - Version-specific (recommended for production)
• flash-legal:latest - Generic latest (default)
• flash-legal:stable - Stable version identifier
• flash-legal:node - Runtime identifier

Bun Runtime (Dockerfile.bun-clean):

• flash-legal:1.0.1-bun - Version + runtime (recommended)
• flash-legal:latest-bun - Latest Bun version
• flash-legal:bun - Generic Bun identifier
• flash-legal:1.0.1-latest - Version + latest combo

Benefits:

• 🎯 Precise targeting - Use specific versions in production
• 🔄 Easy switching - Use convenience tags for development
• 📦 Space efficient - Multiple tags, single image
• 🏃 Quick access - Short tags like bun or latest

#Usage Examples

This will prompt you to:
1. Select action (build, run, update, etc.)
2. Choose Dockerfile if needed
3. Automatically handle the rest

### Direct Commands
```bash
# Build specific image
./manage c build Dockerfile.bun-clean

# Update (build + run)
./manage c update Dockerfile

# Container management
./manage c stop      # Stop container
./manage c logs      # View logs (press Ctrl+C to exit)
./manage c shell     # Open shell in running container
./manage c cleanup   # Remove everything

#Background Container Execution

❌ NEVER DO THIS (blocks terminal):

podman run --rm -p 3000:3000 flash-legal:1.0.0-bun

✅ ALWAYS DO THIS (runs in background):

podman run -d --name flash-legal --network host --env-file apps/flash-legal/.env flash-legal:1.0.0-bun

Our scripts automatically use background mode (-d flag) to prevent terminal blocking.

#Container Runtime Detection

The script automatically detects and uses:

• Podman (preferred) - Uses --network host
• Docker (fallback) - Uses -p 3000:3000

#Directory Structure

flash-law/
├── manage                          # Main entry point
├── scripts/
│   ├── container.sh               # Container management logic
│   ├── CONTAINER_COMMANDS.md      # This documentation
│   └── DOCKER_OPTIMIZATION_RESULTS.md  # Performance results
└── apps/flash-legal/
    ├── Dockerfile                 # Node.js runtime
    ├── Dockerfile.bun-clean       # Bun runtime
    └── .env                      # Required environment file

#Performance Results

#Build Times (with caching)

• Dependencies: ~4.25s (production), ~15s (all)
• Application build: ~28s
• Total: ~1-2 minutes

#Image Sizes

• Node.js: 1.34GB
• Bun: 1.46GB

#Runtime Performance

• Startup time: ~600ms consistently
• Memory usage: Optimized for production

#Troubleshooting

#Container Won't Start

./manage c logs  # Check container logs

#Build Fails

# Clean build (no cache)
podman system prune -f
./manage c build

#Environment Issues

Make sure apps/flash-legal/.env exists with required variables:

DATABASE_URI=mongodb://127.0.0.1:27017/flash-legal
PAYLOAD_SECRET=your-secret-here
NEXT_PUBLIC_SERVER_URL=http://localhost:3000

#Network Access

• Podman: Uses host network (automatic database access)
• Docker: Uses port mapping (may need --network host for DB)

#Best Practices

1. Always use background mode - Never run containers in foreground in scripts
2. Use versioned images - Leverage automatic version tagging
3. Interactive mode first - Try ./manage container for new users
4. Check logs regularly - Use ./manage c logs to monitor health
5. Clean up regularly - Use ./manage c cleanup to free space

#Advanced Usage

#Manual Container Operations

# Direct Podman commands
podman build -f apps/flash-legal/Dockerfile.bun-clean -t flash-legal:1.0.0-bun .
podman run -d --name flash-legal --network host --env-file apps/flash-legal/.env flash-legal:1.0.0-bun

# Check status
podman ps --filter "name=flash-legal"
podman logs flash-legal

#Script Development

The container script supports:

• Multiple Dockerfile variants
• Runtime auto-detection (Podman/Docker)
• Error handling and validation
• Interactive prompts with fallbacks
• Proper background execution

---

Remember: Always run containers in background mode to avoid terminal interruption!

#Image Optimization Features

• ✅ Multi-stage build with separate production dependencies
• ✅ Production-only node_modules (no dev dependencies in final image)
• ✅ Dynamic package detection (automatically copies all packages/*)
• ✅ Optimized build context with .dockerignore
• ✅ Path-independent script (works from any clone location)

#Manual Commands

#1. BUILD IMAGE

Podman:

cd /mnt/repo/Turbo/flash-law
podman build -f apps/flash-legal/Dockerfile -t flash-legal:latest .

Docker:

cd /mnt/repo/Turbo/flash-law
docker build -f apps/flash-legal/Dockerfile -t flash-legal:latest .

#2. STOP AND REMOVE EXISTING CONTAINER

Podman:

podman stop flash-legal-app && podman rm flash-legal-app

Docker:

docker stop flash-legal-app && docker rm flash-legal-app

#3. RUN CONTAINER WITH ENV FILE

Podman (Host Network):

cd /mnt/repo/Turbo/flash-law/apps/flash-legal
podman run -d --network host --name flash-legal-app --env-file .env flash-legal:latest

Docker (Port Mapping):

cd /mnt/repo/Turbo/flash-law/apps/flash-legal
docker run -d -p 3000:3000 --name flash-legal-app --env-file .env flash-legal:latest

#4. COMPLETE UPDATE WORKFLOW

Podman - Full Update:

# Stop and remove existing container
podman stop flash-legal-app && podman rm flash-legal-app

# Build new image
cd /mnt/repo/Turbo/flash-law
podman build -f apps/flash-legal/Dockerfile -t flash-legal:latest .

# Run new container
cd /mnt/repo/Turbo/flash-law/apps/flash-legal
podman run -d --network host --name flash-legal-app --env-file .env flash-legal:latest

Docker - Full Update:

# Stop and remove existing container
docker stop flash-legal-app && docker rm flash-legal-app

# Build new image
cd /mnt/repo/Turbo/flash-law
docker build -f apps/flash-legal/Dockerfile -t flash-legal:latest .

# Run new container
cd /mnt/repo/Turbo/flash-law/apps/flash-legal
docker run -d -p 3000:3000 --name flash-legal-app --env-file .env flash-legal:latest

#5. CONTAINER MANAGEMENT

View Logs:

# Podman
podman logs flash-legal-app
podman logs -f flash-legal-app  # Follow logs

# Docker
docker logs flash-legal-app
docker logs -f flash-legal-app  # Follow logs

Check Status:

# Podman
podman ps | grep flash-legal-app

# Docker
docker ps | grep flash-legal-app

Execute Commands in Container:

# Podman
podman exec -it flash-legal-app /bin/sh

# Docker
docker exec -it flash-legal-app /bin/sh

Test Application:

curl http://localhost:3000
curl -I http://localhost:3000/_next/static/css/b1a328a2eeb8cc11.css

#6. ONE-LINER UPDATE COMMANDS

Podman One-Liner:

cd /mnt/repo/Turbo/flash-law && podman stop flash-legal-app; podman rm flash-legal-app; podman build -f apps/flash-legal/Dockerfile -t flash-legal:latest . && cd apps/flash-legal && podman run -d --network host --name flash-legal-app --env-file .env flash-legal:latest

Docker One-Liner:

cd /mnt/repo/Turbo/flash-law && docker stop flash-legal-app; docker rm flash-legal-app; docker build -f apps/flash-legal/Dockerfile -t flash-legal:latest . && cd apps/flash-legal && docker run -d -p 3000:3000 --name flash-legal-app --env-file .env flash-legal:latest

#7. CLEANUP COMMANDS

Remove All Containers and Images:

# Podman
podman stop flash-legal-app && podman rm flash-legal-app
podman rmi flash-legal:latest
podman system prune -f

# Docker
docker stop flash-legal-app && docker rm flash-legal-app
docker rmi flash-legal:latest
docker system prune -f

#8. TROUBLESHOOTING

Check Container Files:

# Check static files location
podman exec flash-legal-app ls -la /app/.next/static/
docker exec flash-legal-app ls -la /app/.next/static/

# Check environment variables
podman exec flash-legal-app printenv | grep -E "(DATABASE_URI|PAYLOAD_SECRET)"
docker exec flash-legal-app printenv | grep -E "(DATABASE_URI|PAYLOAD_SECRET)"

Network Issues:

# For Docker, if MongoDB connection fails, use host network:
docker run -d --network host --name flash-legal-app --env-file .env flash-legal:latest

#9. DOCKER COMPOSE ALTERNATIVE

If you prefer Docker Compose, use the provided docker-compose.prod.yml:

# With Docker Compose
docker-compose -f docker-compose.prod.yml up -d --build

# Update with Docker Compose
docker-compose -f docker-compose.prod.yml down
docker-compose -f docker-compose.prod.yml up -d --build

#Environment Variables

Make sure your .env file contains:

DATABASE_URI=mongodb://127.0.0.1:27017/flash-legal
PAYLOAD_SECRET=your-secret-here
NEXT_PUBLIC_SERVER_URL=http://localhost:3000
PREVIEW_SECRET=your-preview-secret
CRON_SECRET=your-cron-secret

#Notes

1. Networking: Podman uses --network host for database access, Docker uses -p 3000:3000
2. Database: Make sure MongoDB container is running before starting the app
3. Environment: Always run from the correct directory for env file access
4. Updates: Always rebuild the image when code changes
5. Logs: Use -f flag to follow logs in real-time