# How to Generate Local Dev Setup with Cursor

- Tool: Cursor
- Difficulty: Beginner
- Time required: 10-15 min
- Compatibility: Cursor Pro+, Docker, any language
- Last updated: March 2026

## TL;DR

Generate Docker Compose configurations with Cursor by referencing your project's package.json and Dockerfile with @file context, creating DevOps-specific .cursorrules, and prompting Composer to create multi-service setups with databases, caches, and application containers. Cursor excels at generating Docker configurations when given your exact tech stack.

## Why Cursor Is Ideal for Docker Configuration

Docker Compose files are declarative YAML that follows predictable patterns, making them well-suited for AI generation. Cursor can generate complete multi-service setups including application containers, databases, caches, and message queues when given your project context. This tutorial shows you how to provide the right context and rules so Cursor generates production-quality Docker configurations with proper networking, volumes, health checks, and environment variable handling.

## Before you start

- Cursor installed (Pro recommended)
- Docker and Docker Compose installed locally
- A project with at least a package.json or equivalent build config
- Basic understanding of Docker containers

## Step-by-step guide

### 1. Add Docker rules to your project

Create a .cursor/rules/docker.mdc file that specifies your Docker conventions, base images, and security requirements. These rules ensure Cursor generates production-quality Dockerfiles and Compose configurations following your team's standards.

```
---
description: Docker and container rules
globs: "Dockerfile*, docker-compose*, .dockerignore"
alwaysApply: false
---

- Use multi-stage builds for all application Dockerfiles
- Base images: node:22-alpine for Node.js, python:3.12-slim for Python
- Never run as root in production containers — use USER node or USER app
- Always include health checks for all services
- Use named volumes for database data, not bind mounts
- Environment variables via .env file reference, never hardcoded
- Expose only necessary ports
- Add .dockerignore to exclude node_modules, .git, .env
- Use depends_on with condition: service_healthy for startup ordering
```

**Expected result:** Docker rules auto-attach when editing any Dockerfile or docker-compose file.

### 2. Generate a docker-compose.yml with Composer

Open Composer with Cmd+I and reference your project configuration files. Describe the services you need and Cursor will generate a complete docker-compose.yml with proper networking, volumes, and dependencies. Always reference package.json so Cursor knows your application's runtime and build commands.

```
// Prompt to type in Cursor Composer (Cmd+I):
// @package.json @Dockerfile
// Generate a docker-compose.yml for local development with:
// 1. App service: Node.js with hot reload (mount src/ as volume)
// 2. PostgreSQL 16 with named volume for data persistence
// 3. Redis 7 for caching
// 4. pgAdmin for database management
// Requirements:
// - Health checks on all services
// - depends_on with service_healthy conditions
// - Environment variables from .env file
// - Custom network for service discovery
// - Expose only app (3000) and pgAdmin (5050) to host
```

> Pro tip: Add 'Include a Makefile with common commands: make up, make down, make logs, make reset-db' to your prompt and Cursor will generate both files in one session.

**Expected result:** A complete docker-compose.yml with all requested services, health checks, and proper networking.

### 3. Generate a multi-stage Dockerfile

If you do not have a Dockerfile yet, ask Cursor to generate one alongside the Compose file. Reference your package.json to ensure the build commands and runtime match your project. A multi-stage build keeps the production image small by separating build and runtime stages.

```
// Prompt to type in Cursor Composer (Cmd+I):
// @package.json @tsconfig.json
// Generate a multi-stage Dockerfile for this Node.js project:
// Stage 1 (builder): install deps, compile TypeScript, build project
// Stage 2 (production): copy built files, install prod deps only
// Requirements:
// - Use node:22-alpine as base
// - Run as non-root user
// - Include HEALTHCHECK instruction
// - Copy only necessary files (not src/, tests/, docs/)
// - Set NODE_ENV=production
```

**Expected result:** A multi-stage Dockerfile with separate build and production stages, running as a non-root user.

### 4. Add seed data and initialization scripts

Use Chat (Cmd+L) to generate database initialization scripts that run automatically when the PostgreSQL container starts. Reference your schema or migration files so Cursor generates accurate seed SQL matching your table structure.

```
// Prompt to type in Cursor Chat (Cmd+L):
// @docs/schema.sql
// Generate a Docker entrypoint SQL script at docker/init.sql that:
// 1. Creates the database if it doesn't exist
// 2. Runs all schema creation from the referenced schema
// 3. Inserts 10 realistic seed users and 50 seed orders
// 4. Is idempotent (safe to run multiple times)
// This will be mounted in docker-compose.yml at:
// /docker-entrypoint-initdb.d/init.sql
```

> Pro tip: Mount the init script in docker-compose.yml under volumes: ./docker/init.sql:/docker-entrypoint-initdb.d/init.sql. PostgreSQL runs these scripts automatically on first container creation.

**Expected result:** An idempotent SQL initialization script with seed data matching your schema.

### 5. Debug Docker issues with Cursor

When your Docker setup has issues, paste the error output from docker compose up into Cursor Chat. Reference the docker-compose.yml and Dockerfile so Cursor can diagnose the problem with full context. Common issues include port conflicts, volume permission errors, and health check failures.

```
// Prompt to type in Cursor Chat (Cmd+L):
// @docker-compose.yml @Dockerfile
// My docker compose up failed with this error:
// [paste the error output]
// Diagnose the issue and provide the exact fix.
// Show the corrected YAML or Dockerfile section.
```

> Pro tip: Use @web context if Cursor's training data does not cover the specific Docker error: '@web [error message] docker compose fix'.

**Expected result:** Cursor identifies the Docker configuration issue and provides the corrected YAML.

## Complete code example

File: `docker-compose.yml`

```yaml
version: '3.9'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: development
    ports:
      - '3000:3000'
    volumes:
      - ./src:/app/src
      - ./package.json:/app/package.json
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/myapp
      - REDIS_URL=redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    networks:
      - app-network
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:3000/health']
      interval: 10s
      timeout: 5s
      retries: 3

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: myapp
    volumes:
      - postgres-data:/var/lib/postgresql/data
      - ./docker/init.sql:/docker-entrypoint-initdb.d/init.sql
    ports:
      - '5432:5432'
    networks:
      - app-network
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 5s
      timeout: 3s
      retries: 5

  cache:
    image: redis:7-alpine
    command: redis-server --maxmemory 128mb --maxmemory-policy allkeys-lru
    networks:
      - app-network
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 5s
      timeout: 3s
      retries: 5

  pgadmin:
    image: dpage/pgadmin4:latest
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@local.dev
      PGADMIN_DEFAULT_PASSWORD: admin
    ports:
      - '5050:80'
    depends_on:
      db:
        condition: service_healthy
    networks:
      - app-network

volumes:
  postgres-data:

networks:
  app-network:
    driver: bridge
```

## Common mistakes

- **Not referencing package.json when generating Docker configs** — Without package.json context, Cursor guesses at the package manager (npm vs pnpm vs yarn), build commands, and Node.js version, often generating incorrect configurations. Fix: Always include @package.json in Docker generation prompts so Cursor uses your exact scripts and runtime version.
- **Using bind mounts for database data** — Bind mounts for database data directories cause permission issues on macOS and Linux and can corrupt data during container restarts. Fix: Use named volumes (postgres-data:) for database persistence. Add this as a rule in your Docker .mdc file.
- **Missing health checks in docker-compose.yml** — Without health checks, depends_on only waits for container start, not service readiness. This causes race conditions where the app starts before the database is ready. Fix: Add healthcheck to every service and use depends_on with condition: service_healthy.
- **Hardcoding credentials in docker-compose.yml** — Hardcoded credentials get committed to Git and exposed in public repositories. Fix: Use env_file: .env in docker-compose.yml and add .env to .gitignore. Create a .env.example with placeholder values.

## Best practices

- Reference package.json and existing Dockerfiles when generating compose configurations
- Use multi-stage Dockerfile builds to keep production images small
- Add health checks to all services and use depends_on with service_healthy conditions
- Use named volumes for database data persistence instead of bind mounts
- Create a .cursor/rules/docker.mdc with auto-attaching globs for Docker files
- Include a Makefile or scripts/ directory with common Docker commands for your team
- Generate a .dockerignore file alongside your Dockerfile to exclude unnecessary files

## Frequently asked questions

### Can Cursor run Docker commands directly?

Yes, in Agent mode (Cmd+I), Cursor can execute terminal commands including docker compose up, docker build, and docker logs. Enable YOLO mode for common Docker commands or approve each execution individually.

### How do I generate a Docker setup for a microservices project?

Reference each service's package.json or build config with @file and describe all services in one Composer prompt. Cursor will generate a docker-compose.yml with proper networking between services, shared networks, and inter-service environment variables.

### Why does Cursor generate docker-compose version 2 syntax?

Cursor's training data includes both version 2 and 3 syntax. Specify the version in your prompt or .cursorrules: 'Use docker-compose version 3.9 syntax.' Modern Docker Compose no longer requires the version key at all.

### Can Cursor generate Kubernetes manifests from my Docker Compose file?

Yes. Reference @docker-compose.yml and prompt: 'Convert this Docker Compose setup to Kubernetes manifests with Deployments, Services, and ConfigMaps.' Cursor understands the mapping between Compose and K8s resources.

### How do I add hot reload to a Docker development container?

Mount your source directory as a volume (./src:/app/src) and ensure your application uses a file watcher (nodemon, ts-node-dev). Include this in your Composer prompt and Cursor will configure both the volume mount and the dev command.

---

Source: https://www.rapidevelopers.com/cursor-tutorial/how-to-direct-cursor-ai-to-create-docker-compose-files-for-multi-service-local-development
© RapidDev — https://www.rapidevelopers.com/cursor-tutorial/how-to-direct-cursor-ai-to-create-docker-compose-files-for-multi-service-local-development