Configuration Reference

The following reference covers all supported configuration options in Paideia LMS. Paideia LMS can be configured through environment variables, a .env file, and a paideia.config.json file.

Configuration Priority

Paideia LMS loads configuration from multiple sources in the following order of priority (higher priority overrides lower priority):

paideia.config.json - System configuration file (highest priority for system settings)
.env file - Local environment variables (higher priority than hosting environment)
Hosting environment variables - Variables set by your hosting platform (lowest priority)

Environment Variables

Environment variables can be set in your hosting environment or in a .env file at the path where you run the application. The .env file has higher priority than hosting environment variables.

Database Configuration

`DATABASE_URL`

Type: string
Required: true
Sensitive: true

The connection URL for your database. This is required for Paideia LMS to connect to your database.

DATABASE_URL=postgresql://user:password@localhost:5432/paideia

Server Configuration

`PORT`

Type: number
Required: false
Sensitive: true
Default: 3001

The port number for the Paideia LMS backend server.

PORT=3001

`FRONTEND_PORT`

Type: number
Required: false
Sensitive: true
Default: 3000

The port number for the Paideia LMS frontend application.

FRONTEND_PORT=3000

Storage Configuration (S3/MinIO)

`S3_URL`

Type: string
Required: true
Sensitive: true

The URL endpoint for your S3-compatible storage service (e.g., MinIO, AWS S3).

S3_URL=https://s3.amazonaws.com

`S3_ACCESS_KEY`

Type: string
Required: true
Sensitive: true

The access key ID for your S3-compatible storage service.

S3_ACCESS_KEY=your-access-key

`S3_SECRET_KEY`

Type: string
Required: true
Sensitive: true

The secret access key for your S3-compatible storage service.

S3_SECRET_KEY=your-secret-key

`S3_REGION`

Type: string
Required: false
Sensitive: true
Default: "us-east-1"

The region for your S3-compatible storage service.

S3_REGION=us-east-1

`S3_BUCKET`

Type: string
Required: false
Sensitive: true

The bucket name for your S3-compatible storage service. The bucket name must match the bucket name in your MinIO configuration.

S3_BUCKET=paideia-media

`S3_ENDPOINT_URL`

Type: string
Required: true
Sensitive: true

The endpoint URL for your S3-compatible storage service (without the bucket name). This should match the endpoint URL in your MinIO configuration.

S3_ENDPOINT_URL=https://storage.example.com

Authentication & Security

`PAYLOAD_SECRET`

Type: string
Required: true
Sensitive: true

The secret key used by Payload CMS for authentication and encryption. This should be a long, randomly generated string.

PAYLOAD_SECRET=your-secret-key-here

Email Configuration

`SMTP_HOST`

Type: string
Required: false
Sensitive: true

The SMTP server hostname for sending emails.

SMTP_HOST=smtp.example.com

`SMTP_USER`

Type: string
Required: false
Sensitive: true

The SMTP username for authentication.

SMTP_USER=your-smtp-username

`SMTP_PASS`

Type: string
Required: false
Sensitive: true

The SMTP password for authentication.

SMTP_PASS=your-smtp-password

`RESEND_API_KEY`

Type: string
Required: false
Sensitive: true

The API key for Resend email service (alternative to SMTP).

RESEND_API_KEY=re_your-api-key

`EMAIL_FROM_ADDRESS`

Type: string
Required: false
Sensitive: false
Default: "info@paideialms.com"

The email address used as the “From” address for system emails.

EMAIL_FROM_ADDRESS=noreply@yourdomain.com

`EMAIL_FROM_NAME`

Type: string
Required: false
Sensitive: false
Default: "Paideia LMS"

The display name used as the “From” name for system emails.

EMAIL_FROM_NAME=Your School Name

System Mode

`SANDBOX_MODE`

Type: string
Required: false
Sensitive: false
Default: "0"

Enables sandbox mode for development and testing. When enabled ("1" or "true"), the system will:

Automatically reset the database on server startup with seed data from seed.json
Schedule daily database resets via cron job (at midnight)
Provide manual reset capability via paideia sandbox reset CLI command

Zero Downtime Reset: The sandbox reset process achieves zero downtime by selectively deleting user data while preserving system tables (job logs, migrations, etc.). The application continues operating normally during the reset process, unlike migrate fresh which drops the entire database and causes downtime.

SANDBOX_MODE=1

Zero Downtime

When sandbox mode is enabled, database resets preserve system tables (payload-jobs, payload-jobs-log, payload-migrations, etc.) while only deleting user data. This allows the application to continue operating during resets, achieving zero downtime.

CORS Configuration

`CORS_ORIGINS`

Type: string
Required: false
Sensitive: false
Default: ""

Comma-separated list of allowed CORS origins. If empty, defaults to localhost URLs for both frontend and backend ports. Use "*" to allow all origins (not recommended for production).

CORS_ORIGINS=http://localhost:3000,https://yourdomain.com

Special values:

Empty string: Defaults to http://localhost:3000 and http://localhost:3001
"*": Allows all origins
Comma-separated URLs: Allows specific origins

CSRF Configuration

`CSRF_ORIGINS`

Type: string
Required: false
Sensitive: false
Default: ""

Comma-separated list of allowed CSRF origins. If empty, defaults to localhost frontend port and “localhost” hostname. Wildcard "*" is not supported for security reasons.

