Installation

Phaset runs on a single host within your infrastructure and is deliberately intended to be straightforward to get working.

System Requirements

Operating System:

• Linux (any modern distribution)
• macOS

Runtime:

• Node.js 24 or later (download here)

Hardware:

• Works on anything from a Raspberry Pi to dedicated servers
• Should work fine on any lightweight, conventional VPS or VM setup

Network:

• Internet access during initial installation (to download Phaset)
• SMTP server access (for authentication emails)
• Inbound network access for users and integrations

Quick Start

The fastest way to install Phaset is using the one-line installer:

curl -sSL https://releases.phaset.dev/install.sh | bash

This installs the Phaset CLI to ~/.local/bin/phaset. You may need to add this directory to your PATH:

export PATH="$HOME/.local/bin:$PATH"

Tip

Add the PATH export to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make it permanent.

Installation Steps

1. Install the Phaset CLI using the quick start command above.
2. Install the Phaset API: phaset install. This downloads and installs the Phaset API to ~/.phaset/.
3. Create a configuration file in your desired working directory: phaset init. This creates a phaset.config.json template file.
4. Configure Phaset by editing phaset.config.json with your settings (see Configuration below).
5. Start Phaset: phaset start. The API server will start and display the URL where Phaset is accessible.

That’s it! Phaset is now running on your infrastructure.

Configuration

The phaset.config.json file contains all settings for your Phaset instance. Here’s a complete example with explanations:

{
  "email": {
    "emailSubject": "Sign In To Phaset",
    "user": "signin@my_company.cloud",
    "password": "your_smtp_password",
    "host": "smtp.provider.com",
    "port": 465,
    "secure": true,
    "maxRetries": 2
  },
  "auth": {
    "jwtSecret": "your-secret-key-change-this",
    "magicLinkExpirySeconds": 900,
    "jwtExpirySeconds": 3600,
    "refreshTokenExpirySeconds": 604800,
    "maxActiveSessions": 3,
    "appUrl": "https://phaset.example.com/app/finishSignIn"
  },
  "server": {
    "allowedDomains": [
      "https://phaset.example.com",
      "http://localhost:5173"
    ]
  },
  "phaset": {
    "licenseKey": "",
    "demoMode": false,
    "bootstrap": {
      "organizationName": "My Organization",
      "adminEmail": "admin@my_company.cloud"
    }
  }
}

Email Configuration

Phaset uses email for passwordless authentication (magic links).

Field	Description	Required
emailSubject	Subject line for sign-in emails	Yes
user	SMTP username (often your email address)	Yes
password	SMTP password or app-specific password	Yes
host	SMTP server hostname	Yes
port	SMTP server port (usually 465 for SSL or 587 for TLS)	Yes
secure	Use SSL/TLS (recommended: true)	Yes
maxRetries	Number of retry attempts for failed emails	No (default: 2)

Common SMTP Providers

• Gmail: smtp.gmail.com (port 465, requires app password)
• Outlook/Office 365: smtp.office365.com (port 587)
• SendGrid: smtp.sendgrid.net (port 465)
• AWS SES: Regional endpoint (e.g., email-smtp.us-east-1.amazonaws.com)

Authentication Configuration

Controls how users authenticate with Phaset.

Field	Description	Required
jwtSecret	Secret key for JWT token signing (use a strong random string)	Yes
magicLinkExpirySeconds	How long magic links remain valid (default: 900 = 15 minutes)	No
jwtExpirySeconds	Session token lifetime (default: 3600 = 1 hour)	No
refreshTokenExpirySeconds	Refresh token lifetime (default: 604800 = 7 days)	No
maxActiveSessions	Maximum concurrent sessions per user (default: 3)	No
appUrl	URL where users complete sign-in (must match your deployment)	Yes

Security

Generate a strong jwtSecret using a password manager or command like:

openssl rand -base64 32

Never commit this secret to version control.

Server Configuration

Controls CORS and network access.

Field	Description	Required
allowedDomains	Array of allowed origins for CORS. Use ["*"] to allow all (not recommended for production)	Yes

Examples:

// 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"
]

Phaset Configuration

Organization setup and licensing.

Field	Description	Required
licenseKey	Your Phaset license key. Leave empty for personal use.	No
demoMode	Should a demo organization with demo data be used?	No
bootstrap.organizationName	Your organization name (used during initial setup)	Yes
bootstrap.adminEmail	Admin email address (receives first magic link)	Yes

Licensing

Phaset is free for personal use. For organizational use, you’ll need a license key. Leave the licenseKey field empty during evaluation—Phaset will function fully without it for personal projects.

