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

# Clone the repository
git clone https://github.com/yourusername/buque.git
cd buque

# Build and install
make install

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

Using Go Install

go install github.com/yourusername/buque/cmd/buque@latest

Quick Start

1. Initialize Buque

buque init

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

2. Deploy Nginx-proxy (Optional but Recommended)

buque proxy deploy

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

3. Add Your First Environment

# 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

# Start a specific environment
buque up webapp

# Start all enabled environments
buque up

5. Monitor Your Containers

# 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

# 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

# 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

# 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

# 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

# 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

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:

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

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/ 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

# 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":

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

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

# 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 file for details.

Acknowledgments

• nginx-proxy - Automated nginx reverse proxy for Docker
• acme-companion - Let's Encrypt companion for nginx-proxy
• Cobra - CLI framework for Go
• Docker - Container platform

Support

If you encounter any issues or have questions:

• Open an issue on GitHub
• Check the documentation

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