Skip to content

README.md

Latest commit

 

History

History
208 lines (158 loc) · 7.91 KB

README.md

File metadata and controls

208 lines (158 loc) · 7.91 KB

Node Hybrid JWT + Session Auth API

Coverage badge

This is a backend API that uses a hybrid authentication approach combining Express server-side sessions and JWT-based access control, with all credentials stored in HTTP-only cookies. This approach ensures security while allowing stateless validation for route access.

OpenAPI Specification

Setup

Follow these steps to get the project up and running with Prisma and ensure the prisma/generated folder is created properly.

  1. Environment Configuration To run the application locally, create a .env file in the root directory with the following variables:

    # PostgreSQL connection string
DATABASE_URL=postgresql://admin_pg:password@localhost:5433/local-express-hybrid-auth-api-db

# Google OAuth configuration
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_CALLBACK_URL=http://localhost:3000/auth/google/callback

# GitHub OAuth configuration
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
GITHUB_CALLBACK_URL=http://localhost:3000/auth/github/callback

  2. Install Dependencies: Install all required dependencies for the project.

    npm install

  3. Generate Prisma Client and Artifacts: Prisma generates the database client and optionally other files (like types or codegen outputs) into the prisma/generated folder. To generate everything:

    npx prisma generate

    This command reads your schema.prisma file and creates the necessary output in node_modules/.prisma and (if configured) in prisma/generated. Re-run this command any time you modify your Prisma schema.

  4. Apply Database Migrations: If you're using Prisma Migrate and have migrations defined, run:

    npx prisma migrate dev

    This will:

    • Apply all pending migrations to your local database
    • Generate the Prisma Client
    • Optionally run seed scripts if configured

  5. Open Prisma Studio (Optional): Prisma Studio is a visual interface to explore and manipulate your database during development.

    npx prisma studio

    This opens a browser window where you can browse tables, add records, and debug data visually.

Notes:

  • If your project is configured to use the prisma/generated folder (e.g., for custom types or GraphQL artifacts), it will be populated by npx prisma generate. This folder is typically auto-generated and should either be:

    • Ignored in version control (.gitignore), or
    • Re-generated by every contributor using the steps above. Do not manually edit files in prisma/generated unless explicitly intended.

  • You can generate a strong SESSION_SECRET using the following command in your terminal (Unix/macOS/Linux):openssl rand -base64 64. On windows you can use git bash. Then add it to your .env file for production use:

    SESSION_SECRET=your_generated_value_here

Email Development with MinIO/CDN

This project uses MinIO as a local S3-compatible object storage service for serving static assets (logos, images) used in email templates during development. This setup provides a seamless development experience while maintaining production-ready patterns.

What is MinIO?

MinIO is a high-performance, S3-compatible object storage server that provides:

  • S3-compatible API: Works with existing S3 tools and libraries
  • Local Development: Runs in Docker containers for isolated development
  • Public Asset Serving: Serves static files via HTTP URLs
  • Headless Operation: Runs without a web interface for automated workflows

How It Works

Development Mode

When running npm run email:dev, the system:

  1. Starts MinIO Container: Launches a local MinIO server on port 9000
  2. Creates Public Bucket: Sets up a public-assets bucket with public read access
  3. Uploads Assets: Copies static assets from .devcontainer/cdn-assets/ to MinIO
  4. Serves Assets: Assets become available at http://localhost:9000/public-assets/
  5. Runs React Email: Starts the email preview server with access to CDN assets

Asset Structure

.devcontainer/cdn-assets/
├── static/
│   ├── logo.png          # Company logo
│   ├── header.png        # Email header image
│   ├── footer.png        # Email footer image
│   └── logo-placeholder.png
├── email-header.jpg      # Legacy header image
├── email-footer.png      # Legacy footer image
└── company-icon.svg      # Company icon

Environment Configuration

The CDN_URL environment variable controls asset URLs:

# Development (MinIO)
CDN_URL=http://localhost:9000/public-assets

# Production (CDN)
CDN_URL=https://cdn.yourdomain.com/assets

Production Deployment

Replacing MinIO with a CDN

In production, MinIO is replaced with a Content Delivery Network (CDN) for better performance and global distribution:

Option 1: Cloud Storage + CDN
# AWS S3 + CloudFront
CDN_URL=https://d1234567890.cloudfront.net/assets

# Google Cloud Storage + CDN
CDN_URL=https://storage.googleapis.com/your-bucket/assets

# Azure Blob Storage + CDN
CDN_URL=https://your-cdn.azureedge.net/assets
Option 2: Dedicated CDN Services
# Cloudflare
CDN_URL=https://assets.yourdomain.com

# KeyCDN
CDN_URL=https://your-zone.kxcdn.com/assets

# BunnyCDN
CDN_URL=https://your-zone.b-cdn.net/assets

Migration Steps

  1. Upload Assets: Copy all files from .devcontainer/cdn-assets/ to your CDN
  2. Update Environment: Change CDN_URL in production environment files
  3. Test URLs: Verify all asset URLs are accessible
  4. Update Email Templates: Ensure all Img components use ${assetsUrl}

Benefits of CDN in Production

  • Global Distribution: Faster loading times worldwide
  • Caching: Reduced server load and bandwidth costs
  • HTTPS: Secure asset delivery
  • Scalability: Handles high traffic volumes
  • Reliability: Multiple edge locations for redundancy

Email Development Workflow

Starting Email Development

# Start MinIO + React Email preview
npm run email:dev

# Access email preview
open http://localhost:3000

Adding New Assets

  1. Add files to .devcontainer/cdn-assets/static/
  2. Restart npm run email:dev to upload new assets
  3. Reference in email templates: ${assetsUrl}/static/filename.png

Stopping Services

# Stop MinIO containers
npm run email:stop

Troubleshooting

MinIO Not Starting

  • Check if port 9000 is available
  • Verify Docker is running
  • Check container logs: docker logs email-minio

Assets Not Loading

  • Verify MinIO is running: curl http://localhost:9000/minio/health/live
  • Check bucket exists: curl http://localhost:9000/public-assets/
  • Verify asset upload: curl http://localhost:9000/public-assets/static/logo.png

Translation Errors

  • Ensure translation files exist in src/locales/en/translation.json
  • Check email template imports are correct
  • Verify getEmailTranslator() function is working

Resources