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

```bash
# 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

```bash
# 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)

```bash
# 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

```bash
# 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:

   ```bash
   make env-setup
   ```

1. 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

```text
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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</content>
<parameter name="filePath">/Users/damirmukimov/city_resource_graph/bugulma/backend/README.docker.md