Get started with self-hosting

Prerequisites

• A VPS or dedicated server running a modern Linux distribution (Ubuntu 24.04 recommended)
• At minimum 2 GB RAM; 4 GB or more is recommended for production workloads
• Docker and Node.js (the setup script installs them automatically if not present)

Helion has been validated on Ubuntu 24.04. The setup script is designed to work on most Debian-based distributions. If you already have Docker, Node.js, and pnpm installed, the setup step completes immediately.

A hosted option is available at helionlabs.dev if you prefer managed infrastructure.

Quickstart

git clone -b self-hosting https://github.com/Shrotriya-lalit/helionlabs && cd helionlabs/self-hosting && ./setup
# After setup is complete, run `./start` to launch all Helion services

git clone -b self-hosting https://github.com/Shrotriya-lalit/helionlabs.git

cd helionlabs/self-hosting
./setup

./start

Configuration

Always use the correct API URL

When self-hosting, you must supply your own API URL when initializing the SDK. Set apiUrl to https://<your-domain>/api.

<script>
  window.hl=window.hl||function(){var n=[];return new Proxy(function(){arguments.length&&n.push([].slice.call(arguments))},{get:function(t,r){return"q"===r?n:function(){n.push([r].concat([].slice.call(arguments)))}} ,has:function(t,r){return"q"===r}}) }();
  window.hl('init', {
    apiUrl: 'https://your-domain.com/api', 
    clientId: 'YOUR_CLIENT_ID',
    trackScreenViews: true,
    trackOutgoingLinks: true,
    trackAttributes: true,
  });
</script>
<script src="https://helionlabs.dev/hl1.js" defer async></script>

import { Helion } from '@helionlabs/sdk';

const hl = new Helion({
  apiUrl: 'https://your-domain.com/api', 
  clientId: 'YOUR_CLIENT_ID',
  trackScreenViews: true,
  trackOutgoingLinks: true,
  trackAttributes: true,
});

Email

Password resets and invitations require a configured email provider. Helion supports Resend and standard SMTP.

Features that require email:

• Password reset
• Team invitations

Option A — Resend

Create an account at resend.com, verify your sender domain, and configure the following in your .env file:

RESEND_API_KEY=re_xxxxxxxxxxxxx
EMAIL_SENDER=noreply@yourdomain.com

Option B — SMTP

To use a custom SMTP server, set SMTP_HOST and Helion will route email through it instead of Resend.

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=smtp-user@example.com
SMTP_PASS=your-smtp-password
EMAIL_SENDER=noreply@yourdomain.com

For a complete email configuration reference, see the Environment Variables documentation.

AI integration

Helion includes an AI-powered analytics assistant for data analysis, report generation, and natural-language queries. It supports OpenAI and Anthropic models simultaneously — configure one or both, and the model picker will only surface models whose provider key is present.

Supported models

• OpenAI — GPT-4.1, GPT-4.1 mini
• Anthropic — Claude Haiku 4.5, Claude Sonnet 4.6, Claude Opus 4.8

Configuration

Add one or both API keys to your .env file and restart the API service:

# OpenAI — obtain at platform.openai.com/api-keys
OPENAI_API_KEY=sk-your-openai-api-key-here

# Anthropic — obtain at console.anthropic.com
ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key-here

For complete AI configuration options, see the Environment Variables documentation.

Managed Redis

If you use a managed Redis service (e.g., Upstash, Redis Cloud), you may need to enable keyspace notifications manually:

redis-cli CONFIG SET notify-keyspace-events Ex

Helion uses expired-key events to track currently active visitors. Without this setting, the real-time visitor count will not function. A warning will appear in the API logs if this configuration is missing.

Registration and invitations

By default, registration is disabled after the first user account is created. To allow open registration:

ALLOW_REGISTRATION=true

Invitations are enabled by default. To disable them:

ALLOW_INVITATION=false

For a complete reference of all environment variables, see the Environment Variables documentation.

Utility scripts

All scripts must be run from within the self-hosting directory. Ensure they are executable (chmod +x <script-name> if needed).

Basic operations

./start    # Start all Helion services
./stop     # Stop all Helion services
./logs     # Stream real-time logs from all services

Maintenance

./rebuild <service-name>    # Rebuild and restart a specific service
                            # Example: ./rebuild hl-dashboard

Troubleshooting

./danger_wipe_everything    # Remove all containers, volumes, and data

Updating

To update to the latest Helion release, run the update script from the self-hosting directory:

./update