Vercel

Deploy Hyperterse directly on Vercel using serverless functions. Since Hyperterse is a single executable binary, it works beautifully with Vercel’s Fluid compute infrastructure, providing automatic scaling, zero-configuration deployment, and pay-per-use pricing.

These instructions are a work in progress. Please report any issues or suggestions to the GitHub repository.

Option 1: Deploy Hyperterse on Vercel Recommended

Deploy Hyperterse directly as a serverless function on Vercel. Since Hyperterse is a single executable binary, it works excellently with Vercel’s Fluid compute infrastructure.

1. Export your Hyperterse bundle

   hyperterse export -f config.terse -o dist

   This creates a self-contained script in the dist/ directory. The script name matches your config file name (without the .terse extension).

2. Create a Vercel serverless function

   Create an Express adapter that runs Hyperterse:

   api/index.js

   import express from 'express'
   import { spawn } from 'child_process'
   import { fileURLToPath } from 'url'
   import { dirname, join } from 'path'
   
   const __filename = fileURLToPath(import.meta.url)
   const __dirname = dirname(__filename)
   
   const app = express()
   app.use(express.json())
   
   // Path to the exported Hyperterse script
   const scriptPath = join(__dirname, '../dist/config') // Adjust to your script name
   let hyperterseProcess = null
   
   // Start Hyperterse on first request (lazy initialization)
   function ensureHyperterseRunning() {
     if (!hyperterseProcess || hyperterseProcess.killed) {
       hyperterseProcess = spawn('bash', [scriptPath], {
         env: {
           ...process.env,
           PORT: process.env.PORT || '8080',
         },
         stdio: ['ignore', 'pipe', 'pipe'],
       })
   
       hyperterseProcess.on('error', (err) => {
         console.error('Failed to start Hyperterse:', err)
       })
     }
     return hyperterseProcess
   }
   
   // Proxy all requests to Hyperterse
   app.all('*', async (req, res) => {
     ensureHyperterseRunning()
   
     // Wait a moment for Hyperterse to start
     await new Promise((resolve) => setTimeout(resolve, 100))
   
     try {
       const response = await fetch(
         `http://localhost:${process.env.PORT || 8080}${req.path}`,
         {
           method: req.method,
           headers: {
             ...req.headers,
             host: undefined, // Remove host header
           },
           body:
             req.method !== 'GET' && req.method !== 'HEAD'
               ? JSON.stringify(req.body)
               : undefined,
         },
       )
   
       const data = await response.json().catch(() => response.text())
       res.status(response.status).json(data)
     } catch (error) {
       res.status(500).json({ error: error.message })
     }
   })
   
   export default app

3. Configure Vercel

   Create a vercel.json configuration:

   vercel.json

   {
     "functions": {
       "api/index.js": {
         "runtime": "nodejs20.x",
         "memory": 1024,
         "maxDuration": 30
       }
     }
   }

4. Set environment variables

   In Vercel dashboard:

   • Go to Settings → Environment Variables
   • Add DATABASE_URL with your database connection string
   • Add any other required environment variables from your config

5. Deploy

   # Install Vercel CLI
   npm i -g vercel
   
   # Deploy
   vercel --prod

   Or connect your GitHub repository for automatic deployments on every push.

Note: The exported script embeds both the Hyperterse binary and your config as base64. Vercel’s serverless functions can execute this script directly. For production, consider extracting just the binary if you need faster cold starts.

Option 2: Frontend proxy to external Hyperterse

Deploy your frontend on Vercel and connect it to your Hyperterse API running elsewhere.

Deploy your frontend on Vercel and connect it to your Hyperterse API running elsewhere.

1. Deploy Hyperterse on a persistent platform

   First, deploy Hyperterse on a platform that supports persistent servers:

   • Railway — Simplest option
   • AWS — Production-grade
   • DigitalOcean — Good balance
   • Google Cloud — Enterprise-ready

   Make note of your Hyperterse API URL (e.g., https://hyperterse.railway.app).

2. Create or update your frontend

   If using Next.js, configure API rewrites to proxy requests to Hyperterse:

   next.config.js

   module.exports = {
     async rewrites() {
       return [
         {
           source: '/api/:path*',
           destination: 'https://hyperterse.railway.app/:path*',
         },
       ]
     },
   }

   This allows your frontend to call /api/query/get-user and it will be proxied to your Hyperterse server.

3. Use environment variables

   Store your Hyperterse URL in environment variables:

   # .env.local
   NEXT_PUBLIC_HYPERTERSE_URL=https://hyperterse.railway.app

   Then use it in your code:

   const response = await fetch(
     `${process.env.NEXT_PUBLIC_HYPERTERSE_URL}/query/get-user`,
     {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ email: 'user@example.com' }),
     },
   )

4. Deploy to Vercel

   • Push your code to GitHub
   • Go to vercel.com
   • Click “New Project”
   • Import your repository
   • Vercel will auto-detect Next.js and deploy

5. Configure environment variables

   In Vercel dashboard:

   • Go to your project → Settings → Environment Variables
   • Add NEXT_PUBLIC_HYPERTERSE_URL with your Hyperterse URL
   • Redeploy to apply changes

Option 3: Next.js API Routes

If you’re using Next.js, create API routes that proxy to Hyperterse:

1. Create API route

   pages/api/query/[queryName].js

   export default async function handler(req, res) {
     const { queryName } = req.query
     const hyperterseUrl = process.env.HYPERTERSE_URL
   
     try {
       const response = await fetch(`${hyperterseUrl}/query/${queryName}`, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
         },
         body: JSON.stringify(req.body),
       })
   
       const data = await response.json()
       res.status(response.status).json(data)
     } catch (error) {
       res.status(500).json({ error: error.message })
     }
   }

2. Set environment variable

   In Vercel dashboard, add HYPERTERSE_URL (without NEXT_PUBLIC_ prefix since it’s server-side only).

3. Use in your frontend

   const response = await fetch('/api/query/get-user', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ email: 'user@example.com' }),
   })

Environment variables

Manage environment variables in Vercel:

Via Dashboard:

• Go to your project → Settings → Environment Variables
• Add variables for each environment (Production, Preview, Development)
• Variables are encrypted and secure

Via Vercel CLI:

# Install Vercel CLI
npm i -g vercel

# Login
vercel login

# Link project
vercel link

# Add environment variable
vercel env add HYPERTERSE_URL production

# Pull environment variables locally
vercel env pull .env.local

Custom domain

Add your own domain to Vercel:

1. Add domain

   • Go to your project → Settings → Domains
   • Add your domain (e.g., api.example.com)

2. Configure DNS

   Vercel provides DNS instructions:

   • Add a CNAME record pointing to Vercel
   • Or add an A record with Vercel’s IP

3. SSL certificate

   Vercel automatically provisions and renews SSL certificates.