Dev.to

Corgi: The CLI That Tames Your Local Microservices Chaos

Microservices architecture gives us flexibility and scale, but the local development experience? It's a nightmare of tangled dependencies, Docker scripts, and that recurring question: 'How do I seed this database again?'. After one too many onboarding sessions that took hours instead of minutes, I built Corgi, an open-source Go CLI that launches your entire stack with a single command. It's not Docker Compose with a pretty face—it's a fundamentally different approach that containerizes only what needs isolation (databases) while running your services natively for better performance and lower resource usage In this post, I'll walk you through why I created Corgi, what makes it special, and how it can transform your team's development workflow—all from a simple YAML file. The Problem: Microservices Development Was Too Chaotic A while back, I was working on a project with multiple microservices, each with its own database requirements. We faced several challenges: Onboarding new developers took hours of explanation and troubleshooting Database seeding was inconsistent and required manual steps Service dependencies had to be launched in a specific order Environment variables were difficult to manage across services and filled manually I tried existing solutions like Docker Compose and Kubernetes, but they either felt too heavy or didn't solve our specific problems: Docker Compose is solid but lacks native DB seeding or service orchestration smarts. It also runs everything in containers, which consumes more resources than necessary for local development. Custom Scripts are a maintenance nightmare and don't scale across teams Cloud Tools want your data and your wallet, neither of which I'm keen to hand over I wanted something that would make running our entire stack locally as simple as a single command, but with the efficiency of running services natively when appropriate. When I couldn't find it, I built Corgi. What Makes Corgi Special? Corgi is like a loyal companion that cuts through the chaos. Here's what sets it apart: Define Once, Run Anywhere: Write a corgi-compose.yml file with your services and DBs. One command corgi run and everything launches. Share that file with your team, and they're up in minutes. Database Superpowers: Seed Postgres, MongoDB, Redis (and 30+ others) from SQL dumps or remote DBs. No more manual imports or stale test data. Parallel Power: Services start concurrently, not in some sluggish sequence. Your API and frontend are live at the same time, every time. Auto Git Clone: Repositories specified with cloneFrom are automatically cloned during initialization, ensuring everyone on your team has the exact same code structure. If they were cloned already, they are not cloned again. Smart Environment Management: Automatically connect services with the right environment variables. When you specify dependencies using depends_on_services and depends_on_db, Corgi populates each service's .env file with the correct connection information. For database dependencies, it adds credentials (DB_HOST, DB_USER, etc.), and for service dependencies, it adds URLs like SERVICE_NAME=http://localhost:3000. No more manual environment configuration or copying connection strings. Resource Efficiency: Only containerizes databases while running your services natively, saving significant CPU and memory compared to full containerization Simple YAML Configuration: Describe your entire project in one readable file and check its syntax with dedicated vscode corgi extension It's not flashy—it's functional. Getting Started Ready to give Corgi a spin? Here's how to get started: Install Corgi with Homebrew: brew install andriiklymiuk/homebrew-tools/corgi # Check if it works corgi -h Create a simple corgi-compose.yml file in your project with db or services part Run corgi init followed by corgi run Want to try an example project? Run: corgi run -t https://github.com/Andriiklymiuk/corgi_examples/blob/main/honoExpoTodo/hono-bun-expo.corgi-compose.yml This will download and run a sample Todo app with a Hono backend and an Expo frontend. Under the Hood: How Corgi Works Unlike Docker Compose, which containerizes everything, Corgi takes a hybrid approach: Databases run in Docker: Corgi creates Docker container templates for your databases, making them easy to start, stop, and clean up. Services run natively: Your actual applications (Node.js servers, Go APIs, React frontends, etc.) run directly on your machine, saving CPU and memory. Environment auto-wiring: Corgi automatically connects everything by generating the right environment variables and .env files. Parallel execution: Service commands run concurrently, making startup much faster. This hybrid approach gives you the best of both worlds: the isolation of Docker for databases with the performance of native execution for your applications. How I

Mar 24, 2025 - 13:38
 0
Corgi: The CLI That Tames Your Local Microservices Chaos

