# Core Container Management

The fundamental Docker container lifecycle management capabilities that form the foundation of all testcontainers functionality. The DockerContainer class provides comprehensive configuration options, networking, volume mounting, and environment setup through a fluent API.

## Capabilities

### Basic Container Operations

Core container lifecycle management including creation, startup, shutdown, and resource cleanup with automatic or manual control.

```python { .api }
class DockerContainer:
    def __init__(
        self,
        image: str,
        docker_client_kw: Optional[dict[str, Any]] = None,
        command: Optional[str] = None,
        env: Optional[dict[str, str]] = None,
        name: Optional[str] = None,
        ports: Optional[list[int]] = None,
        volumes: Optional[list[tuple[str, str, str]]] = None,
        network: Optional[Network] = None,
        network_aliases: Optional[list[str]] = None,
        **kwargs: Any
    ):
        """
        Initialize a Docker container.
        
        Args:
            image: Docker image name and tag
            docker_client_kw: Docker client configuration
            command: Container command to execute
            env: Environment variables dictionary
            name: Container name
            ports: Ports to expose
            volumes: Volume mounts as (host_path, container_path, mode) tuples
            network: Network to connect to
            network_aliases: Network aliases for the container
            **kwargs: Additional Docker container options
        """

    def start(self) -> "DockerContainer":
        """
        Start the container.
        
        Returns:
            Self for method chaining
        """

    def stop(self, force: bool = True, delete_volume: bool = True) -> None:
        """
        Stop and remove the container.
        
        Args:
            force: Force container removal
            delete_volume: Delete associated volumes
        """

    def __enter__(self) -> "DockerContainer":
        """Context manager entry - starts container."""

    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
        """Context manager exit - stops container."""
```

### Container Configuration

Fluent API for configuring container properties including environment variables, ports, volumes, networking, and Docker-specific options.

```python { .api }
def with_env(self, key: str, value: str) -> "DockerContainer":
    """
    Add environment variable.
    
    Args:
        key: Environment variable name
        value: Environment variable value
        
    Returns:
        Self for method chaining
    """

def with_envs(self, **variables: str) -> "DockerContainer":
    """
    Add multiple environment variables.
    
    Args:
        **variables: Environment variables as keyword arguments
        
    Returns:
        Self for method chaining
    """

def with_env_file(self, env_file: Union[str, PathLike]) -> "DockerContainer":
    """
    Load environment variables from file.
    
    Args:
        env_file: Path to environment file
        
    Returns:
        Self for method chaining
    """

def with_command(self, command: Union[str, list[str]]) -> "DockerContainer":
    """
    Set container command.
    
    Args:
        command: Command to execute in container
        
    Returns:
        Self for method chaining
    """

def with_name(self, name: str) -> "DockerContainer":
    """
    Set container name.
    
    Args:
        name: Container name
        
    Returns:
        Self for method chaining
    """

def with_kwargs(self, **kwargs: Any) -> "DockerContainer":
    """
    Add Docker container creation arguments.
    
    Args:
        **kwargs: Docker client container creation arguments
        
    Returns:
        Self for method chaining
    """

def with_user(self, user: str) -> "DockerContainer":
    """
    Set container user.
    
    Args:
        user: User to run container as (user or user:group)
        
    Returns:
        Self for method chaining
    """

def with_working_directory(self, working_directory: str) -> "DockerContainer":
    """
    Set container working directory.
    
    Args:
        working_directory: Working directory path
        
    Returns:
        Self for method chaining
    """
```

### Port Management

Configure port exposure and binding for container network access, supporting both automatic port assignment and explicit host port binding.

```python { .api }
def with_exposed_ports(self, *ports: int) -> "DockerContainer":
    """
    Expose ports without binding to host ports.
    
    Args:
        *ports: Port numbers to expose
        
    Returns:
        Self for method chaining
    """

def with_bind_ports(self, container: int, host: Optional[int] = None) -> "DockerContainer":
    """
    Bind container port to specific host port.
    
    Args:
        container: Container port number
        host: Host port number (random if None)
        
    Returns:
        Self for method chaining
    """

def get_exposed_port(self, port: int) -> str:
    """
    Get the host port mapped to container port.
    
    Args:
        port: Container port number
        
    Returns:
        Host port number as string
        
    Raises:
        NoSuchPortExposed: If port not exposed
    """

def get_container_host_ip(self) -> str:
    """
    Get the IP address to connect to the container.
    
    Returns:
        IP address string
    """
```

