Acquisitions - Dockerized Neon Database Application

A Node.js/Express application with Neon Database integration, featuring separate Docker configurations for development (using Neon Local) and production (using Neon Cloud).

🏗️ Architecture Overview

This application uses different database connection strategies based on the environment:

• Development: Uses Neon Local via Docker for ephemeral database branches
• Production: Connects directly to Neon Cloud database

📋 Prerequisites

• Docker and Docker Compose installed
• Neon Database account and project
• Node.js 20+ (for local development without Docker)

🔧 Environment Setup

1. Get Your Neon Credentials

1. Log in to Neon Console
2. Go to your project settings
3. Copy your:
   • API Key (from Account Settings → Developer Settings)
   • Project ID (from Project Settings → General)
   • Parent Branch ID (usually your main branch ID)

2. Configure Environment Variables

Update the environment files with your actual credentials:

Development Environment (.env.development)

# Update these with your actual Neon credentials
NEON_API_KEY=your_actual_neon_api_key_here
NEON_PROJECT_ID=your_actual_neon_project_id_here
PARENT_BRANCH_ID=your_parent_branch_id_here
ARCJET_KEY=your_actual_arcjet_key_here

Production Environment (.env.production)

# Update with your production Neon database URL
DATABASE_URL=postgresql://your_user:your_password@your-endpoint.neon.tech/your_db?sslmode=require
ARCJET_KEY=your_production_arcjet_key_here

🚀 Development Setup

Option 1: Using Docker (Recommended)

1. Start the development environment:

   # Load development environment variables and start services
   docker-compose --env-file .env.development -f docker-compose.dev.yml up -d

2. View logs:

   # View all logs
   docker-compose -f docker-compose.dev.yml logs -f
   
   # View app logs only
   docker-compose -f docker-compose.dev.yml logs -f app
   
   # View Neon Local logs only
   docker-compose -f docker-compose.dev.yml logs -f neon-local

3. Access the application:

   • Application: http://localhost:3000
   • Database: postgres://neon:npg@localhost:5432/neondb

4. Stop the development environment:

   docker-compose -f docker-compose.dev.yml down

Option 2: Local Development (Without Docker)

1. Install dependencies:

   npm install

2. Set up environment:

   cp .env.development .env
   # Edit .env with your actual credentials

3. Run the application:

   npm run dev

Development Features

• Hot Reload: Source code changes are automatically reflected
• Ephemeral Branches: Each container start creates a fresh database branch
• Automatic Cleanup: Database branches are deleted when containers stop
• Git Integration: Optional persistent branches per Git branch

🎯 Production Deployment

Option 1: Docker Compose Production

1. Build and start production services:

   # Load production environment variables and start services
   docker-compose --env-file .env.production -f docker-compose.prod.yml up -d

2. View production logs:

   docker-compose -f docker-compose.prod.yml logs -f

3. Scale the application (optional):

   docker-compose -f docker-compose.prod.yml up -d --scale app=3

Option 2: Production Docker Build

1. Build production image:

   docker build --target production -t acquisitions:latest .

2. Run production container:

   docker run -d \
     --name acquisitions-prod \
     -p 3000:3000 \
     -e NODE_ENV=production \
     -e DATABASE_URL="your_production_neon_url" \
     -e ARCJET_KEY="your_production_arcjet_key" \
     acquisitions:latest

🔍 Database Operations

Development Database Management

# Run database migrations in development
docker-compose -f docker-compose.dev.yml exec app npm run db:migrate

# Generate new migrations
docker-compose -f docker-compose.dev.yml exec app npm run db:generate

# Open Drizzle Studio
docker-compose -f docker-compose.dev.yml exec app npm run db:studio

Production Database Management

# Run database migrations in production
docker-compose -f docker-compose.prod.yml exec app npm run db:migrate

📊 Monitoring and Health Checks

Health Check Endpoints

• Application Health: GET http://localhost:3000/health (if implemented)
• Docker Health: Built-in health checks for all services

Viewing Service Status

# Development
docker-compose -f docker-compose.dev.yml ps

# Production
docker-compose -f docker-compose.prod.yml ps

🐛 Troubleshooting

Common Issues

1. Neon Local Connection Issues

   # Check if Neon Local is ready
   docker-compose -f docker-compose.dev.yml logs neon-local
   
   # Verify health check
   docker-compose -f docker-compose.dev.yml exec neon-local pg_isready -h localhost -p 5432 -U neon

2. App Connection Issues

   # Check app logs
   docker-compose -f docker-compose.dev.yml logs app
   
   # Restart app service
   docker-compose -f docker-compose.dev.yml restart app

3. Environment Variable Issues

   # Verify environment variables are loaded
   docker-compose -f docker-compose.dev.yml exec app env | grep -E '(NODE_ENV|DATABASE_URL|NEON_)'

Database Connection Debugging

The application automatically detects the environment and uses the appropriate database driver:

• Development + Neon Local: Uses pg (PostgreSQL driver)
• Production + Neon Cloud: Uses @neondatabase/serverless

Check the application logs for connection messages:

• 🔧 Connecting to Neon Local (postgres driver)...
• ☁️ Connecting to Neon Cloud (serverless driver)...
• ✅ Database connection established successfully

🔐 Security Considerations

Development

• Self-signed certificates are accepted for Neon Local
• Debug logging is enabled
• Hot reload exposes source code

Production

• SSL/TLS encryption enforced
• Non-root user execution
• Resource limits applied
• Security headers via Helmet middleware
• Rate limiting via Arcjet

📁 Project Structure

acquisitions/
├── src/
│   ├── config/
│   │   └── database.js          # Multi-environment database config
│   ├── controllers/
│   ├── middlewares/
│   ├── models/
│   ├── routes/
│   ├── services/
│   └── utils/
├── Dockerfile                   # Multi-stage Docker build
├── docker-compose.dev.yml       # Development with Neon Local
├── docker-compose.prod.yml      # Production with Neon Cloud
├── .env.development            # Development environment vars
├── .env.production             # Production environment vars
└── README.md                   # This file

🚦 Environment Variables Reference

Development Variables

Variable	Description	Required
NEON_API_KEY	Your Neon API key	✅
NEON_PROJECT_ID	Your Neon project ID	✅
PARENT_BRANCH_ID	Parent branch for ephemeral branches	✅
ARCJET_KEY	Arcjet security key	✅
NODE_ENV	Set to development	✅
PORT	Application port (default: 3000)	❌
LOG_LEVEL	Logging level	❌

Production Variables

Variable	Description	Required
DATABASE_URL	Full Neon Cloud database URL	✅
ARCJET_KEY	Production Arcjet security key	✅
NODE_ENV	Set to production	✅
PORT	Application port (default: 3000)	❌
LOG_LEVEL	Logging level	❌

📚 Additional Resources

• Neon Documentation
• Neon Local Documentation
• Docker Documentation
• Drizzle ORM Documentation

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with both development and production setups
5. Submit a pull request

📄 License

This project is licensed under the ISC License - see the package.json file for details.