CSRF_ORIGINS=http://localhost:3000,https://yourdomain.com

Special values:

Empty string: Defaults to http://localhost:3000 and "localhost"
Comma-separated URLs/domains: Allows specific origins

Seed Data Configuration

When SANDBOX_MODE is enabled, Paideia LMS can use seed data from a seed.json file to populate the database with initial test data. This file should be placed at the path where you run the application.

Reset Behavior: When sandbox mode resets the database (on startup or via cron job), it uses a zero downtime approach that:

Preserves system tables (payload-jobs, payload-jobs-log, payload-migrations, etc.)
Selectively deletes only user data (users, courses, enrollments, submissions, etc.)
Re-seeds the database with fresh data from seed.json
Allows the application to continue operating during the reset process

Seed Data Schema

The seed.json file must follow this structure:

{
  "admin": {
    "email": "admin@example.com",
    "password": "password123",
    "firstName": "Admin",
    "lastName": "User"
  },
  "users": {
    "student": {
      "email": "student@example.com",
      "password": "password123",
      "firstName": "Student",
      "lastName": "User"
    },
    "teacher": {
      "email": "teacher@example.com",
      "password": "password123",
      "firstName": "Teacher",
      "lastName": "User"
    },
    "ta": {
      "email": "ta@example.com",
      "password": "password123",
      "firstName": "Teaching",
      "lastName": "Assistant"
    },
    "additionalStudents": [
      {
        "email": "student2@example.com",
        "password": "password123",
        "firstName": "Student",
        "lastName": "Two"
      }
    ]
  },
  "courses": [
    {
      "title": "Introduction to Computer Science",
      "description": "A beginner-friendly course",
      "slug": "intro-cs",
      "status": "published"
    }
  ],
  "modules": {
    "page": {
      "title": "Welcome Page",
      "description": "A welcome page module",
      "content": "# Welcome"
    },
    "additional": [
      {
        "type": "quiz",
        "title": "Quiz 1",
        "description": "First quiz",
        "status": "published",
        "instructions": "Answer all questions",
        "points": 100,
        "timeLimit": 60
      }
    ]
  },
  "sections": [
    {
      "title": "Week 1",
      "description": "Introduction"
    }
  ],
  "enrollmentStatuses": ["active", "inactive", "completed"]
}

Seed Data Fields

`admin`

Type: object
Required: true

The admin user account to create.

email - Admin email address
password - Admin password
firstName - Admin first name
lastName - Admin last name

`users`

Type: object
Required: true

Predefined user accounts for testing.

student - Default student account
teacher - Default teacher account
ta - Default teaching assistant account
additionalStudents - Array of additional student accounts

Each user object requires:

email - User email address
password - User password
firstName - User first name
lastName - User last name

`courses`

Type: array
Required: true

Array of courses to create.

Each course object requires:

title - Course title
description - Course description
slug - Course URL slug
status - Course status: "published", "draft", or "archived"

`modules`

Type: object
Required: true

Modules to create for testing.

page - Default page module
- title - Module title
- description - Module description
- content - Module content (markdown)
additional - Array of additional modules

Each additional module can be one of:

Page (type: "page")
- title, description, status, content
Quiz (type: "quiz")
- title, description, status, instructions, points, timeLimit
Assignment (type: "assignment")
- title, description, status, instructions, dueDate, maxAttempts
Discussion (type: "discussion")
- title, description, status, instructions, minReplies, threadSorting
Whiteboard (type: "whiteboard")
- title, description, status

`sections`

Type: array
Required: true

Array of course sections to create.

Each section object requires:

title - Section title
description - Section description

`enrollmentStatuses`

Type: array
Required: true

Array of enrollment statuses to use. Valid values: "active", "inactive", "completed"

System Configuration File

For complex and structured settings (usually system configuration), Paideia LMS reads from a paideia.config.json file at the path where you run the application.

Configuration File Priority

The paideia.config.json file has the highest priority for system settings. Values defined in this file will:

Always override values stored in the database
Lock the edit field in the UI - administrators cannot change settings that are defined in the config file

For example, if the system name is defined in paideia.config.json, the system name input field will be disabled in the UI, and even administrators cannot change it.

Example Configuration File

{
  "systemName": "My School LMS",
  "featureFlags": {
    "enableNewFeature": true,
    "enableBetaFeatures": false
  },
  "systemSettings": {
    "maxFileSize": 10485760,
    "allowedFileTypes": ["pdf", "doc", "docx"]
  }
}

Configuration File Behavior

When a setting is defined in paideia.config.json:

The setting value is read from the file
The setting is locked in the UI (input field is disabled)
Administrators cannot override the value through the UI
The config file value takes precedence over database values

This ensures that critical system settings can be managed through version-controlled configuration files rather than through the UI.

Best Practices

When configuring Paideia LMS:

Use .env files for local development and sensitive credentials
Use hosting environment variables for production deployments
Use paideia.config.json for system-wide settings that should be version-controlled
Never commit .env files to version control
Always commit paideia.config.json to version control (with appropriate redaction of sensitive data)
Use seed.json only in sandbox mode for development and testing
Keep sensitive values (passwords, API keys) in environment variables, not in config files

Contribute Community Sponsor