# Docker Compose v2 Migration Guide

This project uses **Docker Compose v2** (the newer version integrated into Docker CLI).

## What's the Difference?

| Version | Command | Status |
|---------|---------|--------|
| v1 | `docker-compose` | Legacy (standalone binary) |
| v2 | `docker compose` | Current (built into Docker) |

**Key change:** The command changed from `docker-compose` (with hyphen) to `docker compose` (with space).

## Check Your Version

```bash
# Check if you have Docker Compose v2
docker compose version

# Check if you have old v1
docker-compose --version
```

## If You Have v1 Only

### Option 1: Upgrade to Docker Compose v2 (Recommended)

**macOS with OrbStack:**
```bash
# OrbStack includes Docker Compose v2 by default
# Just make sure OrbStack is up to date
orb update
```

**macOS with Docker Desktop:**
```bash
# Update Docker Desktop to latest version
# Docker Compose v2 is included since Docker Desktop 3.4.0
```

**Manual Installation:**
```bash
# Install as Docker CLI plugin
mkdir -p ~/.docker/cli-plugins
curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-darwin-aarch64 -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose
```

### Option 2: Create an Alias (Quick Fix)

If you can't upgrade immediately, create an alias:

```bash
# Add to your ~/.zshrc or ~/.bashrc
echo "alias docker-compose='docker compose'" >> ~/.zshrc
source ~/.zshrc
```

### Option 3: Use Docker Compose v1 Syntax (Not Recommended)

Manually replace all `docker compose` commands with `docker-compose` in:
- `start.sh`
- `README.md`
- `DATAGRIP_SETUP.md`

## Why We Use v2

1. **Built-in**: No separate installation needed
2. **Better Performance**: Faster and more efficient
3. **Active Development**: v1 is in maintenance mode only
4. **Same YAML**: Your `docker-compose.yml` works with both versions

## Verify Your Setup

```bash
./check-docker.sh
```

This will check your Docker and Docker Compose installation.

## Common Issues

### "docker: 'compose' is not a docker command"

You have Docker but not Docker Compose v2. Solutions:
- Update Docker Desktop
- Install Docker Compose v2 plugin (see above)
- Use the alias workaround

### Both v1 and v2 installed

No problem! Both can coexist. Just use `docker compose` (v2) for this project.

## References

- [Docker Compose v2 Documentation](https://docs.docker.com/compose/cli-command/)
- [Migration Guide](https://docs.docker.com/compose/migrate/)