Supercharge Your Container Development with Colima: The Ultimate Setup Guide

Build a complete Node.js, PostgreSQL, and Redis stack without melting your CPU

9 min readNov 30, 2024

In today’s cloud-native development landscape, containers have become an essential part of our toolkit. However, running containers locally can sometimes feel like trying to fit a cargo ship in your backyard pool — especially when using heavyweight solutions like Docker Desktop. Enter Colima, a lightweight alternative that’s changing how developers work with containers on their local machines.

Colima means Containers on Lima. Since Lima is aka Linux Machines. By transitivity, Colima can also mean Containers on Linux Machines.

In this comprehensive guide, we’ll build a real-world development environment while exploring what makes Colima special. Whether you’re a seasoned container orchestrator or just starting your containerization journey, this guide will help you understand why Colima might be the missing piece in your development workflow.

Understanding Container Runtime Environments

Before we dive into installation, let’s understand what a container runtime environment does and why it matters. When you run containers on Linux, they run natively because containers are built on Linux kernel features. However, on macOS and Windows, we need a lightweight virtual machine to provide these Linux kernel features. This is where tools like Colima come in.

Think of it like this: If Docker Desktop is a full-service hotel with every amenity imaginable, Colima is more like a well-designed apartment that provides exactly what you need, nothing more, nothing less. This focused approach is what makes Colima particularly efficient.

Installing Colima: Setting Up Your Development Environment

The installation process reflects Colima’s philosophy of simplicity. While Docker Desktop requires you to download an installer, click through various options, and restart your system, Colima’s installation is straightforward and transparent.

# Install Colima using Homebrew
brew install colima

# Install Docker CLI if you haven't already
brew install docker docker-compose

Starting Colima: Resource Allocation and Configuration

When starting Colima, you have precise control over resource allocation. This is crucial for optimizing your development environment based on your specific needs.

# Start Colima with custom resources
colima start --cpu 4 --memory 8 --disk 100

Let’s break down these parameters:

--cpu 4: Allocates 4 CPU cores to the VM
--memory 8: Provides 8GB of RAM
--disk 100: Allocates 100GB of disk space

Why these specific numbers? Let’s consider some common development scenarios:

Running a web application with hot reloading: 2–4 CPU cores
Database operations and caching: 4–8GB RAM
Docker images and volumes: 50–100GB disk space

You can adjust these based on your machine’s capabilities and project requirements. Unlike Docker Desktop, which often takes a one-size-fits-all approach, Colima lets you fine-tune your resource allocation.

Real-World Example: Building a Web Development Environment

Let’s build something practical — a modern web development stack that you might use in a real project. We’ll create a setup that includes:

A Node.js web application (representing your backend service)
A PostgreSQL database (for persistent data storage)
A Redis cache (for session management and caching)

This architecture represents a common pattern in production applications, where you need to handle both persistent data and high-speed caching.

Simple CRUD task app with docker + colima

Step 1: Creating a Project Structure

First, let’s set up our project structure. This organization reflects real-world application architecture:

mkdir colima-demo
cd colima-demo

# Create application structure
mkdir app
touch app/index.js
touch app/package.json
touch Dockerfile
touch docker-compose.yml

The structure matters because it separates concerns:

app/: Contains your application code
app/package.json: Npm package
Dockerfile: Defines how to build your application container
docker-compose.yml: Orchestrates your entire development environment

Step 2: Creating a Node.js Application

Our application will demonstrate common patterns in web development database interactions, caching, and HTTP serving. This CRUD implementation includes:

Features:

Complete CRUD operations for tasks
Redis caching with automatic invalidation
Input validation
Error handling
Database initialization
Health check endpoint

// app/package.json
{
    "name": "colima-demo",
    "version": "1.0.0",
    "description": "Demo application for Colima",
    "main": "index.js",
    "scripts": {
      "start": "node index.js"
    },
    "dependencies": {
      "express": "^4.18.2",
      "pg": "^8.11.3",
      "ioredis": "^5.3.2"
    }
  }

// app/index.js
const express = require('express');
const { Pool } = require('pg');
const Redis = require('ioredis');

const app = express();
const port = 3000;

