252 líneas
7.5 KiB
Markdown
252 líneas
7.5 KiB
Markdown
# 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
|