CLI Commands

The Phaset CLI provides several commands for managing your installation:

# Install the Phaset API
phaset install

# Check for and install updates
phaset upgrade

# Create a config file template
phaset init

# Start the Phaset API server
phaset start

# Validate your Phaset license key
phaset license

# Read the Phaset documentation
phaset docs

# Read the Phaset software agreement
phaset legal

# Remove Phaset from your system
phaset uninstall

Deployment Scenarios

Local Development

For local development and evaluation:

{
  "auth": {
    "appUrl": "http://localhost:5173/app/finishSignIn"
  },
  "server": {
    "allowedDomains": ["http://localhost:5173"]
  }
}

Start Phaset:

phaset start

Access at http://localhost:8080 (or the port shown in the startup logs).

VPS/VM Production

For production deployment on a VPS or VM:

1. Set up a reverse proxy (nginx, Caddy, Traefik) with SSL/TLS
2. Configure your domain to point to the server
3. Update phaset.config.json:

{
  "auth": {
    "appUrl": "https://phaset.example.com/app/finishSignIn"
  },
  "server": {
    "allowedDomains": ["https://phaset.example.com"]
  }
}

4. Start Phaset as a system service (see Running as a Service)

Docker (Community)

While Phaset doesn’t officially provide Docker images, you can containerize it:

FROM node:24-slim

WORKDIR /app

# Install Phaset
RUN curl -sSL https://releases.phaset.dev/install.sh | bash && \
    export PATH="$HOME/.local/bin:$PATH" && \
    phaset install

# Copy your config
COPY phaset.config.json /app/

# Expose port
EXPOSE 8080

# Start Phaset
CMD ["/root/.local/bin/phaset", "start"]

Note

This is a community approach. Official container support may be added in future releases.

Running as a Service

To run Phaset as a background service that starts automatically:

systemd (Linux)

Create /etc/systemd/system/phaset.service:

[Unit]
Description=Phaset API Server
After=network.target

[Service]
Type=simple
User=phaset
WorkingDirectory=/home/phaset/phaset-data
ExecStart=/home/phaset/.local/bin/phaset start
Restart=on-failure
RestartSec=10
Environment="NODE_ENV=production"

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable phaset
sudo systemctl start phaset

Check status:

sudo systemctl status phaset

View logs:

sudo journalctl -u phaset -f

macOS (launchd)

Create ~/Library/LaunchAgents/com.phaset.api.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.phaset.api</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/YOUR_USERNAME/.local/bin/phaset</string>
        <string>start</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/YOUR_USERNAME/phaset-data</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/YOUR_USERNAME/phaset-data/phaset.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/YOUR_USERNAME/phaset-data/phaset.error.log</string>
</dict>
</plist>

Load the service:

launchctl load ~/Library/LaunchAgents/com.phaset.api.plist

Updating Phaset

To update to the latest version:

phaset upgrade

This checks for updates and installs them automatically. Your configuration and data are preserved.

Data Storage

Phaset stores all data locally on your host:

• Installation: ~/.phaset/ (API binary and version info)
• Configuration: phaset.config.json (in your working directory)
• Data: Local database files (in your working directory)

Backup Recommendations

Back up your working directory regularly, which contains:

• phaset.config.json (configuration)
• Database files (all your Records, Metrics, etc.)

Troubleshooting

Command not found: phaset

Add ~/.local/bin to your PATH:

export PATH="$HOME/.local/bin:$PATH"

Make it permanent by adding to ~/.bashrc or ~/.zshrc.

Node.js version error

Phaset requires Node.js 24 or later. Update Node.js:

# Check current version
node --version

# Install latest LTS from https://nodejs.org/

Cannot connect to SMTP server

Verify your SMTP settings:

• Check host and port are correct
• Ensure firewall allows outbound connections to SMTP port
• For Gmail, use an app password
• Test with a simple SMTP tool or telnet

Port already in use

If port 8080 is occupied, specify a different port:

phaset start --port 3000

Permission denied errors

Ensure the user running Phaset has write permissions to:

• Working directory (for database files)
• ~/.phaset/ directory

Uninstalling

To completely remove Phaset:

phaset uninstall

This removes:

• The Phaset CLI (~/.local/bin/phaset)
• The Phaset API (~/.phaset/)

Caution

This does NOT remove your data or configuration. Delete your working directory manually if you want to remove all data. TODO

Next Steps

Now that Phaset is installed:

1. Sign in using the admin email you configured
2. Create your first Record — See Your First Record
3. Set up integrations — See Integration Guide
4. Explore the architecture — See Architecture