Productier/DEPLOYMENT.md

Productier Deployment Guide

Quick Start

Local/Self-Hosted (Recommended)

From the project root:

# 1. Copy and configure environment
cp .env.example .env

# 2. Start all services
docker compose up -d

# 3. Access the application
# Frontend: http://localhost:5173
# API: http://localhost:48080
# Auth: http://localhost:43001

The root .env file contains all configuration for local development and self-hosting.

Remote Deployment (Backend Only)

For deploying the backend API separately:

cd apps/backend

# 1. Copy and configure environment
cp remote.env .env
# Edit .env with your production values

# 2. Start the API service
docker compose -f docker-compose.remote.yml up -d

Remote Deployment (Frontend Only)

For deploying the frontend separately:

cd apps/frontend

# 1. Build with environment variables
source ../apps/frontend/remote.env
docker build \
  --build-arg VITE_FRONTEND_URL=$VITE_FRONTEND_URL \
  --build-arg VITE_AUTH_URL=$VITE_AUTH_URL \
  --build-arg VITE_API_URL=$VITE_API_URL \
  --build-arg VITE_DEV_MAILBOX_ENABLED=false \
  -t productier-frontend \
  -f Dockerfile \
  ..

# 2. Run the container
docker run -d -p 80:80 productier-frontend

Or use npm for development:

cd apps/frontend
npm run dev

Environment Files

File	Purpose	Location
.env	Local/self-hosted deployment	Project root
apps/backend/remote.env	Remote backend deployment	apps/backend/
apps/frontend/remote.env	Remote frontend build	apps/frontend/

Required Configuration

Backend (API)

Variable	Description	Required
DATABASE_URL	PostgreSQL connection string	Yes
AUTH_SERVICE_URL	URL of auth service	Yes
BETTER_AUTH_SECRET	Secret for auth tokens (32+ chars)	Yes
MAIL_ENCRYPTION_KEY	Secret for mail encryption (32+ chars)	Yes
CORS_ALLOW_ORIGINS	Comma-separated allowed origins	Yes

Auth Service

Variable	Description	Required
DATABASE_URL	PostgreSQL connection string	Yes
BETTER_AUTH_SECRET	Secret for auth tokens	Yes
FRONTEND_URL	Frontend URL for redirects	Yes
AUTH_MAGIC_LINK_PROVIDER	dev-mailbox or smtp	Yes
AUTH_SMTP_*	SMTP settings (if using SMTP)	Conditional

Frontend

Variable	Description	Required
VITE_FRONTEND_URL	Public frontend URL	Yes
VITE_AUTH_URL	Public auth service URL	Yes
VITE_API_URL	Public API URL	Yes

Production Deployment

For full production deployment with TLS, use the infra compose:

cd infra

# 1. Copy and configure production environment
cp ../.env.production.example .env.production
# Edit .env.production with your domain and secrets

# 2. Deploy
docker compose -f docker-compose.prod.yml --env-file .env.production up -d

This includes:

• Caddy reverse proxy with automatic TLS
• All services with health checks
• Security hardening (read-only filesystems, no new privileges)
• Structured logging with rotation

Health Endpoints

• API: GET /v1/health
• Auth: GET /health
• Frontend: GET / (nginx health)

File Storage

The backend supports two storage backends:

1. Local (default): Files stored in FILE_STORAGE_DIR
2. S3: Configure S3_* variables and set FILE_STORAGE_PROVIDER=s3

Database Migrations

Migrations run automatically on startup. The migrations directory can be customized via DB_MIGRATIONS_DIR.