Microservices architecture gives us flexibility and scale, but the local development experience? It's a nightmare of tangled dependencies, Docker scripts, and that recurring question: 'How do I seed this database again?'. After one too many onboarding sessions that took hours instead of minutes, I built Corgi, an open-source Go CLI that launches your entire stack with a single command. It's not Docker Compose with a pretty face—it's a fundamentally different approach that containerizes only what needs isolation (databases) while running your services natively for better performance and lower resource usage

In this post, I'll walk you through why I created Corgi, what makes it special, and how it can transform your team's development workflow—all from a simple YAML file.

The Problem: Microservices Development Was Too Chaotic

A while back, I was working on a project with multiple microservices, each with its own database requirements. We faced several challenges:

  • Onboarding new developers took hours of explanation and troubleshooting
  • Database seeding was inconsistent and required manual steps
  • Service dependencies had to be launched in a specific order
  • Environment variables were difficult to manage across services and filled manually

Why

I tried existing solutions like Docker Compose and Kubernetes, but they either felt too heavy or didn't solve our specific problems:

  • Docker Compose is solid but lacks native DB seeding or service orchestration smarts. It also runs everything in containers, which consumes more resources than necessary for local development.
  • Custom Scripts are a maintenance nightmare and don't scale across teams
  • Cloud Tools want your data and your wallet, neither of which I'm keen to hand over

I wanted something that would make running our entire stack locally as simple as a single command, but with the efficiency of running services natively when appropriate. When I couldn't find it, I built Corgi.

What Makes Corgi Special?

Corgi is like a loyal companion that cuts through the chaos. Here's what sets it apart:

  • Define Once, Run Anywhere: Write a corgi-compose.yml file with your services and DBs. One command corgi run and everything launches. Share that file with your team, and they're up in minutes.
  • Database Superpowers: Seed Postgres, MongoDB, Redis (and 30+ others) from SQL dumps or remote DBs. No more manual imports or stale test data.
  • Parallel Power: Services start concurrently, not in some sluggish sequence. Your API and frontend are live at the same time, every time.
  • Auto Git Clone: Repositories specified with cloneFrom are automatically cloned during initialization, ensuring everyone on your team has the exact same code structure. If they were cloned already, they are not cloned again.
  • Smart Environment Management: Automatically connect services with the right environment variables. When you specify dependencies using depends_on_services and depends_on_db, Corgi populates each service's .env file with the correct connection information. For database dependencies, it adds credentials (DB_HOST, DB_USER, etc.), and for service dependencies, it adds URLs like SERVICE_NAME=http://localhost:3000. No more manual environment configuration or copying connection strings.
  • Resource Efficiency: Only containerizes databases while running your services natively, saving significant CPU and memory compared to full containerization
  • Simple YAML Configuration: Describe your entire project in one readable file and check its syntax with dedicated vscode corgi extension

It's not flashy—it's functional.

Getting Started

Ready to give Corgi a spin? Here's how to get started:

  1. Install Corgi with Homebrew: 
   brew install andriiklymiuk/homebrew-tools/corgi

   # Check if it works
   corgi -h
  1. Create a simple corgi-compose.yml file in your project with db or services part
  2. Run corgi init followed by corgi run

Want to try an example project? Run:

corgi run -t https://github.com/Andriiklymiuk/corgi_examples/blob/main/honoExpoTodo/hono-bun-expo.corgi-compose.yml

This will download and run a sample Todo app with a Hono backend and an Expo frontend.

Under the Hood: How Corgi Works

Unlike Docker Compose, which containerizes everything, Corgi takes a hybrid approach:

  1. Databases run in Docker: Corgi creates Docker container templates for your databases, making them easy to start, stop, and clean up.
  2. Services run natively: Your actual applications (Node.js servers, Go APIs, React frontends, etc.) run directly on your machine, saving CPU and memory.
  3. Environment auto-wiring: Corgi automatically connects everything by generating the right environment variables and .env files.
  4. Parallel execution: Service commands run concurrently, making startup much faster.

This hybrid approach gives you the best of both worlds: the isolation of Docker for databases with the performance of native execution for your applications.