// Middleware for parsing JSON bodies
app.use(express.json());

// PostgreSQL connection
const pool = new Pool({
  host: 'postgres',
  database: 'myapp',
  user: 'postgres',
  password: 'secretpassword'
});

// Redis connection with retry strategy
const redis = new Redis({
  host: 'redis',
  retryStrategy: (times) => {
    const delay = Math.min(times * 50, 2000);
    return delay;
  }
});

// Initialize PostgreSQL table
const initDb = async () => {
  try {
    await pool.query(`
      CREATE TABLE IF NOT EXISTS tasks (
        id SERIAL PRIMARY KEY,
        title VARCHAR(255) NOT NULL,
        description TEXT,
        status VARCHAR(50) DEFAULT 'pending',
        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
      )
    `);
    console.log('Database initialized');
  } catch (error) {
    console.error('Database initialization error:', error);
  }
};

initDb();

// Cache middleware
const cacheMiddleware = async (req, res, next) => {
  if (req.method === 'GET') {
    try {
      const cacheKey = `task:${req.params.id || 'all'}`;
      const cachedData = await redis.get(cacheKey);
      
      if (cachedData) {
        console.log('Cache hit');
        return res.json(JSON.parse(cachedData));
      }
    } catch (error) {
      console.error('Cache error:', error);
    }
  }
  next();
};

