Ga naar inhoud

Docker

Table of Contents

Installation

System Requirements

Intel Mac: - macOS version newer than Big Sur - 4GB available RAM - VirtualBox version 4.3.30 must NOT be installed - Download for Intel

Apple Silicon Mac (M1/M2/M3): - Docker Desktop 4.3.0+ (no specific system requirements) - Rosetta 2 must be installed - Download for Apple Silicon

Installing Rosetta 2

If you have Apple Silicon and Rosetta 2 isn't installed:

softwareupdate --install-rosetta

Tip

Not sure which chip you have? See: Determining Your Chipset

Installation Steps

  1. Download the appropriate Docker Desktop DMG for your chip architecture
  2. Open the .dmg file
  3. Drag Docker to Applications
  4. Launch Docker Desktop
  5. Follow the setup wizard

Running Databases

Overview

Run common databases in Docker containers for local development.

Benefits: - No local database installation needed - Isolated environments - Easy cleanup and reset - Consistent versions across team

MySQL 8.4

Run MySQL container:

sudo docker run -d \
  --restart unless-stopped \
  -p "127.0.0.1:3306:3306" \
  --name=mysql8 \
  -e MYSQL_ROOT_PASSWORD= \
  -e MYSQL_ALLOW_EMPTY_PASSWORD=true \
  mysql:8.4

Connection details: - Host: 127.0.0.1 - Port: 3306 - Username: root - Password: (empty)

Redis 7

Run Redis container:

sudo docker run -d \
  --restart unless-stopped \
  -p "127.0.0.1:6379:6379" \
  --name=redis \
  redis:7

Connection details: - Host: 127.0.0.1 - Port: 6379

PostgreSQL 16

Run PostgreSQL container:

sudo docker run -d \
  --restart unless-stopped \
  -p "127.0.0.1:5432:5432" \
  --name=postgres16 \
  -e POSTGRES_HOST_AUTH_METHOD=trust \
  postgres:16

Connection details: - Host: localhost - Port: 5432 - Username: postgres - Password: (none required, trust auth enabled)

Container Management

Start existing container:

docker start mysql8
docker start redis
docker start postgres16

Stop container:

docker stop mysql8

Remove container:

docker rm mysql8

View running containers:

docker ps

Error: Container Name Already in Use

If you see this error:

docker: Error response from daemon: Conflict. The container name "/postgres16" is already in use by container "...".

Solution: Start the existing container instead:

docker start postgres16

Resources: Omakub Dev Storage Setup

Rails Configuration

Configuring Rails with Docker PostgreSQL

Update config/database.yml:

development:
  adapter: postgresql
  encoding: unicode
  database: myapp_development
  pool: 5
  username: postgres  # Default postgres user
  password:           # No password (trust auth enabled)
  host: localhost
  port: 5432

Importing SQL Dump

Import database dump:

psql -h localhost -U postgres --no-password myapp_development < dump.sql

Example:

psql -h localhost -U postgres --no-password leu_app_development < PostgreSQL.sql

Troubleshooting

Docker DNS Timeout (Registry Connection Issues)

Error:

ERROR: failed to build: failed to resolve source metadata for docker.io/docker/dockerfile:1
dial tcp: lookup registry-1.docker.io on 10.0.0.10:53: read udp 172.17.0.3:55624->10.0.0.10:53: i/o timeout

Cause: Docker daemon's DNS cache is stale or network connections need reset.

Solution: Restart Docker daemon:

sudo systemctl restart docker

When this occurs: - After network changes - With long-running Docker daemon - DNS server changes - VPN connect/disconnect

Permanent fix (if issue persists):

Create /etc/docker/daemon.json:

{
  "dns": ["8.8.8.8", "8.8.4.4"]
}

Then restart Docker:

sudo systemctl restart docker

Kamal Deploy: insufficient_scope Error

Problem: When deploying with Kamal to GitLab Container Registry:

ERROR: failed to push registry.codepot.nl/lemone/app:...
server message: insufficient_scope: authorization failed

Cause: - BuildKit/Buildx tries to mount blobs (layers) from other repositories - Deploy token has push/pull rights on current repo but not on other repos - Results in insufficient_scope error

Solution: Add pre-build hook to disable cross-repo blob mounts.

Create .kamal/hooks/pre-build:

#!/usr/bin/env bash
# Purpose: Prepare a deterministic Buildx builder for Kamal.
# - Disables cross-repo blob mounts to avoid "insufficient_scope" errors.

set -euo pipefail

BUILDER_NAME="kamal-local-docker-container"

echo "[pre-build] Ensuring Buildx builder '${BUILDER_NAME}' exists (with blob mounts disabled)..."

docker buildx rm "${BUILDER_NAME}" >/dev/null 2>&1 || true
docker buildx create \
  --name "${BUILDER_NAME}" \
  --driver docker-container \
  --driver-opt env.BUILDKIT_DISABLE_BLOB_MOUNT=1 \
  --use

echo "[pre-build] Builder ready."

Make executable:

chmod +x .kamal/hooks/pre-build

Result: - No more insufficient_scope errors - Layers are uploaded instead of attempting cross-repo mounts - Deploys work reliably

Best Practices

  1. Use --restart unless-stopped - Containers restart automatically after reboot
  2. Bind to localhost - Use 127.0.0.1 instead of 0.0.0.0 for security
  3. Name your containers - Use --name for easy management
  4. Document credentials - Keep connection details in project README
  5. Clean up regularly - Remove unused containers and images

See Also