### Volume Management

Mount host directories and files into containers with configurable access modes and path mapping.

```python { .api }
def with_volume_mapping(self, host: str, container: str, mode: str = "ro") -> "DockerContainer":
    """
    Mount host path into container.
    
    Args:
        host: Host filesystem path
        container: Container filesystem path
        mode: Mount mode ('ro', 'rw', 'z', 'Z')
        
    Returns:
        Self for method chaining
    """
```

### Network Configuration

Connect containers to Docker networks with custom aliases and network-specific configuration.

```python { .api }
def with_network(self, network: Network) -> "DockerContainer":
    """
    Connect container to network.
    
    Args:
        network: Network instance to connect to
        
    Returns:
        Self for method chaining
    """

def with_network_aliases(self, *aliases: str) -> "DockerContainer":
    """
    Set network aliases for container.
    
    Args:
        *aliases: Network alias names
        
    Returns:
        Self for method chaining
    """
```

### Container Inspection and Control

Access container runtime information, execute commands, and retrieve logs for debugging and integration.

```python { .api }
def get_wrapped_container(self) -> "Container":
    """
    Get the underlying Docker container object.
    
    Returns:
        Docker container instance
    """

def get_docker_client(self) -> DockerClient:
    """
    Get the Docker client instance.
    
    Returns:
        Docker client
    """

def get_logs(self) -> tuple[bytes, bytes]:
    """
    Get container logs.
    
    Returns:
        Tuple of (stdout, stderr) as bytes
    """

def exec(self, command: Union[str, list[str]]) -> ExecResult:
    """
    Execute command in running container.
    
    Args:
        command: Command to execute
        
    Returns:
        Execution result with exit_code and output
    """
```

### Platform Compatibility

Handle cross-platform differences and architecture emulation for consistent behavior across development environments.

```python { .api }
def maybe_emulate_amd64(self) -> "DockerContainer":
    """
    Enable AMD64 emulation on ARM platforms.
    
    Returns:
        Self for method chaining
    """
```

## Usage Examples

### Basic Container Usage

```python
from testcontainers.core.container import DockerContainer

# Simple container with automatic cleanup
with DockerContainer("nginx:alpine") as container:
    container.with_exposed_ports(80)
    host_port = container.get_exposed_port(80)
    host_ip = container.get_container_host_ip()
    print(f"Nginx available at http://{host_ip}:{host_port}")
```

### Advanced Configuration

```python
from testcontainers.core.container import DockerContainer
from testcontainers.core.network import Network

# Create custom network
with Network() as network:
    # Configure container with multiple options
    container = DockerContainer("postgres:13") \
        .with_env("POSTGRES_DB", "testdb") \
        .with_env("POSTGRES_USER", "testuser") \
        .with_env("POSTGRES_PASSWORD", "testpass") \
        .with_exposed_ports(5432) \
        .with_volume_mapping("./data", "/var/lib/postgresql/data", "rw") \
        .with_network(network) \
        .with_network_aliases("database", "db") \
        .with_name("test-postgres")
    
    with container:
        # Container is now running with full configuration
        connection_host = container.get_container_host_ip()
        connection_port = container.get_exposed_port(5432)
```

### Command Execution

```python
with DockerContainer("ubuntu:20.04") as container:
    container.with_command("sleep 30")
    
    # Execute commands in running container
    result = container.exec("ls -la /")
    print(f"Exit code: {result.exit_code}")
    print(f"Output: {result.output.decode()}")
    
    # Get container logs
    stdout, stderr = container.get_logs()
    print(f"Container output: {stdout.decode()}")
```

## Types

```python { .api }
class Mount(TypedDict):
    bind: str  # Container path
    mode: str  # Mount mode ('ro', 'rw', etc.)

class Network:
    def __init__(
        self,
        docker_client_kw: Optional[dict] = None,
        docker_network_kw: Optional[dict] = None
    ): ...
    
    def create(self) -> "Network": ...
    def remove(self) -> None: ...
    def connect(self, container_id: str, network_aliases: Optional[list[str]] = None) -> None: ...
    
    @property
    def name(self) -> str: ...
    
    @property
    def id(self) -> str: ...
```