Skip to content

Local Containerized Development using Colima

This guide provides a step-by-step checklist to configure, run, and monitor a local containerized development stack on macOS using Colima (as a lightweight replacement for Docker Desktop) and Docker Compose, with PostgreSQL and a dynamic SQLite fallback database.

🛠️ Step-by-Step Configuration

1. Initialize and Start Colima

Colima provides a container runtime environment on macOS. If you do not have Docker Desktop, start Colima to launch the background Linux VM and expose the Docker daemon API socket:

# Initialize and boot the Colima VM runtime
colima start

Daemon Socket Availability

Once started, Colima will map the Linux guest VM Docker socket to unix:///Users/username/.config/colima/default/docker.sock and symlink it to standard host paths so that docker and docker-compose can execute transparently.

2. Configure Your Database Portability

Your application should be able to seamlessly run in Docker using PostgreSQL, while falling back to SQLite for zero-dependency local runs.

Ensure your config/database.py contains a dynamic switch based on environment variables:

import os
import psycopg

def get_db(name: str|None = None, reset: bool = False) -> None:
    global conn, curs

    database_url = os.getenv("DATABASE_URL")
    postgres_host = os.getenv("POSTGRES_HOST")

    if database_url or postgres_host:
        # PostgreSQL Backend (Inside Docker)
        conn = psycopg.connect(...)
    else:
        # SQLite Fallback Backend (Native Local Run)
        from sqlite3 import connect as sqlite_connect
        conn = sqlite_connect(...)

3. Expose the Application Port

Configure your local development docker-compose.yml to expose your server on port 4000 (matching your native environment) while preserving internal container port mappings:

services:
  fastapi-app:
    build: .
    ports:
      - "4000:8000"

4. Enable Volume Polling for Code Watchers

When running watchers (like file compilers) inside Docker containers on macOS guest VMs, native filesystem events (such as inotify) may not trigger due to directory sync limitations.

Ensure you enable polling for watch processes in your container configuration:

  environment:
    - TAILWIND_POLL=true  # Forces watchers to poll directories rather than wait for OS filesystem events

5. Launch the Container Stack

Build and deploy the containers in detached (background) mode:

# Launch Compose services
docker-compose up -d --build

6. Monitor Containers via lazydocker

To monitor logs, CPU, and container processes in a beautiful terminal dashboard, install and use lazydocker:

# Install lazydocker via Homebrew
brew install jesseduffield/lazydocker/lazydocker

# Start the interactive terminal UI dashboard
lazydocker

Keyboard-Focused Navigation

Inside lazydocker, press Enter on a service to view its live logs, use arrow keys to navigate between networks, volumes, and images, and press x to show the power menu (restart, stop, rebuild).