Skip to content

advanced-docker-configuration.md

Latest commit

 

History

History
352 lines (260 loc) · 5.69 KB

advanced-docker-configuration.md

File metadata and controls

352 lines (260 loc) · 5.69 KB

Advanced Docker Configuration

This guide covers advanced Docker configuration topics including user ID mapping, build arguments, network modes, and performance optimization.

UID/GID Mapping

The environment automatically maps your user ID and group ID into containers to avoid permission issues.

How It Works

When building containers, your UID and GID are passed as build arguments:

docker-compose build --build-arg UID=$(id -u) --build-arg GID=$(id -g)

This ensures:

  • Files created in containers have your ownership
  • You can edit files created by containers
  • No sudo needed for file operations

Verifying UID/GID

Check your IDs:

id -u  # Your UID
id -g  # Your GID

Check container user:

dev console
id

Should match your host user.

Custom UID/GID

To override the automatic detection, set in .env:

UID=1000
GID=1000

Docker Build Arguments

Build arguments customize container builds without modifying Dockerfiles.

Common Build Arguments

The environment supports:

  • UID - User ID
  • GID - Group ID
  • PHP_VERSION - PHP version for builds
  • COMPOSER_MEMORY_LIMIT - Composer memory limit

Setting Build Arguments

In docker-custom.yml:

version: '2'

services:
  php:
    build:
      context: custom/php
      args:
        PHP_VERSION: 8.3
        CUSTOM_ARG: value

Using Build Arguments in Dockerfile

In your custom Dockerfile:

ARG PHP_VERSION=8.2
FROM php:${PHP_VERSION}-fpm

ARG CUSTOM_ARG
RUN echo "Custom arg: ${CUSTOM_ARG}"

Network Modes

Default Bridge Network

Most services use the default bridge network, allowing container-to-container communication.

Services can reference each other by name:

// From PHP container
$redis = new Redis();
$redis->connect('redis', 6379);

$db = new PDO('mysql:host=db;dbname=mydb', 'user', 'pass');

Host Network Mode

Some services use host network mode for direct access to host networking:

  • ngrok - For tunneling
  • expose - For sharing

In docker-custom.yml:

services:
  myservice:
    network_mode: host

Custom Networks

Create isolated networks for specific services:

version: '2'

services:
  myapp:
    networks:
      - frontend
      - backend

  mydb:
    networks:
      - backend

networks:
  frontend:
  backend:
    internal: true  # No external access

Volume Performance

Linux

On Linux, volumes have native performance. Use bind mounts freely:

volumes:
  - ./workspace:/data/workspace

macOS Performance

On macOS, use Docker volumes instead of bind mounts for better performance:

dev volume workspace workspace

Or use delegated/cached modes:

volumes:
  - ./workspace:/data/workspace:delegated

Windows

Similar to macOS, Docker volumes offer better performance than bind mounts.

Resource Limits

Limit container resources to prevent one service from consuming all resources.

Memory Limits

In docker-custom.yml:

services:
  db:
    mem_limit: 2g
    memswap_limit: 2g

  elasticsearch:
    mem_limit: 1g
    environment:
      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"

CPU Limits

services:
  php:
    cpus: '2.0'  # Use up to 2 CPU cores
    cpu_shares: 1024  # Relative weight

Container Restart Policies

Control what happens when containers exit:

services:
  critical-service:
    restart: always

  optional-service:
    restart: unless-stopped

  dev-tool:
    restart: "no"

Docker Compose Version

The environment uses Compose file version 2 for compatibility:

version: '2'

Version 2 provides:

  • Wide compatibility
  • Named volumes
  • Network support
  • Stable feature set

BuildKit

Enable Docker BuildKit for faster, more efficient builds:

export DOCKER_BUILDKIT=1
dev rebuild

Or permanently in ~/.bashrc or ~/.zshrc:

export DOCKER_BUILDKIT=1

Benefits:

  • Parallel build stages
  • Better layer caching
  • Reduced build time
  • Lower disk usage

Health Checks

Add health checks to services:

services:
  db:
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 30s

Check health status:

dev ps

Logging Configuration

Control container log output:

services:
  php:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

This prevents logs from consuming excessive disk space.

Security Considerations

Read-Only Filesystems

Make containers more secure with read-only filesystems:

services:
  web:
    read_only: true
    tmpfs:
      - /tmp
      - /var/run

Drop Capabilities

Remove unnecessary Linux capabilities:

services:
  app:
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE

User Namespace Remapping

For additional security, enable Docker user namespace remapping. See Docker documentation.

Troubleshooting

Permission Errors

Rebuild with correct UID/GID:

dev rebuild

Or fix permissions on host:

sudo chown -R $USER:$USER workspace/

Network Issues

Inspect networks:

docker network ls
docker network inspect dockerdev_default

Build Cache Issues

Clear build cache:

docker builder prune
dev rebuild --no-cache

Resource Exhaustion

Check resource usage:

dev top
docker system df

Clean up:

docker system prune -a
docker volume prune

See Also