buque/README.md

# Buque 🚢

**Buque** (Spanish for "ship") is a powerful command-line tool for managing multiple Docker Compose environments on a single machine. It simplifies the deployment, monitoring, and maintenance of containerized applications with built-in nginx-proxy integration for easy reverse proxy management.

## Features

- 🚀 **Multi-environment Management**: Deploy and manage multiple Docker Compose projects from a single command
- 🔄 **Easy Updates**: Pull latest images and update all environments with one command
- 📊 **Real-time Statistics**: Monitor CPU, memory, network, and disk usage for all containers
- 🌐 **Nginx-proxy Integration**: Automatic reverse proxy setup with Let's Encrypt SSL support
- 📝 **Configuration Management**: Centralized configuration for all your environments
- 🔍 **Container Monitoring**: View logs, status, and statistics for all environments
- 🛠️ **Simple CLI**: Intuitive commands for common Docker Compose operations

## Requirements

- **Go** 1.21 or higher (for building from source)
- **Docker** 20.10 or higher
- **Docker Compose** V2 (or docker-compose V1)
- Linux, macOS, or Windows (with WSL2)

## Installation

### From Source

```bash
# Clone the repository
git clone https://github.com/manalejandro/buque.git
cd buque

# Build and install
make install

# Or build only
make build
./bin/buque --version
```

### Using Go Install

```bash
go install github.com/manalejandro/buque/cmd/buque@latest
```

## Quick Start

### 1. Initialize Buque

```bash
buque init
```

This creates the default configuration file at `~/.buque/config.yaml`.

### 2. Deploy Nginx-proxy (Optional but Recommended)

```bash
buque proxy deploy
```

This deploys nginx-proxy with Let's Encrypt support for automatic SSL certificates.

### 3. Add Your First Environment

```bash
# Add an environment with a docker-compose.yml
buque env add webapp /path/to/webapp

# Add with custom compose file
buque env add api /path/to/api --compose-file docker-compose.prod.yml
```

### 4. Start Your Environment

```bash
# Start a specific environment
buque up webapp

# Start all enabled environments
buque up
```

### 5. Monitor Your Containers

```bash
# View statistics
buque stats

# Continuous monitoring (refreshes every 2 seconds)
buque stats --continuous

# View logs
buque logs webapp

# List running containers
buque ps
```

## Usage

### Environment Management

```bash
# List all environments
buque env list

# Add a new environment
buque env add <name> <path> [--compose-file docker-compose.yml]

# Remove an environment
buque env remove <name>

# Enable/disable an environment
buque env enable <name>
buque env disable <name>
```

### Container Operations

```bash
# Start environments
buque up [environment...]              # Start specific or all environments
buque up webapp api                    # Start multiple environments
buque up --build                       # Build images before starting

# Stop environments
buque down [environment...]            # Stop specific or all environments
buque down --volumes                   # Remove volumes when stopping

# Restart environments
buque restart [environment...]

# Update environments (pull images and recreate)
buque update [environment...]

# Pull latest images
buque pull [environment...]
```

### Monitoring and Statistics

```bash
# View container statistics
buque stats                            # Show stats for all containers
buque stats webapp                     # Show stats for specific environment
buque stats --continuous --interval 5  # Continuous mode with 5s interval
buque stats --sort memory              # Sort by: cpu, memory, network, name

# View logs
buque logs webapp                      # Show logs
buque logs webapp --follow             # Follow log output
buque logs webapp --tail 50            # Show last 50 lines

# List containers
buque ps                               # List all containers
buque ps webapp api                    # List specific environments
```

### Nginx-proxy Management

```bash
# Deploy nginx-proxy
buque proxy deploy

# Remove nginx-proxy
buque proxy remove

# Check nginx-proxy status
buque proxy status

# Generate example docker-compose.yml for a service
buque proxy example myapp myapp.example.com
```

### Maintenance

```bash
# Prune unused resources
buque prune
```

## Configuration

Buque stores its configuration in `~/.buque/config.yaml`. You can specify a custom location with the `--config` flag.

### Example Configuration

```yaml
environments:
  - name: webapp
    path: /home/webapp
    compose_file: docker-compose.yml
    enabled: true
    labels:
      team: frontend
      environment: production

  - name: api
    path: /home/api
    compose_file: docker-compose.yml
    enabled: true

nginx_proxy:
  enabled: true
  network_name: nginx-proxy
  container_name: nginx-proxy
  path: /home/user/.buque/nginx-proxy
  http_port: 80
  https_port: 443
  ssl_enabled: true

docker:
  compose_version: v2
```

