Quickstart

This guide shows you two ways to get started with Phaset quickly: running it locally on your machine, or deploying it to free cloud services for a demo accessible from anywhere.

Local

Run Phaset Locally

The fastest way to try Phaset is to run it on your local machine.

Prerequisites

• Node.js 24 or later (download)
• Basic comfort with command-line interfaces
• 10 minutes of your time

All of the below assumes Linux or MacOS or that you use equivalent tooling as expressed in the steps.

Step 1: Install Phaset

Install the Phaset CLI:

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

Add Phaset to your PATH (if needed):

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

Install the Phaset API using the CLI tool:

phaset install

Step 2: Configure Phaset

Create a configuration file manually (as per below) or generate a scaffold using:

phaset init

Edit phaset.config.json with your email settings. For local testing, you can use a service like Mailtrap or your own SMTP server:

{
  "email": {
    "emailSubject": "Sign In To Phaset",
    "user": "[email protected]",
    "password": "your-smtp-password",
    "host": "smtp.mailtrap.io",
    "port": 2525,
    "secure": false
  },
  "auth": {
    "jwtSecret": "your-secret-key-change-this",
    "appUrl": "http://localhost:5173/app"
  },
  "server": {
    "allowedDomains": ["http://localhost:5173"]
  },
  "phaset": {
    "licenseKey": "",
    "bootstrap": {
      "organizationName": "My Organization",
      "adminEmail": "[email protected]"
    }
  }
}

SMTP for Testing

For local development, Mailtrap offers a free SMTP testing service that catches all emails in a sandbox—perfect for trying Phaset without sending real emails!

Step 3: Download and Configure the Web App

Download the Phaset web application from releases.phaset.dev and extract it.

Open index.html in a text editor and verify the API endpoint configuration:

<script>
  window.APP_CONFIG = {
    apiBaseUrl: window.location.href.includes('localhost')
      ? 'http://localhost:3000'
      : 'https://your-production-api.com'
  };
</script>

The default configuration automatically uses http://localhost:3000 when accessing the app via localhost, which matches Phaset’s default port.

Step 4: Start Phaset

Start the API server:

phaset start

In a separate terminal, serve the web app using any static file server:

# Navigate inside of the web app directory
cd path/to/phaset-web

# Simple example using a basic Node.js package called http-server
npx http-server -o -p 5173 --proxy http://localhost:5173?

You should receive an email asking you to join your Phaset organization. Phaset automatically invites the admin email when there is no existing data.

Step 5: Sign In

1. Click the join button in the email you have received (the one you set as BOOTSTRAP_ADMIN_EMAIL)
2. Phaset will process your join request and you’ll be able to sign in
3. Sign in with your email, now that you are part of the organization
4. Check your inbox for a magic link from Phaset
5. Click the link to complete sign-in
6. You’re in! Start exploring Phaset’s features.

Port Configuration

The defaults are:

• API: http://localhost:3000 (configured in Phaset)
• Web App: http://localhost:5173 (your static file server)

These are automatically configured to work together. If you change ports, update:

• auth.appUrl in phaset.config.json to match your web app port
• window.APP_CONFIG.apiBaseUrl in index.html to match your API port

Cloud

Deploy to the Cloud

Get Phaset running using free cloud services so you can try it from anywhere without local setup. Perfect for quick demos and evaluations.

What you’ll deploy

By the end of this guide, you’ll have:

• A Phaset API running on DigitalOcean App Platform
• A Phaset web application hosted on Netlify
• A working demo you can access from anywhere

Prerequisites

• Basic comfort with command-line interfaces
• A DigitalOcean account ($200 free credit)
• A Netlify account (free forever plan)
• 5 minutes of your time

Demo Limitations

This quickstart uses DigitalOcean App Platform’s ephemeral storage for simplicity. Data is not persisted between deployments. For production use, see the Installation Deep Dive for proper infrastructure setup.

Feedback Welcome

Cloud services change frequently. If you encounter issues with this guide, please let us know at [email protected] so we can keep it up to date.

Step 1: Deploy the Web Application

1. Download the Phaset web app from releases.phaset.dev

