The DaemonEye project maintains comprehensive Docker container development guidelines, organized for clarity and maintainability in the .cursor/rules/docker/ directory. These guidelines cover optimization, security, secret management, compliance, and troubleshooting, with each topic documented in dedicated markdown files and supported by automated rule application via frontmatter metadata source.

Optimization

Image size reduction is achieved by using multi-stage builds, minimal base images (such as alpine, slim, or distroless), and cleaning up temporary files within the same layer. The .dockerignore file should exclude unnecessary files and directories (e.g., .git, node_modules, build artifacts, logs, test directories) to minimize build context size. Layer caching is optimized by copying dependency files first and source code last, maximizing cache hits and reducing rebuild times. Parallelizing independent build stages and using build cache mounts further improve build performance. Runtime optimization involves setting resource limits in docker-compose, tuning memory usage with environment variables, implementing lightweight health checks, and configuring monitoring and logging for performance tracking. Performance targets include base images under 50MB, application images under 200MB, build times under 5 minutes, and startup times under 10 seconds source.

Security Hardening

Security principles are based on immutability (never modify running containers in production; use semantic versioning for image tags), least privilege (run as non-root user, drop unnecessary capabilities, use read-only filesystems), and defense in depth (multiple security controls, image signing, regular scanning, network isolation). Security hardening measures include creating dedicated non-root users in Dockerfiles, setting proper permissions, dropping unnecessary capabilities, and using runtime flags such as --cap-drop=ALL and --security-opt=no-new-privileges. Minimal base images reduce attack surface, and images must be regularly scanned for vulnerabilities using tools like Trivy, Clair, or Snyk. Images should be signed with Cosign or Docker Content Trust and verified before deployment. Health checks must be implemented to monitor container health and enable automatic recovery source.

Secret Management

Secrets must never be included in image layers. Instead, provide secrets at runtime via environment variables or mounted files. The guidelines strictly prohibit including secrets, API keys, passwords, private keys, database credentials, or environment-specific configurations in images source.

Compliance

Compliance requirements include signing images with Cosign, verifying signatures, maintaining image build logs, documenting security scanning results, tracking vulnerabilities, and enforcing security policies. Security scanning is integrated into CI/CD pipelines using tools like Hadolint for Dockerfile linting and Trivy for vulnerability scanning. Vulnerability management involves regular scanning, automated security updates, and a security patch deployment strategy source.

Troubleshooting

Common scenarios include large image size, slow builds, build failures, containers not starting, permission issues, network connectivity problems, high memory or CPU usage, and slow startup. Troubleshooting techniques involve using docker history to analyze image layers, docker logs and docker exec for runtime debugging, docker inspect for configuration review, Trivy for vulnerability scanning, and network debugging commands (docker network ls, docker network inspect, ping). Monitoring and observability best practices include comprehensive health checks, structured logging, and metrics collection with Prometheus labels. Prevention strategies emphasize proactive monitoring, regular dependency updates, and maintaining troubleshooting runbooks source.

Maintainability

The rules directory is intentionally structured by topic (e.g., optimization, security, troubleshooting) to improve maintainability and discoverability. Each rule file uses frontmatter metadata to control its application scope, supporting automated and context-aware guidance. The directory README documents the structure, rule metadata, and instructions for adding new rules, ensuring clarity and ease of future updates source.

Example: Multi-Stage Build and Layer Optimization

# Stage 1: Dependencies
FROM node:18-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production && npm cache clean --force

# Stage 2: Build
FROM node:18-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 3: Production
FROM node:18-alpine AS production
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY --from=build /app/package*.json ./
USER node
EXPOSE 3000
CMD ["node", "dist/main.js"]

Example: .dockerignore for Build Context Reduction

.git*
node_modules
dist
build
*.log
coverage
docs/
test/
__tests__/
.vscode
.idea
*.swp
*.swo
.DS_Store
Thumbs.db

Refer to the .cursor/rules/docker/ directory and its README for the latest standards, checklists, and code examples supporting Docker container development in DaemonEye.