Dokcer & Dockerization
1. Local Development (The Foundation)
Before touching CI/CD or production, Docker must become the absolute source of truth for local development. Developers should not need to install MongoDB or Redis directly on their laptops.
The compose.yaml Standard: Every repository (like the Asaas Foundation starter kit) must include a compose.yaml file. A new engineer should be able to clone the repo, run docker compose up -d, and instantly have the entire stack (Node backend, Next.js frontend, and a localized MongoDB instance) running and connected.
Volume Mapping: For local development, map the local source code into the container (volumes: - ./:/app). This allows developers to use their local IDEs and take advantage of Vite and Next.js Hot Module Replacement (HMR) without needing to rebuild the container on every file save.
Database Seeding: Include automated seed scripts within the local Docker setup so the Payload CMS database boots up with identical dummy data for every developer.
2. Image Architecture & Construction
The way you build Docker images dictates your deployment speed and server costs. Enforce multi-stage builds to keep final image sizes as small as possible.
Node.js & Next.js Dockerfile Guardrails
Multi-Stage Builds: Require a minimum of three stages in your Dockerfile:
Dependencies: Install all packages (npm ci).
Builder: Copy source code and compile TypeScript/Next.js.
Runner: Copy only the compiled production assets and the production node_modules into a lightweight base image.
Next.js Standalone Output: Next.js can generate a massive node_modules folder. Enforce the use of output: 'standalone' in next.config.js. This creates a highly optimized build directory containing only the exact files needed for production, reducing your Docker image size from ~1.5GB to ~150MB.
Base Images: Standardize on lightweight base images. Use node:20-alpine (or current LTS) across the board.
3. Security & Governance Policies
Do not let containerization become a security vulnerability. Enforce these strict rules:
Never Run as Root: By default, Docker runs everything as the root user. Your Dockerfiles must explicitly create a non-root user (e.g., USER node) before executing the application.
Immutable Tags: Never use the :latest tag in staging or production deployments. Tag images with the specific Git commit SHA (e.g., siraj-academy-frontend:a1b2c3d). This guarantees you know exactly which version of the code is running and allows for instant rollbacks.
Secret Management: Never bake .env files or API keys into the Docker image itself. The image must be environment-agnostic. Inject secrets at runtime via your deployment orchestrator.
4. Deployment & Orchestration
Once the images are built in your CI pipeline (via GitHub Actions), they need a place to run.
Self-Hosted Orchestration: Since you are utilizing lightweight, self-hosted orchestrators like Dokploy, the workflow becomes highly streamlined. GitHub Actions builds the image and pushes it to a private container registry (like GitHub Packages or Docker Hub).
Automated Updates: Configure Dokploy to listen for a webhook from your registry. When a new image tagged for production is pushed, Dokploy automatically pulls the new image, gracefully spins down the old container, and starts the new one.
Networking & SSL: Let the orchestrator handle the networking. Your Node.js and Next.js containers should simply expose a port (e.g., 3000) internally. Dokploy's built-in reverse proxy (Traefik) will map your domains, handle the routing, and automatically provision Let's Encrypt SSL certificates.