Configuring Phaset

Phaset is designed to be straightforward to configure while giving you control when you need it. This guide covers everything from the bare minimum to advanced configuration scenarios.

Configuration Overview

Phaset can be configured in three ways, with priorities from highest to lowest:

CLI flags (e.g., phaset start --port 8080)
Environment variables (e.g., PORT=8080)
Configuration file (phaset.config.json)

This flexibility means you can choose the approach that fits your deployment:

Use config files for local development or VMs where you manage files directly
Use environment variables for cloud platforms, containers, or CI/CD pipelines
Use CLI flags for quick overrides during testing

Required Configuration

To run Phaset, you must provide these values:

Email Configuration (Required)

email.host - Your SMTP server hostname
email.user - SMTP username (typically your email address)
email.password - SMTP password or app-specific password

Bootstrap Configuration (Required)

phaset.bootstrap.organizationName - Your organization name
phaset.bootstrap.adminEmail - Admin email address (receives first sign-in link)

Configuration File

The configuration file is the most common way to set up Phaset, especially for local development and self-hosted deployments.

Creating the Configuration File

phaset init

This creates phaset.config.json in your current directory with a template similar to this:

{
  "email": {
    "emailSubject": "Sign In To Phaset",
    "user": "my_user@my_domain.net",
    "password": "my_password",
    "host": "smtp.my_host.net",
    "port": 465,
    "secure": true
  },
  "auth": {
    "jwtSecret": "your-jwt-secret",
    "appUrl": "http://localhost:5173/app"
  },
  "server": {
    "allowedDomains": ["*"]
  },
  "phaset": {
    "licenseKey": "",
    "bootstrap": {
      "organizationName": "My Organization",
      "adminEmail": "me@my_domain.net"
    }
  }
}

Configuration File Location

Phaset looks for phaset.config.json in your current working directory when you run phaset start. This means you can have different configurations for different deployments by running Phaset from different directories.

Environment Variables

Environment variables are ideal for cloud deployments, containers, and CI/CD pipelines where you don’t want to manage configuration files.

Email Configuration

Environment Variable	Description	Default
`EMAIL_HOST`	SMTP server hostname	-
`EMAIL_USER`	SMTP username	-
`EMAIL_PASSWORD`	SMTP password	-
`EMAIL_PORT`	SMTP port	`587`
`EMAIL_SECURE`	Use SSL/TLS (`true`/`false`)	`true`
`EMAIL_SUBJECT`	Subject line for sign-in emails	`"Sign In To Phaset"`
`EMAIL_MAX_RETRIES`	Retry attempts for failed emails	`2`

Authentication Configuration

Environment Variable	Description	Default
`AUTH_JWT_SECRET`	Secret key for JWT signing	`"your-jwt-secret"`
`APP_URL`	URL where users complete sign-in	`"http://localhost:5173/app"`
`AUTH_LINK_EXPIRY`	Magic link expiry in seconds	`900` (15 min)
`AUTH_JWT_EXPIRY`	JWT token expiry in seconds	`900` (15 min)
`AUTH_REFRESH_EXPIRY`	Refresh token expiry in seconds	`604800` (7 days)
`AUTH_MAX_SESSIONS`	Max concurrent sessions per user	`3`

Server Configuration

Environment Variable	Description	Default
`PORT`	Port to listen on	`3000`
`HOST`	Host to bind to	`0.0.0.0`
`ALLOWED_DOMAINS`	Comma-separated list of allowed CORS origins	`"http://localhost:5173,http://0.0.0.0:5173"`

Storage Configuration

Environment Variable	Description	Default
`DATA_DIR`	Directory for database files	Current directory
`STORAGE_KEY`	Encryption key for sensitive data	-

Phaset Configuration

Environment Variable	Description	Default
`BOOTSTRAP_ORG_NAME`	Organization name for initial setup	-
`BOOTSTRAP_ADMIN_EMAIL`	Admin email for initial setup	-
`PHASET_LICENSE_KEY`	Your Phaset license key	`""`
`DEMO_MODE`	Enable demo mode (`true`/`false`)	`false`
`DEBUG`	Enable debug logging (`true`/`false`)	`false`

