Skip to content

README.md

Latest commit

 

History

History
211 lines (136 loc) · 5.93 KB

README.md

File metadata and controls

211 lines (136 loc) · 5.93 KB

My Fastify Template for Future Projects

Status

CI

Requirements

To execute this example, install Node.js and Docker. The local workflow below starts MongoDB and Mailpit for you in Docker.

You can use the following versions:

  • Node.js 26+
  • Latest Docker engine

The backend now uses the built-in Temporal API available in Node.js 26. Keep Temporal usage inside business-logic helpers and convert back to native Date values at MongoDB or other library boundaries.

Getting Started

Running the Project Using Docker

There are two Docker compose paths.

Local Docker stack (Mailpit included, no real SMTP needed)

make dev-compose

This builds the image and starts Mongo, the app in development mode, and Mailpit for SMTP capture. Open http://localhost:8025 to inspect captured mail. No SMTP credentials are required.

Production Docker stack (real SMTP required)

Ensure SMTP_HOST, SMTP_PORT, SMTP_SECURE, SMTP_USER, and SMTP_PASS are set in .env, then:

docker compose -f docker-compose.yml up

or the makefile alias:

make up

The app boots in production mode and fails fast at startup if SMTP is not configured. That behavior is intentional.

Running the Project Locally

  1. Install Dependencies:

    npm install

  2. Create the local env file:

make init-env

make init-env creates .env with local-safe defaults and generates secrets when openssl is available. If .env already exists, the target leaves it unchanged.

  1. Adjust .env if needed:

    Leave SMTP_HOST, SMTP_PORT, SMTP_SECURE, SMTP_USER, and SMTP_PASS unset to use local Mailpit by default. Review or rotate the generated secrets before reusing the environment elsewhere.

  2. Start the local stack:

     make dev

    This starts MongoDB on localhost:27017, Mailpit SMTP on localhost:1025, and the Mailpit inbox UI on http://localhost:8025.

  3. Inspect captured email in Mailpit:

    Open http://localhost:8025 and trigger flows such as password reset. Development defaults to Mailpit unless you set real SMTP credentials in .env.

  4. Run Tests:

    make test

make test starts the managed local test runtime, including Docker-backed test dependencies, managed runtime state, and cleanup.

Use the raw CI-oriented runner only when the test dependencies are already available outside the managed wrapper:

make test-ci

make test-ci and npm run test:ci are intentionally plain, CI-style entrypoints. They do not boot MongoDB or other test dependencies for you.

  1. Stop the local containers when finished:

    make dev-stop

Switching to Real SMTP

For short manual delivery checks, add the SMTP settings below to .env and rerun make dev:

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-smtp-user
SMTP_PASS=your-smtp-password

Outside development and test, the app now fails fast during boot if SMTP is not configured.

Makefile Commands

  • Show the canonical local command surface:

     make

  • Create .env once for local development:

     make init-env

  • Start the local Docker app stack with Mailpit:

     make dev-compose

  • Start local MongoDB + Mailpit + app:**

     make dev

  • Stop local MongoDB + Mailpit:

     make dev-stop

  • Inspect managed runtime state:

     make runtime-status

  • Clean managed runtime state and owned processes:

     make runtime-cleanup

  • Run database migrations with .env loaded:

     make migrate

  • Run tests:

     make test

  • Run the raw CI-style Node suite when test dependencies are already running:

     make test-ci

  • Run lint:

     make lint

  • Emit machine-readable managed runtime status:

     make runtime-status-json

Runtime Status And Cleanup

  • make runtime-status and npm run runtime:status show human-readable managed runtime status and keep exit code 0 for inspection.
  • make runtime-status-json and npm run runtime:status -- --json emit machine-readable JSON without ANSI styling.
  • make runtime-cleanup and npm run runtime:cleanup clean backend-owned runtime state and owned stale processes.
  • Cleanup first attempts a graceful stop, waits for the process to exit, and then escalates to forced termination if the process remains alive.
  • If cleanup still cannot remove all runtime state, the cleanup command exits with code 1 and prints a manual-recovery message instead of pretending the machine is clean.

Stale Runtime State

  • Managed runtimes record ownership in the system temp directory instead of inside the repository.
  • Automatic stale-state recovery only happens after the recorded runtime has been inactive for the stale-state TTL, which defaults to 15 minutes.
  • If a recorded runtime is too recent for automatic recovery, startup fails fast and asks you to wait for the TTL window or run explicit cleanup.
  • Explicit cleanup bypasses the stale-state TTL so operators can recover immediately.

Output And Color Behavior

  • Human-oriented Node-managed surfaces such as make dev, make test, make runtime-status, and the managed local Node test reporter use semantic color when the output stream is interactive.
  • Set NO_COLOR to disable ANSI styling. Set FORCE_COLOR=1 to force ANSI styling on Node-managed human output even for non-TTY streams.
  • JSON status output remains plain text JSON.
  • make help is plain text by design so the make entrypoint stays thin and predictable.
  • Focused wrapper tests intentionally use quiet output sinks so they can validate lifecycle semantics without leaking fake operator banners into the suite output.