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
|
||||
Referencia en una nueva incidencia
Block a user