Root Path Configuration

Prerequisites

Before following this guide, you should:

1. Complete the Proxy Migration - Follow the Proxy Migration Guide to enable Helix proxy mode
2. Understand the environment variables - Be familiar with the .env configuration file

Overview

By default, Helix is configured to run under the /helix path. This allows it to coexist with the legacy Onify Hub application. However, if you want to run Helix as a standalone application at the root path, you need to update several environment variables.

Development Environment Setup

Step 1: Update Base URL Configuration

Locate the following variables in your .env or .env.local file and update them:

Before:

HELIX_BASE_URL="/helix"
HELIX_ERROR_URL="/helix/error"
HELIX_INTERNAL_LOGIN_PAGE="/helix/login/internal"

After:

HELIX_BASE_URL="/"
HELIX_ERROR_URL="/error"
HELIX_INTERNAL_LOGIN_PAGE="/login/internal"

Step 2: Update Helix Proxy Mode Configuration

If you're using the Helix proxy mode (as described in the Proxy Migration Guide), you also need to update the proxy-related environment variables to remove the /helix prefix.

Before:

# Uncomment the lines below (remove ##) when SSO login flow and proxy API requests should be handled by Helix instead of the legacy app
# This will override the values above since environment variables use the last defined value
HELIX_API_URL="/helix/api/v2"
HELIX_LOGIN_URL="/helix/login"
HELIX_LOGOUT_URL="/helix/logout"
ONIFY_HUB_API_PATH="/helix/api/v2"
VITE_LOCAL_API_PROXY_TARGET="http://localhost:8181/api/v2"
VITE_LOCAL_API_PROXY_ENDPOINT="/helix/api/v2"
VITE_SSO_CALLBACK_PROXY_ENDPOINT="/helix/sso/callback"

After:

# Uncomment the lines below (remove ##) when SSO login flow and proxy API requests should be handled by Helix instead of the legacy app
# This will override the values above since environment variables use the last defined value
HELIX_API_URL="/api/v2"
HELIX_LOGIN_URL="/login"
HELIX_LOGOUT_URL="/logout"
ONIFY_HUB_API_PATH="/api/v2"
VITE_LOCAL_API_PROXY_TARGET="http://localhost:8181/api/v2"
VITE_LOCAL_API_PROXY_ENDPOINT="/api/v2"
VITE_SSO_CALLBACK_PROXY_ENDPOINT="/sso/callback"

Step 3: Restart Development Server

After making these changes, restart your Vite dev server:

npm run dev

Step 4: Access Helix at Root Path

Your Helix application is now available at:

• Root path: http://localhost:5173/
• Login: http://localhost:5173/login (auto-redirect from root if not authenticated)
• Error page: http://localhost:5173/error

Production Deployment

For production deployments at the root path, you need to update the Dockerfile.proxy and nginx.proxy.conf files.

Update Dockerfile.proxy

Modify the environment variables in Dockerfile.proxy:

Before:

ENV HELIX_API_URL="/helix/api/v2"
ENV HELIX_LOGIN_URL="/helix/login"
ENV HELIX_LOGOUT_URL="/helix/logout"
ENV HELIX_ERROR_URL="/helix/error"
ENV HELIX_INTERNAL_LOGIN_PAGE="/helix/login/internal"
ENV HELIX_BASE_URL="/helix"
ENV ONIFY_HUB_API_PATH="/helix/api/v2"

After:

ENV HELIX_API_URL="/api/v2"
ENV HELIX_LOGIN_URL="/login"
ENV HELIX_LOGOUT_URL="/logout"
ENV HELIX_ERROR_URL="/error"
ENV HELIX_INTERNAL_LOGIN_PAGE="/login/internal"
ENV HELIX_BASE_URL="/"
ENV ONIFY_HUB_API_PATH="/api/v2"

Update nginx.proxy.conf

The proxy location blocks in nginx.proxy.conf use environment variables (like ${HELIX_LOGIN_URL}, ${ONIFY_HUB_API_PATH}, etc.), so they will automatically update when you change the environment variables in Dockerfile.proxy.

However, you need to manually update the static file location block:

Before:

location /helix/ {
    root /etc/nginx/html;
    try_files $uri $uri/ /helix/index.html;
}

After:

location / {
    root /etc/nginx/html;
    try_files $uri $uri/ /index.html /helix/index.html;
}

What Changed?

URL Path Changes

Related Documentation

• Proxy Migration Guide - Complete guide for enabling Helix proxy mode (prerequisite)
• Helix App README - Main documentation for the Helix application

Summary

This guide showed you how to configure Helix to run at the root path (/) instead of the default /helix subpath. The key changes are:

1. Update base URL environment variables to use root paths
2. Remove /helix prefix from all proxy mode configuration
3. Update production Docker and nginx configuration
4. Restart/rebuild and test

After these changes, you can access Helix directly at http://localhost:5173/ in development and http://your-domain.com/ in production.