Example: Cloud Deployment with Environment Variables

In your App Platform configuration, add these environment variables:

APP_URL=https://phaset.yourcompany.com/app
ALLOWED_DOMAINS=https://phaset.yourcompany.com
[email protected]
BOOTSTRAP_ORG_NAME=Your Company
EMAIL_HOST=smtp.gmail.com
[email protected]
EMAIL_PASSWORD=your-app-password
EMAIL_PORT=465
EMAIL_SECURE=true
AUTH_JWT_SECRET=your-secure-random-string

Pass environment variables when running your container:

docker run -d \
  -e EMAIL_HOST=smtp.gmail.com \
  -e [email protected] \
  -e EMAIL_PASSWORD=your-app-password \
  -e EMAIL_PORT=465 \
  -e EMAIL_SECURE=true \
  -e AUTH_JWT_SECRET=your-secure-random-string \
  -e APP_URL=https://phaset.yourcompany.com/app \
  -e [email protected] \
  -e BOOTSTRAP_ORG_NAME="Your Company" \
  -e ALLOWED_DOMAINS=https://phaset.yourcompany.com \
  -p 3000:3000 \
  phaset:latest

Add environment variables to your service file:

[Service]
Environment="APP_URL=https://phaset.yourcompany.com/app"
Environment="ALLOWED_DOMAINS=https://phaset.yourcompany.com"
Environment="[email protected]"
Environment="BOOTSTRAP_ORG_NAME=Your Company"
Environment="EMAIL_HOST=smtp.gmail.com"
Environment="[email protected]"
Environment="EMAIL_PASSWORD=your-app-password"
Environment="EMAIL_PORT=465"
Environment="EMAIL_SECURE=true"
Environment="AUTH_JWT_SECRET=your-secure-random-string"

CLI Flags

CLI flags provide the highest priority and are useful for quick overrides during development or testing.

Authentication Flags

--jwtSecret <secret>                 JWT secret for token signing
--magicLinkExpirySeconds <seconds>   Magic link expiry time
--jwtExpirySeconds <seconds>         JWT expiry time
--refreshTokenExpirySeconds <secs>   Refresh token expiry time
--maxActiveSessions <number>         Max concurrent sessions
--appUrl <url>                       Application URL for sign-in completion
--debug                              Enable debug mode (flag, no value)

Email Flags

--emailSubject <subject>             Email subject line
--emailHost <hostname>               SMTP server hostname
--emailUser <username>               SMTP username
--emailPassword <password>           SMTP password
--emailPort <port>                   SMTP port number
--emailSecure                        Use SSL/TLS (flag, no value)
--emailMaxRetries <number>           Max retry attempts

Server Flags

--port <port>                        Port to listen on
--host <hostname>                    Host to bind to
--allowed <domain1,domain2,...>      Comma-separated allowed domains

Examples of allowed domains:

// Allow specific domains (recommended for production)
"allowedDomains": [
  "https://phaset.example.com",
  "https://app.example.com"
]

// Allow all domains (development only)
"allowedDomains": ["*"]

// Allow localhost for development
"allowedDomains": [
  "http://localhost:5173",
  "http://localhost:3000"
]

Storage Flags

--db <directory>                     Database directory path
--encryptionKey <key>                Encryption key for storage

Phaset Flags

--licenseKey <key>                   Phaset license key
--demoMode                           Enable demo mode (flag, no value)
--bootstrapOrganizationName <name>   Organization name
--bootstrapAdminEmail <email>        Admin email address

Example: Override Port and Debug Mode

phaset start --port 8080 --debug

Example: Test with Different Config

phaset start --emailHost smtp.mailtrap.io --emailPort 2525 --demoMode

Configuration Priority

When the same setting is provided in multiple ways, Phaset uses this priority order:

CLI flags (highest priority)
Environment variables
Configuration file
Default values (lowest priority)

Example Priority Resolution

If you have:

Config file: "port": 3000
Environment variable: PORT=8080
CLI flag: --port 9000

Phaset will use port 9000 (CLI flag wins).

Complete Configuration Reference

Here’s a fully documented configuration file showing all available options:

{
  "email": {
    "emailSubject": "Sign In To Phaset",
    "user": "[email protected]",
    "password": "your-smtp-password",
    "host": "smtp.gmail.com",
    "port": 465,
    "secure": true,
    "maxRetries": 2
  },
  "auth": {
    "jwtSecret": "your-secret-key-change-this",
    "magicLinkExpirySeconds": 900,
    "jwtExpirySeconds": 900,
    "refreshTokenExpirySeconds": 604800,
    "maxActiveSessions": 3,
    "appUrl": "https://phaset.yourcompany.com/app",
    "debug": false
  },
  "server": {
    "port": 3000,
    "host": "0.0.0.0",
    "allowedDomains": [
      "https://phaset.yourcompany.com",
      "http://localhost:5173"
    ]
  },
  "storage": {
    "databaseDirectory": "",
    "encryptionKey": "",
    "debug": false
  },
  "phaset": {
    "licenseKey": "",
    "demoMode": false,
    "bootstrap": {
      "organizationName": "Your Company",
      "adminEmail": "[email protected]"
    }
  }
}

Configuration Validation

When you start Phaset, it validates your configuration and provides helpful error messages if required fields are missing:

$ phaset start
Error: Missing email.host value
Error: Missing email.user value
Error: Missing email.password value
Error: Missing phaset.bootstrap.organizationName value
Error: Missing phaset.bootstrap.adminEmail value

This ensures you can’t accidentally start Phaset with incomplete configuration.

Common Configuration Scenarios

Local Development

Goal: Quick setup for testing on your laptop

{
  "email": {
    "user": "[email protected]",
    "password": "test-password",
    "host": "smtp.mailtrap.io",
    "port": 2525,
    "secure": false
  },
  "auth": {
    "jwtSecret": "dev-secret",
    "appUrl": "http://localhost:5173/app"
  },
  "server": {
    "allowedDomains": ["*"]
  },
  "phaset": {
    "demoMode": true,
    "bootstrap": {
      "organizationName": "Dev Org",
      "adminEmail": "[email protected]"
    }
  }
}

Production VPS/VM

Goal: Secure production deployment on your infrastructure

{
  "email": {
    "user": "[email protected]",
    "password": "secure-app-password",
    "host": "smtp.gmail.com",
    "port": 465,
    "secure": true
  },
  "auth": {
    "jwtSecret": "generated-with-openssl-rand-base64-32",
    "appUrl": "https://phaset.yourcompany.com/app",
    "jwtExpirySeconds": 3600,
    "refreshTokenExpirySeconds": 2592000
  },
  "server": {
    "allowedDomains": [
      "https://phaset.yourcompany.com"
    ]
  },
  "phaset": {
    "licenseKey": "your-license-key-if-applicable",
    "bootstrap": {
      "organizationName": "Your Company",
      "adminEmail": "[email protected]"
    }
  }
}

Cloud Platform (Using Environment Variables)

Goal: Deploy on DigitalOcean, AWS, or similar without managing config files

Set these environment variables in your platform’s dashboard:

# Required
EMAIL_HOST=smtp.sendgrid.net
EMAIL_USER=apikey
EMAIL_PASSWORD=your-sendgrid-api-key
BOOTSTRAP_ORG_NAME="Your Company"
BOOTSTRAP_ADMIN_EMAIL=[email protected]

# Important
AUTH_JWT_SECRET=your-secure-random-string
APP_URL=https://phaset.yourcompany.com/app
ALLOWED_DOMAINS=https://phaset.yourcompany.com

# Optional
EMAIL_PORT=465
EMAIL_SECURE=true
PORT=3000

Security Recommendations

JWT Secret

Always generate a strong, random JWT secret:

openssl rand -base64 32

Never commit secrets to version control. Use environment variables or secret management tools.

Storage Encryption Key

If you provide a storage.encryptionKey, Phaset encrypts sensitive data at rest. Generate it the same way:

openssl rand -base64 32

CORS Configuration

In production, never use "allowedDomains": ["*"]. Always specify exact domains:

"allowedDomains": [
  "https://phaset.yourcompany.com"
]