427
README.md
Archivo normal
427
README.md
Archivo normal
@@ -0,0 +1,427 @@
|
||||
# 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/yourusername/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/yourusername/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/yourusername/buque/issues)
|
||||
- Check the [documentation](https://github.com/yourusername/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
|
||||
Referencia en una nueva incidencia
Block a user