turash/bugulma/backend/README.docker.md

Turash Backend - Docker Development Setup

This directory contains the Docker configuration for the Turash backend development environment.

Architecture

The development stack includes:

• Neo4j 5.26: Graph database for resource matching relationships
• PostgreSQL 17 + PostGIS 3.6: Spatial database for geospatial queries
• Redis 8.4: Caching and session management
• NATS 2.12.2: Message queue for event streaming
• Go 1.25.3: Backend application with hot reload

Quick Start

Prerequisites

• Docker and Docker Compose installed
• At least 4GB RAM available for containers
• Ports 7474, 7687, 5432, 6379, 4222, 8222, 8080 available

Start Development Environment

# Clone and navigate to backend directory
cd bugulma/backend

# Quick start (setup environment and start all services)
make quick-start

# Or start step by step:
make env-setup    # Setup .env file
make infra        # Start infrastructure services
make dev-build    # Build development environment
make dev          # Start with hot reload

Alternative Commands

# Start all services with hot reload
make dev

# Start only infrastructure (for local Go development)
make infra

# View available commands
make help

Access Services

• Neo4j Browser: http://localhost:7474 (neo4j/test123456)
• NATS Monitoring: http://localhost:8222
• Backend API: http://localhost:8080
• PostgreSQL: localhost:5432 (turash/turash123)
• Redis: localhost:6379 (password: turash123)

Development Workflow

With Hot Reload (Recommended)

# Start all services including backend with hot reload
docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d

# The backend will automatically rebuild on code changes

Manual Development

# Start only infrastructure services
docker-compose up -d neo4j postgres redis nats

# Run backend locally
go run ./cmd/cli server

Environment Configuration

1. Setup environment file:

   make env-setup
   

2. Update values in .env for your local setup

Database Initialization

Neo4j

• Schema: Constraints and indexes created automatically
• Sample Data: Pre-loaded with 3 businesses, sites, and resource flows
• Access: Use Neo4j Browser at http://localhost:7474

PostgreSQL

• Extensions: PostGIS enabled for spatial queries
• Schema: Tables for geospatial data and analytics
• Sample Data: Mirrors Neo4j sample data for spatial queries

Sample Data Overview

Businesses:
- Berlin Heat GmbH (Heat producer)
- Green Brewery Berlin (Heat consumer)
- Eco Hotel Berlin (Heat consumer)

Resource Flows:
- Heat output: 1000 kWh/h at 80°C
- Heat inputs: 200 kWh/h and 150 kWh/h at 60-70°C

Testing the Setup

Health Checks

# Check all services are running
docker-compose ps

# Test Neo4j connection
curl -u neo4j:test123456 http://localhost:7474/db/data/

# Test PostgreSQL connection
docker-compose exec postgres psql -U turash -d turash -c "SELECT PostGIS_version();"

# Test Redis connection
docker-compose exec redis redis-cli -a turash123 ping

# Test NATS connection
docker-compose exec nats nats pub test "hello world"

API Testing

# Health check
curl http://localhost:8080/health

# Login (if authentication enabled)
curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@turash.dev","password":"admin"}'

# List businesses
curl http://localhost:8080/api/organizations

# Find matches for a resource flow
curl "http://localhost:8080/api/matching/resource/flow-001"

Troubleshooting

Common Issues

1. Port conflicts: Stop local services using those ports
2. Memory issues: Ensure Docker has enough RAM (4GB+ recommended)
3. Neo4j won't start: Check available disk space
4. PostgreSQL connection fails: Wait for health checks to pass

Logs and Debugging

# View all logs
make dev-logs

# View specific service logs
docker-compose logs neo4j
docker-compose logs backend

# Follow logs in real-time
make dev-logs

# Restart a specific service
docker-compose restart neo4j

# Check service health
make health

Reset Environment

# Stop and remove all containers and volumes
make dev-clean

# Rebuild and start fresh
make dev-build && make dev

Production Deployment

For production deployment, use the base docker-compose.yml and:

1. Update environment variables for production values
2. Use external databases or managed services
3. Configure proper secrets management
4. Set up monitoring and logging
5. Use production Dockerfiles with multi-stage builds

Services Configuration

Neo4j

• Version: 5.26 with Graph Data Science plugin
• Auth: neo4j/test123456 (change in production!)
• Plugins: APOC, GDS enabled
• Data: Persisted in neo4j_data volume

PostgreSQL

• Version: 17 with PostGIS 3.6
• Database: turash
• User: turash/turash123
• Extensions: PostGIS, PostGIS Topology

Redis

• Version: 8.4 Alpine
• Password: turash123
• Persistence: AOF enabled

NATS

• Version: 2.12.2 Alpine
• JetStream: Enabled for persistence
• Monitoring: Available at :8222

Development Tips

1. Use volumes: Code changes are reflected immediately with hot reload
2. Database migrations: Run manually or add to init scripts
3. Environment variables: Use .env file for local development
4. Logs: Use docker-compose logs -f to monitor all services
5. Cleanup: Regularly clean up unused containers and images

Next Steps

1. Frontend Development: Set up React/Next.js with similar Docker setup
2. Testing: Add integration tests using testcontainers
3. CI/CD: Set up GitHub Actions for automated testing
4. Monitoring: Add Prometheus/Grafana for observability
5. Security: Implement proper authentication and authorization /Users/damirmukimov/city_resource_graph/bugulma/backend/README.docker.md