Docker Compose Multi-Container Local Dev Cursor Rules Template

Overview

Direct answer: This Cursor rules template provides a complete, copyable .cursorrules configuration tailored for a docker-compose multi-container local development stack with an API service, a frontend service, and a PostgreSQL database. It ensures consistent Cursor AI driven edits and safe automation in a local dev environment.

Stack coverage: Docker Compose v2, a Node.js API, a React frontend, and PostgreSQL. The rules enforce folder structure, environment handling, and security boundaries for local development with Cursor AI.

When to Use These Cursor Rules

• Setting up or onboarding a docker-compose multi-container local dev environment for API, frontend, and database.
• When you want Cursor AI to generate or modify code in services with consistent styling and practices.
• To enforce security constraints (no hard-coded secrets, proper env handling) during local development.
• When you need repeatable project structure and quick provisioning across machines.

Copyable .cursorrules Configuration

# .cursorrules
framework: docker-compose
stack: docker-compose-multi-container-local-dev

# Framework Role & Context
role_context: Cursor AI acts as DevOps advisor for a docker-compose based local stack with api web and db

# Code Style and Style Guides
code_style: ESLint Prettier for JS; avoid inline code; explicit versions

# Architecture & Directory Rules
architecture: root docker-compose.yml; services/api; services/web; services/db; .env

# Authentication & Security Rules
security: do not hardcode credentials; use env vars; run as non root

# Database and ORM patterns
database: PostgreSQL; migrations via sql scripts; use data volumes

# Testing & Linting Workflows
testing: npm test; eslint; prettier; git hooks; ci

# Prohibited Actions and Anti-patterns
anti: do not mount host node_modules; do not expose all ports; do not run as root; avoid host network

Recommended Project Structure

project-root/
├── docker-compose.yml
├── .env
├── services/
│   ├── api/
│   │   ├── Dockerfile
│   │   └── app/
│   ├── web/
│   │   ├── Dockerfile
│   │   └── src/
│   └── db/
│       ├── Dockerfile
│       └── init.sql

Core Engineering Principles

• Repeatable, reproducible local development environments across machines.
• Clear separation of concerns between API, frontend, and database.
• Security-by-default: avoid secrets in code, minimize exposed surfaces.
• Deterministic builds and deterministic runtime behavior.
• Observability: health checks, logs, and consistent metrics.
• CI/CD compatibility and easy rollback in local dev.

Code Construction Rules

• Use explicit, pinned versions in Dockerfiles and package.json. Do not rely on latest tags.
• Run containers as non-root users where feasible.
• Keep COPY statements minimal and leverage multi-stage builds for smaller images.
• Mount only necessary volumes; avoid mounting node_modules in production-like containers.
• Keep environment-specific config in environment variables or secret management, not in code.

Security and Production Rules

• Do not expose DB ports publicly; bind to localhost or use a private network.
• Use TLS where possible for web endpoints; rotate credentials regularly.
• Enable container healthchecks and restrict capabilities; run as non-root.
• Use read-only filesystems for static assets and cache when possible.
• Limit network access between services; avoid broad network ACLs in development.

Testing Checklist

• Unit tests for api and web services; linting passes before commit.
• Integration tests for service interactions (api-web, api-db).
• Docker Compose config validation (docker-compose config) and local end-to-end tests.
• CI checks for build/test/lint, plus a local dev sanity check run.

Common Mistakes to Avoid

• Pinning to latest tags or relying on system-wide dependencies.
• Hardcoding secrets or using plain text credentials in repo.
• Overexposed ports or running containers with host network mode.
• Not validating docker-compose configuration changes before merging.

FAQ

What is this Cursor Rules Template for docker-compose multi-container local dev?

This template provides a copyable .cursorrules block and a recommended project structure to support a docker-compose based local development stack with an API, web frontend, and PostgreSQL. It guides Cursor AI to configure, lint, test, and secure the environment, while preventing common pitfalls in multi-container development.

Which stack does this template cover?

It covers a docker-compose multi-container local development stack with API (Node.js), frontend (React), and PostgreSQL. The template enforces directory layout, environment handling, and container security appropriate for local development and Cursor AI-assisted changes.

How do I use the copyable .cursorrules block?

Copy the code block from the Copyable section into a file named .cursorrules at the repo root. Cursor AI will reference this file to guide code generation, enforce stack structure, and prevent common DevOps mistakes in local development.

Can I adapt this template to other stacks?

Yes. You can adapt the stack by renaming services, adjusting Dockerfiles, and updating environment rules. Maintain the same Cursor AI rule structure to preserve guidance when applying Cursor AI edits to other docker-compose based stacks.

Where are the project structure and directory rules?

The template outlines a root docker-compose.yml and a services directory with api, web, and db subfolders. This consistent layout enables Cursor AI to provide accurate guidance and helps ensure reproducible local development.