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.
Prerequisites
- 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
Add Docker rules to your project
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.
1---2description: Docker and container rules3globs: "Dockerfile*, docker-compose*, .dockerignore"4alwaysApply: false5---67- Use multi-stage builds for all application Dockerfiles8- Base images: node:22-alpine for Node.js, python:3.12-slim for Python9- Never run as root in production containers — use USER node or USER app10- Always include health checks for all services11- Use named volumes for database data, not bind mounts12- Environment variables via .env file reference, never hardcoded13- Expose only necessary ports14- Add .dockerignore to exclude node_modules, .git, .env15- Use depends_on with condition: service_healthy for startup orderingExpected result: Docker rules auto-attach when editing any Dockerfile or docker-compose file.
Generate a docker-compose.yml with Composer
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.
1// Prompt to type in Cursor Composer (Cmd+I):2// @package.json @Dockerfile3// Generate a docker-compose.yml for local development with:4// 1. App service: Node.js with hot reload (mount src/ as volume)5// 2. PostgreSQL 16 with named volume for data persistence6// 3. Redis 7 for caching7// 4. pgAdmin for database management8// Requirements:9// - Health checks on all services10// - depends_on with service_healthy conditions11// - Environment variables from .env file12// - Custom network for service discovery13// - Expose only app (3000) and pgAdmin (5050) to hostPro 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.
Generate a multi-stage Dockerfile
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.
1// Prompt to type in Cursor Composer (Cmd+I):2// @package.json @tsconfig.json3// Generate a multi-stage Dockerfile for this Node.js project:4// Stage 1 (builder): install deps, compile TypeScript, build project5// Stage 2 (production): copy built files, install prod deps only6// Requirements:7// - Use node:22-alpine as base8// - Run as non-root user9// - Include HEALTHCHECK instruction10// - Copy only necessary files (not src/, tests/, docs/)11// - Set NODE_ENV=productionExpected result: A multi-stage Dockerfile with separate build and production stages, running as a non-root user.
Add seed data and initialization scripts
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.
1// Prompt to type in Cursor Chat (Cmd+L):2// @docs/schema.sql3// Generate a Docker entrypoint SQL script at docker/init.sql that:4// 1. Creates the database if it doesn't exist5// 2. Runs all schema creation from the referenced schema6// 3. Inserts 10 realistic seed users and 50 seed orders7// 4. Is idempotent (safe to run multiple times)8// This will be mounted in docker-compose.yml at:9// /docker-entrypoint-initdb.d/init.sqlPro 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.
Debug Docker issues with Cursor
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.
1// Prompt to type in Cursor Chat (Cmd+L):2// @docker-compose.yml @Dockerfile3// My docker compose up failed with this error:4// [paste the error output]5// Diagnose the issue and provide the exact fix.6// 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 working example
1version: '3.9'23services:4 app:5 build:6 context: .7 dockerfile: Dockerfile8 target: development9 ports:10 - '3000:3000'11 volumes:12 - ./src:/app/src13 - ./package.json:/app/package.json14 environment:15 - NODE_ENV=development16 - DATABASE_URL=postgresql://postgres:postgres@db:5432/myapp17 - REDIS_URL=redis://cache:637918 depends_on:19 db:20 condition: service_healthy21 cache:22 condition: service_healthy23 networks:24 - app-network25 healthcheck:26 test: ['CMD', 'curl', '-f', 'http://localhost:3000/health']27 interval: 10s28 timeout: 5s29 retries: 33031 db:32 image: postgres:16-alpine33 environment:34 POSTGRES_USER: postgres35 POSTGRES_PASSWORD: postgres36 POSTGRES_DB: myapp37 volumes:38 - postgres-data:/var/lib/postgresql/data39 - ./docker/init.sql:/docker-entrypoint-initdb.d/init.sql40 ports:41 - '5432:5432'42 networks:43 - app-network44 healthcheck:45 test: ['CMD-SHELL', 'pg_isready -U postgres']46 interval: 5s47 timeout: 3s48 retries: 54950 cache:51 image: redis:7-alpine52 command: redis-server --maxmemory 128mb --maxmemory-policy allkeys-lru53 networks:54 - app-network55 healthcheck:56 test: ['CMD', 'redis-cli', 'ping']57 interval: 5s58 timeout: 3s59 retries: 56061 pgadmin:62 image: dpage/pgadmin4:latest63 environment:64 PGADMIN_DEFAULT_EMAIL: admin@local.dev65 PGADMIN_DEFAULT_PASSWORD: admin66 ports:67 - '5050:80'68 depends_on:69 db:70 condition: service_healthy71 networks:72 - app-network7374volumes:75 postgres-data:7677networks:78 app-network:79 driver: bridgeCommon mistakes when generating Local Dev Setup with Cursor
Why it's a problem: Not referencing package.json when generating Docker configs
How to avoid: Always include @package.json in Docker generation prompts so Cursor uses your exact scripts and runtime version.
Why it's a problem: Using bind mounts for database data
How to avoid: Use named volumes (postgres-data:) for database persistence. Add this as a rule in your Docker .mdc file.
Why it's a problem: Missing health checks in docker-compose.yml
How to avoid: Add healthcheck to every service and use depends_on with condition: service_healthy.
Why it's a problem: Hardcoding credentials in docker-compose.yml
How to avoid: 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
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
Generate a docker-compose.yml for a Node.js application with PostgreSQL, Redis, and pgAdmin. Include health checks, named volumes, depends_on with service_healthy conditions, and a custom bridge network. Use environment variables from a .env file.
@package.json @Dockerfile Generate a complete docker-compose.yml for local development. Include: app service with hot reload, PostgreSQL 16 with health check and named volume, Redis 7 with memory limit, pgAdmin. Use depends_on with service_healthy. All config from environment variables, not hardcoded.
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.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation