9.4 KiB
9.4 KiB
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 pointinternal/cmd: CLI commands implementationinternal/config: Configuration managementinternal/docker: Docker and Docker Compose operationsinternal/models: Data modelsinternal/proxy: Nginx-proxy managementinternal/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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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