2. Create a redirects file for single-page app routing:

   • Create a new file named _redirects (no file extension) in the root folder
   • Add this single line:

   /*   /index.html   200

3. Deploy to Netlify:

   • Log into Netlify
   • Click “Add new site” → “Deploy manually”
   • Drag and drop your entire Phaset folder into the upload area
   • Wait ~30 seconds for deployment to complete

4. Copy your site URL from Netlify (you will get a randomized name, which you can configure; it looks like https://something-random-here.netlify.app)

Custom Domain

Want to use your own domain? Netlify makes it easy—just add a custom domain in your site settings. Remember to update the APP_URL and ALLOWED_DOMAINS environment variables in DigitalOcean to match your custom domain.

Step 2: Deploy the API

1. Log into DigitalOcean and navigate to App Platform

2. Click “Create App”

3. Select “Container Image” and choose GitHub Container Registry

   • Repository: phasetdev/phaset-api
   • Image tag: latest
   • Click Next

4. Configure your app:

   • Instance size: Select the smallest available ($5/month)
   • Region: Choose the closest datacenter to you
   • Network: Under HTTP Port, enter 3000

5. Add environment variables under “App-Level Environment Variables”:

   APP_URL=https://your-netlify-url.com/app
   ALLOWED_DOMAINS=https://your-netlify-url.com
   [email protected]
   BOOTSTRAP_ORG_NAME=My Organization
   EMAIL_HOST=smtp.provider.com
   [email protected]
   EMAIL_PASSWORD=your-email-password
   EMAIL_PORT=465                                  # Example
   EMAIL_SECURE=true                               # If needed
   DEMO_MODE=true                                  # If you want demo data to look at

   Important: Set Your Email

   Replace [email protected] and anything else above with your actual details. Note that the user specified in BOOTSTRAP_ADMIN_EMAIL is where you’ll receive your sign-in link.

   SMTP Configuration

   You’ll need your own SMTP server, which for example Google and Proton provide. See the Installation Deep Dive for setup details. Important: Many cloud providers block SMTP—ensure your infrastructure allows SMTP connections on your chosen port (typically 465 or 587).

6. Review and create your app. Wait a minute or so for deployment to complete.

7. Copy your API URL from the app overview page (looks like https://phaset-api-xxxxx.ondigitalocean.app)

8. You should receive an email asking you to join your Phaset organization. Phaset automatically invites the admin email when there is no existing data. For now, refrain from clicking the join button, as we need to finish configuring Phaset.

Step 3: Reference the API in the Web Application

1. Update the API endpoint:

   • Open index.html in a text editor
   • Find the window.APP_CONFIG configuration:

   <script>
     window.APP_CONFIG = {
       apiBaseUrl: window.location.href.includes('localhost')
         ? 'http://localhost:3000'
         : 'https://phaset-api-xxxxx.ondigitalocean.app'
     };
   </script>

   • Replace https://phaset-api-xxxxx.ondigitalocean.app with your DigitalOcean API URL from Step 2

   Matching Configurations

   Make sure your API and web app configurations match:

   • The web app’s apiBaseUrl should point to your API endpoint
   • The API’s APP_URL environment variable should point to your web app’s /app path

   For this cloud setup:

   • Web app → API: Set in window.APP_CONFIG.apiBaseUrl
   • API → Web app: Already set as APP_URL=https://phaset.netlify.app/app

2. Redeploy to Netlify by dragging and dropping your entire Phaset folder into the upload area. Redeployment is very fast, since only a single file is changed.

Step 4: Sign In

1. Click the join button in the email you have received (the one you set as BOOTSTRAP_ADMIN_EMAIL)
2. Phaset will process your join request and you’ll be able to sign in
3. Sign in with your email, now that you are part of the organization
4. Check your inbox for a magic link from Phaset
5. Click the link to complete sign-in
6. You’re in! Start exploring Phaset’s features.

What’s Next?

Now that Phaset is running, here’s what to explore:

• Go on and create your first Record
• Set up integrations to automate your Phaset work
• Time for a production installation?
• Curious? Read the Architecture overview
• Issues? Find your answers on the Troubleshooting page