246
docs/DOCKER_SETUP.md
Archivo normal
246
docs/DOCKER_SETUP.md
Archivo normal
@@ -0,0 +1,246 @@
|
||||
# Docker and Docker Compose Setup Guide
|
||||
|
||||
This guide will help you install Docker and Docker Compose on various operating systems.
|
||||
|
||||
## Linux
|
||||
|
||||
### Ubuntu/Debian
|
||||
|
||||
```bash
|
||||
# Update package index
|
||||
sudo apt-get update
|
||||
|
||||
# Install prerequisites
|
||||
sudo apt-get install -y \
|
||||
apt-transport-https \
|
||||
ca-certificates \
|
||||
curl \
|
||||
gnupg \
|
||||
lsb-release
|
||||
|
||||
# Add Docker's official GPG key
|
||||
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
|
||||
|
||||
# Set up the stable repository
|
||||
echo \
|
||||
"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
|
||||
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
|
||||
|
||||
# Install Docker Engine
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
|
||||
|
||||
# Add your user to the docker group
|
||||
sudo usermod -aG docker $USER
|
||||
|
||||
# Apply new group membership (or logout and login)
|
||||
newgrp docker
|
||||
|
||||
# Verify installation
|
||||
docker --version
|
||||
docker compose version
|
||||
```
|
||||
|
||||
### Fedora/CentOS/RHEL
|
||||
|
||||
```bash
|
||||
# Install prerequisites
|
||||
sudo dnf -y install dnf-plugins-core
|
||||
|
||||
# Add Docker repository
|
||||
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
|
||||
|
||||
# Install Docker
|
||||
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
|
||||
|
||||
# Start Docker
|
||||
sudo systemctl start docker
|
||||
sudo systemctl enable docker
|
||||
|
||||
# Add your user to the docker group
|
||||
sudo usermod -aG docker $USER
|
||||
|
||||
# Verify installation
|
||||
docker --version
|
||||
docker compose version
|
||||
```
|
||||
|
||||
### Arch Linux
|
||||
|
||||
```bash
|
||||
# Install Docker
|
||||
sudo pacman -S docker docker-compose
|
||||
|
||||
# Start Docker service
|
||||
sudo systemctl start docker
|
||||
sudo systemctl enable docker
|
||||
|
||||
# Add your user to the docker group
|
||||
sudo usermod -aG docker $USER
|
||||
|
||||
# Verify installation
|
||||
docker --version
|
||||
docker compose version
|
||||
```
|
||||
|
||||
## macOS
|
||||
|
||||
### Using Homebrew
|
||||
|
||||
```bash
|
||||
# Install Docker Desktop
|
||||
brew install --cask docker
|
||||
|
||||
# Start Docker Desktop from Applications
|
||||
# Or use: open -a Docker
|
||||
|
||||
# Verify installation
|
||||
docker --version
|
||||
docker compose version
|
||||
```
|
||||
|
||||
### Manual Installation
|
||||
|
||||
1. Download Docker Desktop for Mac from [https://www.docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop)
|
||||
2. Open the `.dmg` file and drag Docker to Applications
|
||||
3. Launch Docker from Applications
|
||||
4. Docker icon will appear in the menu bar when running
|
||||
|
||||
## Windows
|
||||
|
||||
### Using WSL2 (Recommended)
|
||||
|
||||
1. Enable WSL2:
|
||||
```powershell
|
||||
wsl --install
|
||||
```
|
||||
|
||||
2. Download and install Docker Desktop for Windows from [https://www.docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop)
|
||||
|
||||
3. During installation, ensure "Use WSL 2 instead of Hyper-V" is selected
|
||||
|
||||
4. After installation, open Docker Desktop settings:
|
||||
- Go to Settings > General
|
||||
- Ensure "Use the WSL 2 based engine" is checked
|
||||
- Go to Settings > Resources > WSL Integration
|
||||
- Enable integration with your WSL distributions
|
||||
|
||||
5. Verify installation in WSL:
|
||||
```bash
|
||||
docker --version
|
||||
docker compose version
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
After installation, verify Docker is working:
|
||||
|
||||
```bash
|
||||
# Check Docker version
|
||||
docker --version
|
||||
|
||||
# Check Docker Compose version
|
||||
docker compose version
|
||||
|
||||
# Run a test container
|
||||
docker run hello-world
|
||||
|
||||
# Check Docker is running
|
||||
docker ps
|
||||
```
|
||||
|
||||
## Post-Installation Steps
|
||||
|
||||
### Linux: Run Docker without sudo
|
||||
|
||||
```bash
|
||||
# Create docker group (usually already exists)
|
||||
sudo groupadd docker
|
||||
|
||||
# Add your user to docker group
|
||||
sudo usermod -aG docker $USER
|
||||
|
||||
# Apply changes
|
||||
newgrp docker
|
||||
|
||||
# Verify
|
||||
docker run hello-world
|
||||
```
|
||||
|
||||
### Configure Docker to start on boot
|
||||
|
||||
```bash
|
||||
# Linux (systemd)
|
||||
sudo systemctl enable docker
|
||||
|
||||
# Check status
|
||||
sudo systemctl status docker
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Permission Denied Error
|
||||
|
||||
If you get "permission denied" when running Docker:
|
||||
|
||||
```bash
|
||||
# Make sure your user is in the docker group
|
||||
groups $USER
|
||||
|
||||
# If docker is not listed:
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
```
|
||||
|
||||
### Docker Daemon Not Running
|
||||
|
||||
```bash
|
||||
# Linux
|
||||
sudo systemctl start docker
|
||||
sudo systemctl status docker
|
||||
|
||||
# If it fails to start, check logs:
|
||||
sudo journalctl -u docker.service
|
||||
```
|
||||
|
||||
### Docker Compose Command Not Found
|
||||
|
||||
If `docker compose` doesn't work but `docker-compose` does:
|
||||
|
||||
```bash
|
||||
# Install Docker Compose plugin
|
||||
sudo apt-get install docker-compose-plugin
|
||||
|
||||
# Or use docker-compose (standalone)
|
||||
sudo apt-get install docker-compose
|
||||
```
|
||||
|
||||
Buque supports both `docker compose` (V2) and `docker-compose` (V1).
|
||||
|
||||
## Resources
|
||||
|
||||
- [Docker Documentation](https://docs.docker.com/)
|
||||
- [Docker Compose Documentation](https://docs.docker.com/compose/)
|
||||
- [Docker Desktop](https://www.docker.com/products/docker-desktop)
|
||||
- [WSL2 Installation Guide](https://docs.microsoft.com/en-us/windows/wsl/install)
|
||||
|
||||
## Next Steps
|
||||
|
||||
Once Docker is installed, you can:
|
||||
|
||||
1. Install Buque:
|
||||
```bash
|
||||
cd buque
|
||||
./install.sh
|
||||
```
|
||||
|
||||
2. Initialize Buque:
|
||||
```bash
|
||||
buque init
|
||||
```
|
||||
|
||||
3. Start managing your containers:
|
||||
```bash
|
||||
buque env add myapp /path/to/myapp
|
||||
buque up myapp
|
||||
```
|
||||
251
docs/PROJECT_STRUCTURE.md
Archivo normal
251
docs/PROJECT_STRUCTURE.md
Archivo normal
@@ -0,0 +1,251 @@
|
||||
# Buque Project Structure
|
||||
|
||||
```
|
||||
buque/
|
||||
├── cmd/
|
||||
│ └── buque/
|
||||
│ └── main.go # Application entry point
|
||||
│
|
||||
├── internal/
|
||||
│ ├── cmd/ # CLI command implementations
|
||||
│ │ ├── root.go # Root command and initialization
|
||||
│ │ ├── init.go # Initialize command
|
||||
│ │ ├── env.go # Environment management commands
|
||||
│ │ ├── compose.go # Docker Compose operations (up/down/restart/update)
|
||||
│ │ ├── stats.go # Statistics display command
|
||||
│ │ ├── logs.go # Log viewing and container listing
|
||||
│ │ ├── proxy.go # Nginx-proxy management commands
|
||||
│ │ └── utils.go # Utility functions
|
||||
│ │
|
||||
│ ├── config/
|
||||
│ │ └── config.go # Configuration management
|
||||
│ │
|
||||
│ ├── docker/
|
||||
│ │ ├── client.go # Docker API client wrapper
|
||||
│ │ └── compose.go # Docker Compose manager
|
||||
│ │
|
||||
│ ├── models/
|
||||
│ │ └── models.go # Data structures
|
||||
│ │
|
||||
│ ├── proxy/
|
||||
│ │ └── nginx.go # Nginx-proxy deployment and management
|
||||
│ │
|
||||
│ └── stats/
|
||||
│ └── collector.go # Container statistics collection
|
||||
│
|
||||
├── examples/
|
||||
│ ├── config.example.yaml # Example configuration file
|
||||
│ ├── docker-compose.example.yml # Basic docker-compose example
|
||||
│ ├── docker-compose.multi-service.yml # Multi-service example
|
||||
│ └── example_usage.go # Go library usage example
|
||||
│
|
||||
├── docs/
|
||||
│ ├── QUICK_START.md # Quick start guide
|
||||
│ └── DOCKER_SETUP.md # Docker installation guide
|
||||
│
|
||||
├── scripts/
|
||||
│ └── demo.sh # Interactive demo script
|
||||
│
|
||||
├── .github/
|
||||
│ └── workflows/
|
||||
│ └── ci.yml # GitHub Actions CI workflow
|
||||
│
|
||||
├── .gitignore # Git ignore rules
|
||||
├── CHANGELOG.md # Version history
|
||||
├── CONTRIBUTING.md # Contribution guidelines
|
||||
├── LICENSE # MIT License
|
||||
├── Makefile # Build automation
|
||||
├── README.md # Main documentation
|
||||
├── go.mod # Go module definition
|
||||
├── go.sum # Go dependencies checksum
|
||||
└── install.sh # Installation script
|
||||
```
|
||||
|
||||
## Key Components
|
||||
|
||||
### Core Packages
|
||||
|
||||
#### `cmd/buque`
|
||||
Main application entry point that initializes the CLI.
|
||||
|
||||
#### `internal/cmd`
|
||||
Contains all CLI command implementations using the Cobra framework:
|
||||
- Environment management (add, remove, list, enable, disable)
|
||||
- Container operations (up, down, restart, update, pull)
|
||||
- Monitoring and statistics
|
||||
- Nginx-proxy management
|
||||
- Logging and container listing
|
||||
|
||||
#### `internal/config`
|
||||
Configuration management system that:
|
||||
- Loads/saves YAML configuration
|
||||
- Manages environment list
|
||||
- Handles default settings
|
||||
- Validates configuration
|
||||
|
||||
#### `internal/docker`
|
||||
Docker integration layer:
|
||||
- **client.go**: Direct Docker API interactions (containers, images, networks, stats)
|
||||
- **compose.go**: Docker Compose command wrapper (up, down, pull, build, etc.)
|
||||
|
||||
#### `internal/models`
|
||||
Data structures for:
|
||||
- Environments
|
||||
- Services/Containers
|
||||
- Statistics
|
||||
- Configuration
|
||||
- Results and status
|
||||
|
||||
#### `internal/proxy`
|
||||
Nginx-proxy management:
|
||||
- Deployment automation
|
||||
- Docker Compose file generation
|
||||
- Network management
|
||||
- SSL/Let's Encrypt configuration
|
||||
- Service label generation
|
||||
|
||||
#### `internal/stats`
|
||||
Container statistics collection:
|
||||
- Real-time metrics (CPU, memory, network, disk)
|
||||
- Aggregation across containers
|
||||
- Continuous monitoring
|
||||
- Sorting and formatting
|
||||
|
||||
## Features by File
|
||||
|
||||
### Configuration Management
|
||||
- `internal/config/config.go`: Load, save, update configuration
|
||||
- `examples/config.example.yaml`: Configuration template
|
||||
|
||||
### Environment Management
|
||||
- `internal/cmd/env.go`: Add, remove, list, enable/disable environments
|
||||
- `internal/models/models.go`: Environment data structure
|
||||
|
||||
### Container Operations
|
||||
- `internal/cmd/compose.go`: Up, down, restart, update, pull commands
|
||||
- `internal/docker/compose.go`: Docker Compose execution
|
||||
|
||||
### Monitoring
|
||||
- `internal/cmd/stats.go`: Statistics display (continuous mode, sorting)
|
||||
- `internal/stats/collector.go`: Metrics collection and aggregation
|
||||
- `internal/docker/client.go`: Docker API for stats
|
||||
|
||||
### Nginx Proxy
|
||||
- `internal/cmd/proxy.go`: Deploy, remove, status, example commands
|
||||
- `internal/proxy/nginx.go`: Nginx-proxy setup and configuration
|
||||
|
||||
### Logging and Info
|
||||
- `internal/cmd/logs.go`: View logs, list containers, prune resources
|
||||
|
||||
## Build System
|
||||
|
||||
### Makefile Targets
|
||||
- `build`: Build the binary
|
||||
- `install`: Install to $GOPATH/bin
|
||||
- `test`: Run tests
|
||||
- `fmt`: Format code
|
||||
- `vet`: Run linter
|
||||
- `clean`: Remove build artifacts
|
||||
- `deps`: Download dependencies
|
||||
- `build-all`: Build for multiple platforms
|
||||
|
||||
### Installation
|
||||
- `install.sh`: Automated installation script
|
||||
- Checks prerequisites (Go, Docker, Docker Compose)
|
||||
- Builds and installs binary
|
||||
- Verifies installation
|
||||
|
||||
## Documentation
|
||||
|
||||
### User Documentation
|
||||
- `README.md`: Complete user guide with examples
|
||||
- `docs/QUICK_START.md`: Quick reference guide
|
||||
- `docs/DOCKER_SETUP.md`: Docker installation guide
|
||||
- `CONTRIBUTING.md`: Contribution guidelines
|
||||
- `CHANGELOG.md`: Version history
|
||||
|
||||
### Example Code
|
||||
- `examples/example_usage.go`: Library usage examples
|
||||
- `examples/*.yml`: Docker Compose templates
|
||||
- `scripts/demo.sh`: Interactive demonstration
|
||||
|
||||
## Development
|
||||
|
||||
### CI/CD
|
||||
- `.github/workflows/ci.yml`: GitHub Actions workflow
|
||||
- Runs tests
|
||||
- Builds for multiple platforms
|
||||
- Lints code
|
||||
|
||||
### Code Organization
|
||||
- Clear separation of concerns
|
||||
- Reusable components
|
||||
- Testable architecture
|
||||
- Idiomatic Go code
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Main Dependencies
|
||||
- `github.com/spf13/cobra`: CLI framework
|
||||
- `github.com/docker/docker`: Docker client
|
||||
- `gopkg.in/yaml.v3`: YAML parsing
|
||||
|
||||
### Build Tools
|
||||
- Go 1.21+
|
||||
- Make
|
||||
- Git
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### As CLI Tool
|
||||
Users interact through intuitive commands:
|
||||
```bash
|
||||
buque env add myapp /path/to/myapp
|
||||
buque up myapp
|
||||
buque stats --continuous
|
||||
```
|
||||
|
||||
### As Library
|
||||
Developers can import and use internal packages:
|
||||
```go
|
||||
import "github.com/yourusername/buque/internal/docker"
|
||||
|
||||
compose, _ := docker.NewComposeManager()
|
||||
compose.Up(ctx, environment, true)
|
||||
```
|
||||
|
||||
## Extension Points
|
||||
|
||||
### Adding New Commands
|
||||
1. Create command file in `internal/cmd/`
|
||||
2. Implement cobra.Command
|
||||
3. Add to root command in `internal/cmd/root.go`
|
||||
|
||||
### Adding New Features
|
||||
1. Update models in `internal/models/`
|
||||
2. Implement business logic in appropriate package
|
||||
3. Add CLI command to expose functionality
|
||||
4. Update documentation
|
||||
|
||||
### Custom Statistics
|
||||
Extend `internal/stats/collector.go` to add new metrics or aggregations.
|
||||
|
||||
### Custom Proxy Configurations
|
||||
Modify `internal/proxy/nginx.go` to support different proxy setups.
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests
|
||||
- Test individual functions and methods
|
||||
- Mock Docker API calls
|
||||
- Test configuration management
|
||||
|
||||
### Integration Tests
|
||||
- Test with real Docker daemon
|
||||
- Test compose operations
|
||||
- Test proxy deployment
|
||||
|
||||
### Manual Testing
|
||||
- Use `scripts/demo.sh` for manual verification
|
||||
- Test on different platforms
|
||||
- Verify documentation accuracy
|
||||
119
docs/QUICK_START.md
Archivo normal
119
docs/QUICK_START.md
Archivo normal
@@ -0,0 +1,119 @@
|
||||
# Buque Docker Compose Manager
|
||||
|
||||
## Quick Links
|
||||
|
||||
- [Installation](#installation)
|
||||
- [Quick Start](#quick-start)
|
||||
- [Commands](#commands)
|
||||
- [Examples](#examples)
|
||||
- [Configuration](#configuration)
|
||||
|
||||
## Installation
|
||||
|
||||
### Requirements
|
||||
- Go 1.21+
|
||||
- Docker 20.10+
|
||||
- Docker Compose V2
|
||||
|
||||
### Install from source
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/buque.git
|
||||
cd buque
|
||||
make install
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Initialize
|
||||
buque init
|
||||
|
||||
# Deploy nginx-proxy
|
||||
buque proxy deploy
|
||||
|
||||
# Add environment
|
||||
buque env add myapp /path/to/myapp
|
||||
|
||||
# Start environment
|
||||
buque up myapp
|
||||
|
||||
# Monitor containers
|
||||
buque stats --continuous
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `buque init` | Initialize configuration |
|
||||
| `buque env add <name> <path>` | Add environment |
|
||||
| `buque env list` | List environments |
|
||||
| `buque up [env...]` | Start environments |
|
||||
| `buque down [env...]` | Stop environments |
|
||||
| `buque restart [env...]` | Restart environments |
|
||||
| `buque update [env...]` | Update environments |
|
||||
| `buque stats [env]` | Show statistics |
|
||||
| `buque logs <env>` | View logs |
|
||||
| `buque ps [env...]` | List containers |
|
||||
| `buque proxy deploy` | Deploy nginx-proxy |
|
||||
| `buque pull [env...]` | Pull images |
|
||||
| `buque prune` | Clean up resources |
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic docker-compose.yml with nginx-proxy
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
web:
|
||||
image: nginx:alpine
|
||||
expose:
|
||||
- "80"
|
||||
environment:
|
||||
- VIRTUAL_HOST=example.com
|
||||
- LETSENCRYPT_HOST=example.com
|
||||
networks:
|
||||
- nginx-proxy
|
||||
labels:
|
||||
- "buque.environment=myapp"
|
||||
networks:
|
||||
nginx-proxy:
|
||||
external: true
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
|
||||
```bash
|
||||
# Real-time stats
|
||||
buque stats --continuous --interval 2
|
||||
|
||||
# Sort by memory
|
||||
buque stats --sort memory
|
||||
|
||||
# Environment-specific
|
||||
buque stats webapp
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Default location: `~/.buque/config.yaml`
|
||||
|
||||
```yaml
|
||||
environments:
|
||||
- name: webapp
|
||||
path: /path/to/webapp
|
||||
enabled: true
|
||||
|
||||
nginx_proxy:
|
||||
enabled: true
|
||||
network_name: nginx-proxy
|
||||
http_port: 80
|
||||
https_port: 443
|
||||
ssl_enabled: true
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT License - see [LICENSE](LICENSE) for details
|
||||
Referencia en una nueva incidencia
Block a user