Deploy with Docker Compose

This guide covers deploying Helion with Docker Compose on a VPS or dedicated server. Docker Compose provides full infrastructure control, making it the recommended approach for self-hosted production deployments.

Prerequisites

A VPS or server (Docker and Node will be installed automatically if needed)
At least 2GB RAM (4GB+ recommended)
Domain name pointing to your server (optional but recommended)
Basic knowledge of command line

The setup script installs Docker and Node.js automatically if they are not already present on the target system.

Quick Start

Clone the Repository

Clone the Helion repository and navigate to the self-hosting directory:

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

Run the Setup Script

The setup script handles initial configuration through an interactive wizard. It will:

Install Node.js (if not present and you consent)
Install Docker (if not present and you consent)
Launch an interactive configuration wizard

Setup typically completes in 30 seconds to 2 minutes depending on server speed.

./setup

The wizard prompts for:

Domain name
Database credentials
Email provider (optional)
AI integration keys (optional)
Registration policy

If ./setup fails to execute, run the following steps manually:

Install Docker
Install Node.js and npm
Run npm run quiz from inside the self-hosting directory

Start the Services

After the setup is complete, start all Helion services:

./start

This starts all required services:

Container	Role
`hl-db`	PostgreSQL — primary relational database
`hl-kv`	Redis — caching and real-time pub/sub
`hl-ch`	ClickHouse — analytics event store
`hl-api`	Helion API server
`hl-dashboard`	Helion dashboard frontend
`hl-worker`	Background worker for event processing

Verify Installation

Check that all containers are running:

docker compose ps

All services should show as "healthy" or "running". You can also check the logs:

docker compose logs -f

Or use the provided logs script:

./logs

Once all services are healthy, you can access Helion at your configured domain (or http://your-server-ip if you haven't configured a domain).

Configuration

Environment Variables

The setup wizard will configure most environment variables automatically. You can manually edit the .env file in the self-hosting directory if needed.

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

If you change the .env file, you need to restart the services for the changes to take effect. Use ./stop and ./start or docker compose restart.

Using Custom Docker Images

If you want to use specific image versions, edit the docker-compose.yml file and update the image tags:

hl-api:
  image: ghcr.io/shrotriya-lalit/api:2.0.0  # Specify version

Scaling Workers

To scale the worker service, set the HL_WORKER_REPLICAS environment variable:

HL_WORKER_REPLICAS=3 docker compose up -d

Or edit the docker-compose.yml file:

hl-worker:
  deploy:
    replicas: 3

Managing Your Deployment

Helion comes with several utility scripts to help manage your deployment. All scripts should be run from within the self-hosting directory.

Basic Operations

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

View Logs

View logs from all services:

./logs

Or using Docker Compose directly:

docker compose logs -f

View logs from a specific service:

docker compose logs -f hl-api

Stop Services

Stop all services:

./stop

Or using Docker Compose:

docker compose down

Stop services but keep volumes (data persists):

docker compose stop

Restart Services

Restart all services:

./stop && ./start

Or using Docker Compose:

docker compose restart

Restart a specific service:

docker compose restart hl-api

Rebuild Services

Rebuild and restart a specific service:

./rebuild hl-dashboard

Update Helion

To update to the latest version, use the update script:

./update

This script will:

Pull the latest changes from the repository
Pull the latest Docker images
Restart all services

If you don't have the ./update script, you can manually update:

git pull
docker compose pull
docker compose up -d

Always backup your data before updating. The database migrations will run automatically when the API container starts. Also read any changes in the changelog and apply them to your instance.

Backup and Restore

Backup

Backup your PostgreSQL database:

docker compose exec hl-db pg_dump -U postgres postgres > backup.sql

Backup volumes:

docker run --rm -v helion_hl-db-data:/data -v $(pwd):/backup alpine tar czf /backup/db-backup.tar.gz /data

Restore

Restore PostgreSQL database:

docker compose exec -T hl-db psql -U postgres postgres < backup.sql

Troubleshooting

Services Won't Start

Check Docker and Docker Compose versions:
```
docker --version
docker compose version
```
Check available disk space:
```
df -h
```
Check logs for errors:
```
docker compose logs
```

Database Connection Issues

If services can't connect to the database:

Verify the database is healthy:
```
docker compose ps hl-db
```
Check database logs:
```
docker compose logs hl-db
```
Verify DATABASE_URL in your .env file references the correct service hostname (hl-db within the Docker Compose network)

Port Conflicts

If ports 80 or 443 are already in use, you can:

Change the ports in docker-compose.yml:
```
ports:
  - "8080:80"
  - "8443:443"
```
Or stop the conflicting service

Health Check Failures

If health checks are failing:

Check if services are actually running:
```
docker compose ps
```

Increase health check timeout in docker-compose.yml:

healthcheck:
  interval: 30s
  timeout: 10s
  retries: 10

Using Your Own Reverse Proxy

If you want to use NGINX, Traefik, or another reverse proxy instead of the bundled Caddy — or put a TLS terminator upstream of Caddy — see the dedicated Reverse proxy setup guide. It covers the working NGINX config, the Connection: upgrade SSR-break gotcha, and the WebSocket upgrade headers required for the Realtime view.

Next Steps

Configure email settings for password resets and invitations
Set up AI integration for the analytics assistant
Configure SDK to track events from your applications

Deploy with Docker Compose

On this page