## Docker Compose Setup

### Basic Service with Nginx-proxy

Create a `docker-compose.yml` for your service:

```yaml
version: '3.8'

services:
  web:
    image: nginx:alpine
    expose:
      - "80"
    environment:
      - VIRTUAL_HOST=myapp.example.com
      - VIRTUAL_PORT=80
      - LETSENCRYPT_HOST=myapp.example.com
      - LETSENCRYPT_EMAIL=admin@example.com
    networks:
      - nginx-proxy
    labels:
      - "buque.environment=myapp"
      - "buque.managed=true"

networks:
  nginx-proxy:
    external: true
```

### Multi-service Application

```yaml
version: '3.8'

services:
  app:
    build: .
    expose:
      - "3000"
    environment:
      - VIRTUAL_HOST=myapp.example.com
      - VIRTUAL_PORT=3000
      - LETSENCRYPT_HOST=myapp.example.com
      - LETSENCRYPT_EMAIL=admin@example.com
    networks:
      - nginx-proxy
      - internal
    labels:
      - "buque.environment=myapp"

  database:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=myapp
      - POSTGRES_PASSWORD=changeme
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - internal
    labels:
      - "buque.environment=myapp"

networks:
  nginx-proxy:
    external: true
  internal:

volumes:
  db-data:
```

## Examples

See the [`examples/`](./examples/) directory for more docker-compose.yml templates and configurations.

## Architecture

Buque is organized into several packages:

- **`cmd/buque`**: Main application entry point
- **`internal/cmd`**: CLI commands implementation
- **`internal/config`**: Configuration management
- **`internal/docker`**: Docker and Docker Compose operations
- **`internal/models`**: Data models
- **`internal/proxy`**: Nginx-proxy management
- **`internal/stats`**: Container statistics collection

## Development

### Building

```bash
# Build the binary
make build

# Run tests
make test

# Format code
make fmt

# Run linter
make vet

# Build for all platforms
make build-all
```

### Project Structure

```
buque/
├── cmd/
│   └── buque/           # Main application
├── internal/
│   ├── cmd/             # CLI commands
│   ├── config/          # Configuration management
│   ├── docker/          # Docker client and compose manager
│   ├── models/          # Data models
│   ├── proxy/           # Nginx-proxy manager
│   └── stats/           # Statistics collector
├── examples/            # Example configurations
├── go.mod
├── go.sum
├── Makefile
└── README.md
```

## Troubleshooting

### Docker Connection Issues

If you see "Cannot connect to the Docker daemon":

```bash
# Check if Docker is running
systemctl status docker

# Add your user to the docker group
sudo usermod -aG docker $USER
newgrp docker
```

### Nginx-proxy Network Issues

If containers can't connect to nginx-proxy:

```bash
# Ensure the nginx-proxy network exists
docker network create nginx-proxy

# Redeploy nginx-proxy
buque proxy remove
buque proxy deploy
```

### Permission Issues

If you get permission errors with config files:

```bash
# Check config directory permissions
ls -la ~/.buque/

# Fix permissions if needed
chmod 755 ~/.buque
chmod 644 ~/.buque/config.yaml
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [nginx-proxy](https://github.com/nginx-proxy/nginx-proxy) - Automated nginx reverse proxy for Docker
- [acme-companion](https://github.com/nginx-proxy/acme-companion) - Let's Encrypt companion for nginx-proxy
- [Cobra](https://github.com/spf13/cobra) - CLI framework for Go
- [Docker](https://www.docker.com/) - Container platform

## Support

If you encounter any issues or have questions:

- Open an issue on [GitHub](https://github.com/manalejandro/buque/issues)
- Check the [documentation](https://github.com/manalejandro/buque/wiki)

## Roadmap

- [ ] Web UI dashboard for monitoring
- [ ] Automated backup and restore functionality
- [ ] Integration with container registries
- [ ] Scheduled updates via cron
- [ ] Email/Slack notifications for container events
- [ ] Support for Docker Swarm and Kubernetes
- [ ] Health checks and automatic recovery
- [ ] Resource usage alerts and limits

---

Made with ❤️ for Docker enthusiasts