re-uploading work
This commit is contained in:
303
docker/PORT_CONFLICTS.md
Normal file
303
docker/PORT_CONFLICTS.md
Normal file
@@ -0,0 +1,303 @@
|
||||
# Docker Port Conflicts Resolution
|
||||
|
||||
## Problem
|
||||
|
||||
When starting Attune with Docker Compose, you may encounter port binding errors:
|
||||
|
||||
```
|
||||
Error response from daemon: ports are not available: exposing port TCP 0.0.0.0:5432 -> 127.0.0.1:0: listen tcp 0.0.0.0:5432: bind: address already in use
|
||||
```
|
||||
|
||||
This happens when **system-level services** (PostgreSQL, RabbitMQ, Redis) are already running and using the same ports that Docker containers need.
|
||||
|
||||
## Port Conflicts Table
|
||||
|
||||
| Service | Port | Docker Container | System Service |
|
||||
|---------|------|------------------|----------------|
|
||||
| PostgreSQL | 5432 | attune-postgres | postgresql |
|
||||
| RabbitMQ (AMQP) | 5672 | attune-rabbitmq | rabbitmq-server |
|
||||
| RabbitMQ (Management) | 15672 | attune-rabbitmq | rabbitmq-server |
|
||||
| Redis | 6379 | attune-redis | redis-server |
|
||||
| API | 8080 | attune-api | (usually free) |
|
||||
| Notifier (WebSocket) | 8081 | attune-notifier | (usually free) |
|
||||
| Web UI | 3000 | attune-web | (usually free) |
|
||||
|
||||
## Quick Fix
|
||||
|
||||
### Automated Script (Recommended)
|
||||
|
||||
Run the provided script to stop all conflicting services:
|
||||
|
||||
```bash
|
||||
./scripts/stop-system-services.sh
|
||||
```
|
||||
|
||||
This will:
|
||||
1. Stop system PostgreSQL, RabbitMQ, and Redis services
|
||||
2. Verify all ports are free
|
||||
3. Clean up any orphaned Docker containers
|
||||
4. Give you the option to disable services on boot
|
||||
|
||||
### Manual Fix
|
||||
|
||||
If the script doesn't work, follow these steps:
|
||||
|
||||
#### 1. Stop System PostgreSQL
|
||||
|
||||
```bash
|
||||
# Check if running
|
||||
systemctl is-active postgresql
|
||||
|
||||
# Stop it
|
||||
sudo systemctl stop postgresql
|
||||
|
||||
# Optionally disable on boot
|
||||
sudo systemctl disable postgresql
|
||||
```
|
||||
|
||||
#### 2. Stop System RabbitMQ
|
||||
|
||||
```bash
|
||||
# Check if running
|
||||
systemctl is-active rabbitmq-server
|
||||
|
||||
# Stop it
|
||||
sudo systemctl stop rabbitmq-server
|
||||
|
||||
# Optionally disable on boot
|
||||
sudo systemctl disable rabbitmq-server
|
||||
```
|
||||
|
||||
#### 3. Stop System Redis
|
||||
|
||||
```bash
|
||||
# Check if running
|
||||
systemctl is-active redis-server
|
||||
|
||||
# Stop it
|
||||
sudo systemctl stop redis-server
|
||||
|
||||
# Optionally disable on boot
|
||||
sudo systemctl disable redis-server
|
||||
```
|
||||
|
||||
#### 4. Verify Ports are Free
|
||||
|
||||
```bash
|
||||
# Check PostgreSQL port
|
||||
nc -zv localhost 5432
|
||||
|
||||
# Check RabbitMQ port
|
||||
nc -zv localhost 5672
|
||||
|
||||
# Check Redis port
|
||||
nc -zv localhost 6379
|
||||
|
||||
# All should return "Connection refused" (meaning free)
|
||||
```
|
||||
|
||||
## Finding What's Using a Port
|
||||
|
||||
If ports are still in use after stopping services:
|
||||
|
||||
```bash
|
||||
# Method 1: Using lsof (most detailed)
|
||||
sudo lsof -i :5432
|
||||
|
||||
# Method 2: Using ss
|
||||
sudo ss -tulpn | grep 5432
|
||||
|
||||
# Method 3: Using netstat
|
||||
sudo netstat -tulpn | grep 5432
|
||||
|
||||
# Method 4: Using fuser
|
||||
sudo fuser 5432/tcp
|
||||
```
|
||||
|
||||
## Killing a Process on a Port
|
||||
|
||||
```bash
|
||||
# Find the process ID
|
||||
PID=$(lsof -ti tcp:5432)
|
||||
|
||||
# Kill it
|
||||
sudo kill $PID
|
||||
|
||||
# Force kill if needed
|
||||
sudo kill -9 $PID
|
||||
```
|
||||
|
||||
## Docker-Specific Issues
|
||||
|
||||
### Orphaned Containers
|
||||
|
||||
Sometimes Docker containers remain running after a failed `docker compose down`:
|
||||
|
||||
```bash
|
||||
# List all containers (including stopped)
|
||||
docker ps -a
|
||||
|
||||
# Stop and remove Attune containers
|
||||
docker compose down
|
||||
|
||||
# Remove orphaned containers using specific ports
|
||||
docker ps -q --filter "publish=5432" | xargs docker stop
|
||||
docker ps -q --filter "publish=5672" | xargs docker stop
|
||||
docker ps -q --filter "publish=6379" | xargs docker stop
|
||||
```
|
||||
|
||||
### Corrupted Container in Restart Loop
|
||||
|
||||
If `docker ps -a` shows a container with status "Restarting (255)":
|
||||
|
||||
```bash
|
||||
# Check logs
|
||||
docker logs attune-postgres
|
||||
|
||||
# If you see "exec format error", the image is corrupted
|
||||
docker compose down
|
||||
docker rmi postgres:16-alpine
|
||||
docker volume rm attune_postgres_data
|
||||
docker pull postgres:16-alpine
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Alternative: Change Docker Ports
|
||||
|
||||
If you want to keep system services running, modify `docker compose.yaml` to use different ports:
|
||||
|
||||
```yaml
|
||||
postgres:
|
||||
ports:
|
||||
- "5433:5432" # Map to 5433 on host instead
|
||||
|
||||
rabbitmq:
|
||||
ports:
|
||||
- "5673:5672" # Map to 5673 on host instead
|
||||
- "15673:15672"
|
||||
|
||||
redis:
|
||||
ports:
|
||||
- "6380:6379" # Map to 6380 on host instead
|
||||
```
|
||||
|
||||
Then update your config files to use these new ports:
|
||||
|
||||
```yaml
|
||||
# config.docker.yaml
|
||||
database:
|
||||
url: postgresql://attune:attune@postgres:5432 # Internal still uses 5432
|
||||
|
||||
# But if accessing from host:
|
||||
database:
|
||||
url: postgresql://attune:attune@localhost:5433 # Use external port
|
||||
```
|
||||
|
||||
## Recommended Approach for Development
|
||||
|
||||
**Option 1: Use Docker Exclusively (Recommended)**
|
||||
|
||||
Stop all system services and use Docker for everything:
|
||||
|
||||
```bash
|
||||
./scripts/stop-system-services.sh
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- Clean separation from system
|
||||
- Easy to start/stop all services together
|
||||
- Consistent with production deployment
|
||||
- No port conflicts
|
||||
|
||||
**Cons:**
|
||||
- Need to use Docker commands to access services
|
||||
- Slightly more overhead
|
||||
|
||||
**Option 2: Use System Services**
|
||||
|
||||
Don't use Docker Compose, run services directly:
|
||||
|
||||
```bash
|
||||
sudo systemctl start postgresql
|
||||
sudo systemctl start rabbitmq-server
|
||||
sudo systemctl start redis-server
|
||||
|
||||
# Then run Attune services natively
|
||||
cargo run --bin attune-api
|
||||
cargo run --bin attune-executor
|
||||
# etc.
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- Familiar system tools
|
||||
- Easier debugging with local tools
|
||||
- Lower overhead
|
||||
|
||||
**Cons:**
|
||||
- Manual service management
|
||||
- Different from production
|
||||
- Version mismatches possible
|
||||
|
||||
## Re-enabling System Services
|
||||
|
||||
To go back to using system services:
|
||||
|
||||
```bash
|
||||
# Start and enable services
|
||||
sudo systemctl start postgresql
|
||||
sudo systemctl start rabbitmq-server
|
||||
sudo systemctl start redis-server
|
||||
|
||||
sudo systemctl enable postgresql
|
||||
sudo systemctl enable rabbitmq-server
|
||||
sudo systemctl enable redis-server
|
||||
```
|
||||
|
||||
## Troubleshooting Checklist
|
||||
|
||||
- [ ] Stop Docker containers: `docker compose down`
|
||||
- [ ] Stop system PostgreSQL: `sudo systemctl stop postgresql`
|
||||
- [ ] Stop system RabbitMQ: `sudo systemctl stop rabbitmq-server`
|
||||
- [ ] Stop system Redis: `sudo systemctl stop redis-server`
|
||||
- [ ] Verify port 5432 is free: `nc -zv localhost 5432`
|
||||
- [ ] Verify port 5672 is free: `nc -zv localhost 5672`
|
||||
- [ ] Verify port 6379 is free: `nc -zv localhost 6379`
|
||||
- [ ] Check for orphaned containers: `docker ps -a | grep attune`
|
||||
- [ ] Check for corrupted images: `docker logs attune-postgres`
|
||||
- [ ] Start fresh: `docker compose up -d`
|
||||
|
||||
## Prevention
|
||||
|
||||
To avoid this issue in the future:
|
||||
|
||||
1. **Add to your shell profile** (`~/.bashrc` or `~/.zshrc`):
|
||||
|
||||
```bash
|
||||
alias attune-docker-start='cd /path/to/attune && ./scripts/stop-system-services.sh && docker compose up -d'
|
||||
alias attune-docker-stop='cd /path/to/attune && docker compose down'
|
||||
alias attune-docker-logs='cd /path/to/attune && docker compose logs -f'
|
||||
```
|
||||
|
||||
2. **Create a systemd service** to automatically stop conflicting services when starting Docker:
|
||||
|
||||
See `docs/deployment/systemd-setup.md` for details (if available).
|
||||
|
||||
3. **Use different ports** as described above to run both simultaneously.
|
||||
|
||||
## Summary
|
||||
|
||||
The most reliable approach:
|
||||
|
||||
```bash
|
||||
# One-time setup
|
||||
./scripts/stop-system-services.sh
|
||||
# Answer 'y' to disable services on boot
|
||||
|
||||
# Then use Docker
|
||||
docker compose up -d # Start all services
|
||||
docker compose logs -f # View logs
|
||||
docker compose down # Stop all services
|
||||
```
|
||||
|
||||
This ensures clean, reproducible environments that match production deployment.
|
||||
Reference in New Issue
Block a user