225 lines
4.4 KiB
Markdown
225 lines
4.4 KiB
Markdown
|
|
|
|
# Docker Module Documentation
|
|
|
|
The Docker module provides a comprehensive set of tools for working with Docker containers, images, and compose files in V. It offers high-level abstractions for common Docker operations while maintaining flexibility for advanced use cases.
|
|
|
|
## Core Components
|
|
|
|
### DockerEngine
|
|
|
|
The main entry point for Docker operations. It manages:
|
|
- Docker images and containers
|
|
- Build operations
|
|
- Registry interactions
|
|
- Platform-specific settings
|
|
|
|
```v
|
|
// Create a new Docker engine
|
|
mut engine := docker.new(
|
|
name: 'myengine'
|
|
localonly: true
|
|
)!
|
|
```
|
|
|
|
### DockerContainer
|
|
|
|
Represents a Docker container with operations for:
|
|
- Starting/stopping containers
|
|
- Shell access
|
|
- Port forwarding
|
|
- Volume mounting
|
|
- Container state management
|
|
|
|
```v
|
|
// Create and start a container
|
|
mut container := engine.container_create(
|
|
name: 'mycontainer'
|
|
image_repo: 'ubuntu'
|
|
image_tag: 'latest'
|
|
)!
|
|
container.start()!
|
|
```
|
|
|
|
### DockerImage
|
|
|
|
Handles Docker image operations:
|
|
- Image loading/saving
|
|
- Deletion
|
|
- Export/import
|
|
- Image metadata
|
|
|
|
```v
|
|
// Get an image by name
|
|
mut image := engine.image_get(
|
|
repo: 'ubuntu'
|
|
tag: 'latest'
|
|
)!
|
|
```
|
|
|
|
### DockerCompose
|
|
|
|
Manages Docker Compose operations:
|
|
- Service definitions
|
|
- Multi-container deployments
|
|
- Network configuration
|
|
- Volume management
|
|
|
|
```v
|
|
// Create a new compose configuration
|
|
mut composer := engine.compose_new(
|
|
name: 'myapp'
|
|
)!
|
|
|
|
// Add a service
|
|
mut service := composer.service_new(C
|
|
name: 'web'
|
|
image: 'nginx:latest'
|
|
)!
|
|
|
|
// Configure service
|
|
service.port_expose(80, 8080)!
|
|
service.env_add('NGINX_HOST', 'localhost')
|
|
service.restart_set()
|
|
|
|
// Start the compose stack
|
|
composer.start()!
|
|
```
|
|
|
|
### DockerRegistry
|
|
|
|
Provides functionality for:
|
|
- Registry setup and management
|
|
- Image pushing/pulling
|
|
- Authentication
|
|
- SSL configuration
|
|
|
|
## Recipe System
|
|
|
|
The module includes a powerful recipe system for building Docker images:
|
|
|
|
### DockerBuilderRecipe
|
|
|
|
Allows declarative definition of Docker images with:
|
|
- Multi-stage builds
|
|
- Package installation
|
|
- File operations
|
|
- Environment configuration
|
|
- Service initialization
|
|
|
|
```v
|
|
// Create a new recipe
|
|
mut recipe := engine.recipe_new(RecipeArgs{
|
|
name: 'myapp'
|
|
platform: .ubuntu
|
|
})!
|
|
|
|
// Add build steps
|
|
recipe.add_package(name: 'nginx,curl')!
|
|
recipe.add_copy(source: 'app', dest: '/app')!
|
|
recipe.add_env('APP_ENV', 'production')!
|
|
recipe.add_expose(ports: ['80/tcp'])!
|
|
|
|
// Build the image
|
|
recipe.build(false)!
|
|
```
|
|
|
|
### Recipe Components
|
|
|
|
The recipe system supports various Dockerfile instructions through specialized components:
|
|
|
|
- **FromItem**: Base image specification
|
|
- **RunItem**: Command execution
|
|
- **CmdItem**: Container entry point
|
|
- **EnvItem**: Environment variables
|
|
- **WorkDirItem**: Working directory
|
|
- **CopyItem**: File copying
|
|
- **ExposeItem**: Port exposure
|
|
- **VolumeItem**: Volume mounting
|
|
- **ZinitItem**: Process management
|
|
|
|
|
|
## Examples
|
|
|
|
### Basic Container Management
|
|
```v
|
|
// Create and manage a container
|
|
mut engine := docker.new(DockerEngineArgs{name: 'default'})!
|
|
mut container := engine.container_create(
|
|
name: 'webserver'
|
|
image_repo: 'nginx'
|
|
forwarded_ports: ['80:8080/tcp']
|
|
)!
|
|
container.start()!
|
|
```
|
|
|
|
### Custom Image Build
|
|
```v
|
|
mut recipe := engine.recipe_new(
|
|
name: 'custom-nginx'
|
|
platform: .ubuntu
|
|
)!
|
|
|
|
recipe.add_package(name: 'nginx')!
|
|
recipe.add_file_embedded(
|
|
source: 'nginx.conf'
|
|
dest: '/etc/nginx/nginx.conf'
|
|
)!
|
|
recipe.add_expose(ports: ['80/tcp'])!
|
|
|
|
recipe.build(false)!
|
|
```
|
|
|
|
### Multi-Container Setup
|
|
```v
|
|
mut composer := engine.compose_new(name: 'webapp')!
|
|
|
|
// Web service
|
|
mut web := composer.service_new
|
|
name: 'web'
|
|
image: 'nginx'
|
|
)!
|
|
web.port_expose(80, 8080)!
|
|
|
|
// Database service
|
|
mut db := composer.service_new(
|
|
name: 'db'
|
|
image: 'postgres'
|
|
)!
|
|
db.env_add('POSTGRES_PASSWORD', 'secret')
|
|
|
|
composer.start()!
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
The module provides specific error types for common scenarios:
|
|
|
|
- **ImageGetError**: Image retrieval issues
|
|
- **ContainerGetError**: Container access problems
|
|
|
|
Always handle these errors appropriately in your code:
|
|
|
|
```v
|
|
engine.image_get(
|
|
repo: 'nonexistent'
|
|
) or {
|
|
if err is ImageGetError {
|
|
if err.notfound {
|
|
// Handle missing image
|
|
}
|
|
}
|
|
return err
|
|
}
|
|
|
|
|
|
## Builders
|
|
|
|
see https://github.com/threefoldtech/vbuilders/tree/development/builders for examples
|
|
|
|
How to get started see
|
|
|
|
https://github.com/threefoldtech/vbuilders/blob/development/docsrc/src/gettingstarted/ubuntu/ubuntu.md
|
|
|
|
|