// CREATE - Create a new task
app.post('/tasks', async (req, res) => {
  try {
    const { title, description } = req.body;
    
    if (!title) {
      return res.status(400).json({ error: 'Title is required' });
    }

    const result = await pool.query(
      'INSERT INTO tasks (title, description) VALUES ($1, $2) RETURNING *',
      [title, description]
    );

    // Invalidate cache for all tasks
    await redis.del('task:all');

    res.status(201).json(result.rows[0]);
  } catch (error) {
    console.error('Error creating task:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

// READ - Get all tasks
app.get('/tasks', cacheMiddleware, async (req, res) => {
  try {
    const result = await pool.query('SELECT * FROM tasks ORDER BY created_at DESC');
    
    // Cache the results for 1 minute
    await redis.setex('task:all', 60, JSON.stringify(result.rows));
    
    res.json(result.rows);
  } catch (error) {
    console.error('Error fetching tasks:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

// READ - Get single task
app.get('/tasks/:id', cacheMiddleware, async (req, res) => {
  try {
    const { id } = req.params;
    const result = await pool.query('SELECT * FROM tasks WHERE id = $1', [id]);
    
    if (result.rows.length === 0) {
      return res.status(404).json({ error: 'Task not found' });
    }

    // Cache the result for 1 minute
    await redis.setex(`task:${id}`, 60, JSON.stringify(result.rows[0]));
    
    res.json(result.rows[0]);
  } catch (error) {
    console.error('Error fetching task:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

// UPDATE - Update a task
app.put('/tasks/:id', async (req, res) => {
  try {
    const { id } = req.params;
    const { title, description, status } = req.body;
    
    if (!title) {
      return res.status(400).json({ error: 'Title is required' });
    }

    const result = await pool.query(
      'UPDATE tasks SET title = $1, description = $2, status = $3 WHERE id = $4 RETURNING *',
      [title, description, status, id]
    );

    if (result.rows.length === 0) {
      return res.status(404).json({ error: 'Task not found' });
    }

    // Invalidate related caches
    await Promise.all([
      redis.del(`task:${id}`),
      redis.del('task:all')
    ]);

    res.json(result.rows[0]);
  } catch (error) {
    console.error('Error updating task:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

// DELETE - Delete a task
app.delete('/tasks/:id', async (req, res) => {
  try {
    const { id } = req.params;
    const result = await pool.query('DELETE FROM tasks WHERE id = $1 RETURNING *', [id]);
    
    if (result.rows.length === 0) {
      return res.status(404).json({ error: 'Task not found' });
    }

    // Invalidate related caches
    await Promise.all([
      redis.del(`task:${id}`),
      redis.del('task:all')
    ]);

    res.json({ message: 'Task deleted successfully' });
  } catch (error) {
    console.error('Error deleting task:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

// Health check endpoint
app.get('/health', (req, res) => {
  res.json({ status: 'healthy' });
});

// Error handling middleware
app.use((err, req, res, next) => {
  console.error('Unhandled error:', err);
  res.status(500).json({ error: 'Something went wrong!' });
});

// Graceful shutdown
process.on('SIGTERM', async () => {
  console.log('Received SIGTERM. Performing graceful shutdown...');
  
  try {
    await pool.end();
    await redis.quit();
    process.exit(0);
  } catch (error) {
    console.error('Error during shutdown:', error);
    process.exit(1);
  }
});

app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

Key Features:

Uses parameterized queries for SQL injection prevention
Implements caching middleware for GET requests
Includes proper error handling and validation
Manages cache invalidation on updates/deletes
Includes graceful shutdown handling

Step 3: Creating a Production-Ready Dockerfile

Our Dockerfile needs to be efficient and secure for production use:

FROM node:16-alpine

# Create non-root user for security
RUN addgroup -S appgroup && adduser -S appuser -G appgroup

WORKDIR /app

# Copy package files first to leverage Docker cache
COPY app/package*.json ./

# Install dependencies
RUN npm install --production

# Copy application code
COPY app .

# Set ownership to non-root user
RUN chown -R appuser:appgroup /app

# Switch to non-root user
USER appuser

EXPOSE 3000

# Use exec form for proper signal handling
CMD ["node", "index.js"]

This Dockerfile includes several best practices:

Multi-stage builds for smaller images
Non-root user for security
Proper signal handling
Efficient layer caching

Step 4: Orchestrating with Docker Compose

The Docker Compose file is your environment’s blueprint:

version: '3.8'

services:
  web:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    environment:
      NODE_ENV: development
    healthcheck:
      test: ["CMD", "wget", "--spider", "http://localhost:3000"]
      interval: 10s
      timeout: 5s
      retries: 3

  postgres:
    image: postgres:14-alpine
    environment:
      POSTGRES_DB: myapp
      POSTGRES_PASSWORD: secretpassword
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 3

  redis:
    image: redis:alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3

volumes:
  postgres_data:
  redis_data:

This configuration includes several production-ready features:

Health checks for all services
Proper dependency ordering
Volume management for persistence
Environment variable configuration

Step 5: Running and Managing Your Application

Now let’s look at common development workflows:

# Start everything in development mode
docker-compose up -d

# View logs with timestamps
docker-compose logs -f --timestamps

# Scale specific services
docker-compose up -d --scale web=3

# Check resource usage
docker stats

Step 6: Testing your app

You can testing your app using CURL or using API platform like Postman

# Create a task
curl -X POST http://localhost:3000/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "Learn Colima", "description": "Master container development"}'

# Get all tasks
curl http://localhost:3000/tasks

# Get single task
curl http://localhost:3000/tasks/1

# Update a task
curl -X PUT http://localhost:3000/tasks/1 \
  -H "Content-Type: application/json" \
  -d '{"title": "Learn Colima", "description": "Master container development", "status": "completed"}'

# Delete a task
curl -X DELETE http://localhost:3000/tasks/1

Production Considerations

When moving from development to production, consider:

1. Security

Use secrets management instead of environment variables
Implement proper logging and monitoring
Set up appropriate network policies

2. Scalability

Use proper load balancing
Implement caching strategies
Set up proper database indexing

3. Maintenance

Regular backup strategies
Update and patch management
Monitoring and alerting setup

Conclusion

Colima provides a lightweight, efficient way to run containers locally while maintaining compatibility with your existing Docker workflows. Its resource-efficient approach and straightforward configuration make it an excellent choice for development environments.

Remember these key points:

Start with minimal resources and scale as needed
Use health checks for robust service management
Implement proper logging and monitoring
Consider security from the start

By following these practices and understanding how Colima works under the hood, you can create efficient, production-like development environments that don’t overwhelm your local machine.

If you’re interested in diving deeper into system design and backend development, be sure to follow me for more insights, tips, and practical examples. Together, we can explore the intricacies of creating efficient systems, optimizing database performance, and mastering the tools that drive modern applications. Join me on this journey to enhance your skills and stay updated on the latest trends in the tech world! 🚀

Read the design system in bahasa on iniakunhuda.com