How I Use It (and Why You'll Love It)

Here's a glimpse of how Corgi fits into my workflow:

  • Team Onboarding: New teammate? Send them the corgi-compose.yml. They run corgi run, and they're coding, not debugging setup.
  • Prototyping: Testing a new service? Clone it, tweak the YAML, and run it alongside the rest. Ports and dependencies sort themselves out.
  • Prod Parity: Seed your local DB from a prod dump. Catch issues before they hit staging.
  • Resource Management: Run a complex stack on a laptop without fans spinning up, since only the databases are containerized.
  • Cleanup: Ctrl+C kills everything cleanly, with optional afterStart commands to tidy up.

Let's look at a simple example:

# corgi-compose.yml
db_services:
  postgres_main:
    driver: postgres
    databaseName: app_db
    user: admin
    password: secret
    port: 5432
    seedFromFilePath: ./seed.sql

services:
  backend:
    cloneFrom: https://github.com/myorg/backend-api.git
    path: ./backend
    port: 8080
    depends_on_db:
      - name: postgres_main
    beforeStart:
      - go mod tidy
    start:
      - go run main.go

  frontend:
    cloneFrom: https://github.com/myorg/frontend-app.git
    path: ./frontend
    port: 3000
    depends_on_services:
      - name: backend
    start:
      - npm run dev

With this file, anyone on your team can run:

# First time setup
corgi init

# Run everything
corgi run

And Corgi will:

  1. Clone both repositories (if they don't exist)
  2. Create and start the Postgres database in Docker
  3. Seed the database from your SQL file
  4. Configure environment variables to connect everything
  5. Start both services concurrently (directly on your machine, not in Docker)
  6. Handle clean shutdown when you hit Ctrl+C

No more "it works on my machine" problems!

Real-World Examples

Example 1: Todo App with Bun and Expo

Here's a simple Todo application setup with React Native/Expo frontend and a Bun-powered backend:

services:
  dodoApp:
    cloneFrom: https://github.com/Andriiklymiuk/dodo.git
    path: ./dodo
    depends_on_services:
      - name: dodoServer
        envAlias: EXPO_PUBLIC_TODO_URL
        suffix: /
    environment:
      - EXPO_PUBLIC_TODO_WEBSOCKET_URL=ws://localhost:65533
    beforeStart:
      - yarn install
    start:
      # you can run yarn startAll to open web, android and ios all at once
      # - yarn startAll
      # or you can run yarn web, yarn ios, yarn android separately
      - yarn ios
    afterStart:
      # close ios emulator
      - killall Simulator 2>/dev/null || true
      # close android emulator
      - killall qemu-system-aarch64 2>/dev/null || true
  dodoServer:
    cloneFrom: https://github.com/Andriiklymiuk/dodoServer.git
    path: ./dodoServer
    port: 65533
    beforeStart:
      - bun install
    start:
      - bun dev

Notice how this configuration handles mobile development cleanly, automatically connecting the Expo app to its backend and even providing cleanup commands to close simulators when you're done.

Example 2: Go and Deno with AWS SQS

This example showcases a Go service that listens to SQS messages sent by a Deno service, with a Postgres database:

db_services:
  postgres-db-for-go-example:
    driver: postgres
    databaseName: best_name_for_database
    user: woof
    password: woof_database_password
    port: 5234
  aws-sqs-queue-for-go:
    driver: sqs
    databaseName: sqs_queue_name
    port: 4599

services:
  go_aws_sqs_listener:
    cloneFrom: https://github.com/Andriiklymiuk/go_aws_sqs_listener.git
    path: ./go_aws_sqs_listener
    depends_on_db:
      - name: postgres-db-for-go-example
        envAlias: none
      - name: aws-sqs-queue-for-go
        envAlias: none
    port: 7092
    start:
      - go run .
  deno_aws_sqs_emitter:
    cloneFrom: https://github.com/Andriiklymiuk/deno_aws_sqs_emitter.git
    path: ./deno_aws_sqs_emitter
    depends_on_db:
      - name: aws-sqs-queue-for-go
        envAlias: none
    port: 7098
    start:
      - deno run --allow-net --allow-read --allow-env server.ts

required:
  go:
    why:
      - To launch locally service manually
      - You need to install it yourself brew install go
    checkCmd: go version
  deno:
    why:
      - Needed to launch deno_aws_sqs_emitter
      - You need to install it yourself from https://deno.land/manual/getting_started/installation
    checkCmd: deno --version
  docker:
    why:
      - To launch databases
      - You need to install it yourself from https://docs.docker.com/desktop/install/mac-install/
    checkCmd: docker -v

This example shows how Corgi handles more complex infrastructure like message queues just as easily as databases, connecting the services together automatically.

Example 3: React Native App with Go Backend and Seeded Postgres

Here's an example that includes database seeding from a dump file:

db_services:
  postgres_with_data_for_go_reactnative:
    driver: postgres
    databaseName: bestDbName
    user: awesomeUser
    password: themostsecurepasswordyoucanimaging
    port: 5511
    seedFromFilePath: ./users_dump.sql

services:
  reactnative_app_get_user:
    cloneFrom: https://github.com/Andriiklymiuk/reactnative_app_get_user.git
    path: ./reactnative_app_get_user
    depends_on_services:
      - name: go_server_user_data
    beforeStart:
      - yarn install
      - npx pod-install
    start:
      - yarn start
      - yarn ios
    afterStart:
      - yarn ios:simulator:close
  go_server_user_data:
    cloneFrom: https://github.com/Andriiklymiuk/go_server_user_data.git
    path: ./go_server_user_data
    port: 7012
    depends_on_db:
      - name: postgres_with_data_for_go_reactnative
        envAlias: none
    start:
      - go run .

required:
  go:
    why:
      - To launch locally go service manually
      - You need to install it yourself brew install go
    checkCmd: go version
  yarn:
    why:
      - To build and launch some of the repos locally with yarn
    install:
      - brew install yarn
    checkCmd: yarn -v
  node:
    why:
      - To build and launch some of the repos locally with npm
    install:
      - brew install node
    checkCmd: node -v
  docker:
    why:
      - To launch databases
      - You need to install it yourself from https://docs.docker.com/desktop/install/mac-install/
    checkCmd: docker -v

For this example, the users_dump.sql file contains a schema and sample data:

SET statement_timeout = 0;
SET lock_timeout = 0;
SET idle_in_transaction_session_timeout = 0;
SET client_encoding = 'UTF8';
SET standard_conforming_strings = on;
SELECT pg_catalog.set_config('search_path', '', false);
SET check_function_bodies = false;
SET xmloption = content;
SET client_min_messages = warning;
SET row_security = off;

CREATE EXTENSION IF NOT EXISTS pgcrypto WITH SCHEMA public;

COMMENT ON EXTENSION pgcrypto IS 'cryptographic functions';
SET default_tablespace = '';
SET default_table_access_method = heap;

CREATE TABLE public.schema_migrations (
  version bigint NOT NULL,
  dirty boolean NOT NULL
);

CREATE TABLE public.users (
  id uuid DEFAULT gen_random_uuid() NOT NULL,
  name text NOT NULL
);

COPY public.schema_migrations (version, dirty) FROM stdin;
1 f
\.

COPY public.users (id, name) FROM stdin;
0961f8ea-7a94-4f2f-ba09-f41c802465b4 Some random user
0961f8ea-7a94-4f2f-ba09-f41c802465b5 Another random user
\.

ALTER TABLE ONLY public.schema_migrations
  ADD CONSTRAINT schema_migrations_pkey PRIMARY KEY (version);

ALTER TABLE ONLY public.users
  ADD CONSTRAINT users_pkey PRIMARY KEY (id);

To use this configuration:

  1. Download the corgi-compose.yml file and the users_dump.sql file
  2. Run corgi init to initialize repos
  3. Run corgi run --seed to start everything with database seeding

This will start up the iOS app and Go server with a seeded Postgres database containing sample user data.

Example 4: RabbitMQ with NestJS and Go

This example showcases a message queue setup with NestJS sending messages to a Go service:

db_services:
  rabbitmq-for-go-nestjs:
    user: best_user
    password: most_secure_password
    driver: rabbitmq
    databaseName: rabbitmq-for-go-nestjs-db
    port: 4577

services:
  nestjs_rabbitmq_emitter:
    cloneFrom: https://github.com/Andriiklymiuk/nestjs_rabbitmq_emitter.git
    path: ./nestjs_rabbitmq_emitter
    port: 7856
    depends_on_db:
      - name: rabbitmq-for-go-nestjs
    beforeStart:
      - pnpm install
    start:
      - pnpm start:dev
  go_rabbitmq_listener:
    cloneFrom: https://github.com/Andriiklymiuk/go_rabbitmq_listener.git
    path: ./go_rabbitmq_listener
    port: 7854
    depends_on_db:
      - name: rabbitmq-for-go-nestjs
    beforeStart:
      - go run .

required:
  go:
    why:
      - To launch locally sync-go-trigger service manually
      - You need to install it yourself brew install go
    checkCmd: go version
  pnpm:
    why:
      - To launch products service locally
    install:
      - brew install pnpm
    checkCmd: pnpm -v
  docker:
    why:
      - To launch databases
      - You need to install it yourself from https://docs.docker.com/desktop/install/mac-install/
    checkCmd: docker -v

Example 5: Redis with Bun Server and Expo Client

This example shows a Redis-backed application with a Bun server and Expo client:

db_services:
  redis-for-bun:
    driver: redis
    host: localhost
    user: best_user_for_this_serivce
    password: most_secure_password_ever
    port: 2911

services:
  expo_redis_listener:
    cloneFrom: https://github.com/Andriiklymiuk/expo_redis_listener.git
    depends_on_services:
      - name: bun_redis_server
        envAlias: EXPO_PUBLIC_API_URL
    beforeStart:
      - yarn install
    start:
      - yarn ios
    afterStart:
      - yarn ios:simulator:close
  bun_redis_server:
    cloneFrom: https://github.com/Andriiklymiuk/bun_redis_server.git
    port: 1022
    depends_on_db:
      - name: redis-for-bun
    beforeStart:
      - bun install
    start:
      - bun start

required:
  yarn:
    why:
      - To build and launch some of the repos locally with yarn
    install:
      - brew install yarn
    checkCmd: yarn -v
  bun:
    why:
      - To launch products service locally
    install:
      - curl -fsSL https://bun.sh/install | bash
    checkCmd: bun -v
  docker:
    why:
      - To launch database services
      - You need to install it yourself from https://docs.docker.com/desktop/install/mac-install/
    checkCmd: docker -v
  jq:
    why:
      - To format server output in nice format
    install:
      - brew install jq
    checkCmd: jq --version

Database Support: Not Just Postgres

One of my favorite features is Corgi's extensive database support. While the examples above use several different databases, Corgi supports a huge range:

And over 20 more specialized databases like CockroachDB, SurrealDB, and Timescale. You can find the full list and examples in the Corgi documentation.

Each database type comes with sensible defaults, but you can configure them exactly as needed for your project.

Database Helpers: Seeding and Management

Working with databases locally is one of the biggest pain points in microservices development. Corgi makes this easy with built-in database helpers:

Automated Database Seeding

You can seed your databases in two ways:

Automatically (recommended) 

# Run with the seed flag
corgi run --seed

This will automatically create dumps and seed your databases based on the configuration in your corgi-compose.yml file.

Manually

If you need more control:

  1. Run corgi db
  2. Choose your service
  3. Select dump to create a dump
  4. Select seed to populate the database

Database Commands

Corgi provides a simple CLI for database management:

# Start all databases
corgi db -u

# Stop all databases
corgi db -s

# Remove all databases
corgi db -r

# Combination: stop, remove, and start all databases
corgi db -rsu

Or work with individual databases using the interactive menu:

corgi db

This gives you an interactive menu to choose your service and the operation you want to perform:

Use the arrow keys to navigate: ↓ ↑ → ← 
? Select service: 
  ▸
Read More

Tags:

Previous Article

How to Use AI to Personalize Your eCommerce Shopping Experience

Next Article

Double Your Output - The Secrets of Action Stacking

Related Posts

AI Vision Models Fail to Spot Basic Image Changes, Study Finds

AI Vision Models Fail to Spot Basic Image Changes, Stud...

Mar 15, 2025  0

How to delete data using golang web framework Beego?

How to delete data using golang web framework Beego?

Feb 26, 2025  0

UploadingState component in FilePizza codebase.

UploadingState component in FilePizza codebase.

Apr 4, 2025  0