Configuration

Overview

ARCA uses environment variables to configure both the backend (NestJS) and frontend (Next.js) applications. This guide details all configuration options.

Backend Configuration

The backend application (apps/backend) uses the following environment variables.

Database Configuration

DATABASE_URL

string

required

PostgreSQL connection string for PrismaFormat:

postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=SCHEMA

Example:

DATABASE_URL="postgresql://postgres:password@localhost:5432/arca_db?schema=public"

Production Example:

DATABASE_URL="postgresql://user:[email protected]:5432/arca_production"

JWT Authentication

JWT_SECRET

string

required

Secret key for signing JWT tokens

JWT_SECRET="your-super-secret-key-change-in-production"

Use a strong, random secret in production. Generate one with:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

JWT_TOKEN_AUDIENCE

string

JWT token audience claim (optional)

JWT_TOKEN_AUDIENCE="arca-api"

JWT_TOKEN_ISSUER

string

JWT token issuer claim (optional)

JWT_TOKEN_ISSUER="arca-backend"

JWT_TTL

string

JWT token time-to-live (optional)

JWT_TTL="3600s"  # 1 hour
JWT_TTL="7d"     # 7 days

Server Configuration

PORT

number

default:"3333"

Port for the backend server

PORT=3333

CORS_ORIGIN

string

default:"http://localhost:3000"

Allowed CORS origin(s) for the frontendDevelopment:

CORS_ORIGIN="http://localhost:3000"

Production:

CORS_ORIGIN="https://arca.example.com"

Multiple origins:

CORS_ORIGIN="https://arca.example.com,https://admin.arca.example.com"

NODE_ENV

string

Node.js environment

NODE_ENV="development"  # or "production", "test"

This affects which .env file is loaded (.env.development, .env.production, etc.)

Complete Backend .env Example

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/arca_dev"

# JWT Configuration
JWT_SECRET="dev-secret-key-change-this"
JWT_TOKEN_AUDIENCE="arca-api"
JWT_TOKEN_ISSUER="arca-backend"
JWT_TTL="24h"

# Server
PORT=3333
CORS_ORIGIN="http://localhost:3000"
NODE_ENV="development"

Frontend Configuration

The frontend application (apps/frontend) uses Next.js public environment variables.

Next.js environment variables prefixed with NEXT_PUBLIC_ are exposed to the browser. Never include secrets in these variables.

API Configuration

NEXT_PUBLIC_API_URL

string

default:"http://localhost:3333"

Backend API base URLDevelopment:

NEXT_PUBLIC_API_URL="http://localhost:3333"

Production:

NEXT_PUBLIC_API_URL="https://api.arca.example.com"

NextAuth Configuration

ARCA uses NextAuth for authentication. Configure these in apps/frontend/.env.local:

NEXTAUTH_URL

string

The canonical URL of your siteDevelopment:

NEXTAUTH_URL="http://localhost:3000"

Production:

NEXTAUTH_URL="https://arca.example.com"

NEXTAUTH_SECRET

string

required

Secret key for encrypting NextAuth tokens

NEXTAUTH_SECRET="your-nextauth-secret-change-in-production"

Generate a secure secret:

openssl rand -base64 32

Complete Frontend .env Example

# API Configuration
NEXT_PUBLIC_API_URL="http://localhost:3333"

# NextAuth
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="dev-nextauth-secret-change-this"

Environment File Priority

Both applications follow standard environment file loading:

Backend (NestJS)

Files are loaded in this order (later files override earlier ones):

.env
.env.${NODE_ENV} (e.g., .env.production)
Environment variables set in the shell

Frontend (Next.js)

Files are loaded in this order:

.env
.env.local (ignored by git)
.env.${NODE_ENV} (e.g., .env.production)
.env.${NODE_ENV}.local

Never commit .env.local or files containing secrets to version control. Add them to .gitignore.

Security Best Practices

Use Strong Secrets

Generate cryptographically secure secrets:

# For JWT_SECRET
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# For NEXTAUTH_SECRET
openssl rand -base64 32

Separate Development and Production

Use different values for development and production:

Different database credentials
Different JWT secrets
Different API URLs

Use Environment Variables in Production

Don’t use .env files in production. Instead:

Set environment variables directly in your hosting platform
Use secrets management (AWS Secrets Manager, etc.)
Use container orchestration secrets (Docker Swarm, Kubernetes)

Validate Environment Variables

The backend uses @nestjs/config for validation. Add validation schemas for required variables.

Deployment-Specific Configuration

Vercel (Frontend)
Railway/Heroku (Backend)
Docker

Add environment variables in Vercel dashboard:

Go to Project Settings → Environment Variables
Add:
- NEXT_PUBLIC_API_URL
- NEXTAUTH_URL
- NEXTAUTH_SECRET
Set appropriate values for Production/Preview/Development

Set environment variables via CLI or dashboard:

# Railway
railway variables set DATABASE_URL="postgresql://..."
railway variables set JWT_SECRET="..."

# Heroku
heroku config:set DATABASE_URL="postgresql://..."
heroku config:set JWT_SECRET="..."

Use environment files or pass variables:

docker-compose.yml

services:
  backend:
    env_file:
      - ./apps/backend/.env
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - JWT_SECRET=${JWT_SECRET}
  
  frontend:
    environment:
      - NEXT_PUBLIC_API_URL=http://backend:3333

Troubleshooting

Environment Variables Not Loading

Ensure file names are correct (.env, not env or .env.txt)
Check file is in the correct directory (apps/backend or apps/frontend)
Restart the development server after changing .env files
For Next.js, use NEXT_PUBLIC_ prefix for client-side variables

CORS Errors

Verify CORS_ORIGIN matches your frontend URL exactly
Include protocol (http:// or https://)
Don’t include trailing slash
Check browser console for the exact origin being rejected

JWT Token Errors

Ensure JWT_SECRET is set and matches on all instances
Verify JWT_TTL format is valid
Check token expiration settings

Next Steps

Database Setup

Configure and manage your PostgreSQL database

Production Deployment

Deploy to production environments

Get Started

Core Features

User Management

Deployment

Development

Configuration

Overview

Backend Configuration

Database Configuration

JWT Authentication

Server Configuration

Complete Backend .env Example

Frontend Configuration

API Configuration

NextAuth Configuration

Complete Frontend .env Example

Environment File Priority

Security Best Practices

Deployment-Specific Configuration

Troubleshooting

Next Steps

Database Setup

Production Deployment

Build docs developers (and LLMs) love

Get Started

Core Features

User Management

Deployment

Development

​Overview

​Backend Configuration

​Database Configuration

​JWT Authentication

​Server Configuration

​Complete Backend .env Example

​Frontend Configuration

​API Configuration

​NextAuth Configuration

​Complete Frontend .env Example

​Environment File Priority

​Security Best Practices

​Deployment-Specific Configuration

​Troubleshooting

​Next Steps

Database Setup

Production Deployment

Build docs developers (and LLMs) love

Overview

Backend Configuration

Database Configuration

JWT Authentication

Server Configuration

Complete Backend .env Example

Frontend Configuration

API Configuration

NextAuth Configuration

Complete Frontend .env Example

Environment File Priority

Security Best Practices

Deployment-Specific Configuration

Troubleshooting

Next Steps