Environment Variables

Overview

Nexus Access Vault uses environment variables for configuration. All variables are defined in the .env file at the root of your project. Copy .env.example to .env and configure the values for your deployment.

cp .env.example .env

Variable Categories

Supabase

Database and authentication backend

Zitadel

OIDC authentication provider

Network

Network access and isolation

Supabase Configuration

These variables configure the connection to your Supabase backend.

VITE_SUPABASE_PROJECT_ID

string

required

Your Supabase project ID. Find this in your Supabase project settings.Example:

VITE_SUPABASE_PROJECT_ID="vbuwctubivhffkvhqwpp"

The project ID is visible in your Supabase project URL: https://app.supabase.com/project/[PROJECT_ID]

VITE_SUPABASE_PUBLISHABLE_KEY

string

required

Your Supabase anon/public API key. This key is safe to use in a browser.Example:

VITE_SUPABASE_PUBLISHABLE_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Find this in your Supabase project settings under API → Project API keys → anon public

VITE_SUPABASE_URL

string

required

The full URL to your Supabase project API endpoint.Example:

VITE_SUPABASE_URL="https://vbuwctubivhffkvhqwpp.supabase.co"

Find this in your Supabase project settings under API → Project URL

Zitadel OIDC Configuration

These variables configure authentication using Zitadel as the OIDC provider.

Before configuring these variables, you must create an OIDC application in your Zitadel instance. See Zitadel OIDC Setup for detailed instructions.

VITE_ZITADEL_ISSUER_URL

string

required

The base URL of your Zitadel instance. This is used for OIDC discovery.Example:

VITE_ZITADEL_ISSUER_URL="https://manager.kappa4.com"

The issuer URL must be accessible from both the server and client browsers. Do not include trailing slashes.

VITE_ZITADEL_CLIENT_ID

string

required

The client ID of your OIDC application in Zitadel.Example:

VITE_ZITADEL_CLIENT_ID="123456789@nexus-vault"

This is generated when you create an OIDC application in Zitadel. Find it in your Zitadel project under the application settings.

VITE_ZITADEL_REDIRECT_URI

string

required

The redirect URI where users will be sent after authentication. This must match the redirect URI configured in your Zitadel application.Examples:Development:

VITE_ZITADEL_REDIRECT_URI="http://localhost:8080/auth/callback"

Production (VPN):

VITE_ZITADEL_REDIRECT_URI="http://100.64.1.10:8080/auth/callback"

Production (Domain):

VITE_ZITADEL_REDIRECT_URI="https://vault.internal.company.com/auth/callback"

The redirect URI must be added to the allowed redirect URIs in your Zitadel application configuration. Mismatched URIs will cause authentication to fail.

Network Configuration

These variables control network access and isolation for your deployment.

VITE_NETWORK_MODE

string

default:"internal"

Controls the network access mode for the application.Values:

internal: Restricts access to internal network only (VPN required)
public: Allows public internet access

Example:

VITE_NETWORK_MODE="internal"

When set to internal, the application will enforce VPN-only access. Users must be connected to your Netbird network or VPN to access the portal.

VITE_INTERNAL_HOST

string

required

The internal IP address or DNS name where the application is accessible on your VPN network.Examples:Using Netbird IP:

VITE_INTERNAL_HOST="100.64.1.10"

Using internal DNS:

VITE_INTERNAL_HOST="vault.internal.company.com"

This should be the IP or hostname assigned by your VPN solution (Netbird, Tailscale, WireGuard, etc.)

Complete Configuration Example

Here’s a complete example .env file with all variables configured:

.env

# Supabase Configuration
VITE_SUPABASE_PROJECT_ID="vbuwctubivhffkvhqwpp"
VITE_SUPABASE_PUBLISHABLE_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InZidXdjdHViaXZoZmZrdmhxd3BwIiwicm9sZSI6ImFub24iLCJpYXQiOjE2OTk1NTU1NTUsImV4cCI6MjAxNTEzMTU1NX0.example"
VITE_SUPABASE_URL="https://vbuwctubivhffkvhqwpp.supabase.co"

# Zitadel OIDC Configuration
VITE_ZITADEL_ISSUER_URL="https://manager.kappa4.com"
VITE_ZITADEL_CLIENT_ID="123456789@nexus-vault"
VITE_ZITADEL_REDIRECT_URI="http://100.64.1.10:8080/auth/callback"

# Network Configuration
VITE_NETWORK_MODE="internal"
VITE_INTERNAL_HOST="100.64.1.10"

Environment-Specific Configurations

Development Environment

.env.development

# Supabase - use your dev project
VITE_SUPABASE_PROJECT_ID="dev-project-id"
VITE_SUPABASE_PUBLISHABLE_KEY="dev-anon-key"
VITE_SUPABASE_URL="https://dev-project.supabase.co"

# Zitadel - use localhost redirect
VITE_ZITADEL_ISSUER_URL="https://manager.kappa4.com"
VITE_ZITADEL_CLIENT_ID="dev-client-id"
VITE_ZITADEL_REDIRECT_URI="http://localhost:8080/auth/callback"

# Network - public access for development
VITE_NETWORK_MODE="public"
VITE_INTERNAL_HOST="localhost"

Production Environment

.env.production

# Supabase - use your production project
VITE_SUPABASE_PROJECT_ID="prod-project-id"
VITE_SUPABASE_PUBLISHABLE_KEY="prod-anon-key"
VITE_SUPABASE_URL="https://prod-project.supabase.co"

# Zitadel - use VPN IP redirect
VITE_ZITADEL_ISSUER_URL="https://manager.kappa4.com"
VITE_ZITADEL_CLIENT_ID="prod-client-id"
VITE_ZITADEL_REDIRECT_URI="http://100.64.1.10:8080/auth/callback"

# Network - internal only for production
VITE_NETWORK_MODE="internal"
VITE_INTERNAL_HOST="100.64.1.10"

Validation

You can validate your environment configuration by running the development server:

npm run dev

The application will fail to start if required variables are missing or invalid.

Never commit .env files to version control! Always use .env.example as a template and add .env to your .gitignore file.

Build-Time vs Runtime

All environment variables prefixed with VITE_ are embedded into the application at build time. This means:

Important: If you change any VITE_* variable, you must rebuild the application:

npm run build

Security Considerations

Sensitive Variables

The following variables contain sensitive information:

VITE_SUPABASE_PUBLISHABLE_KEY (safe to expose in browser)
Zitadel client secrets (if using confidential clients)

Never commit these values to version control. Use .env.example with placeholder values instead.

VITE_ Prefix Exposure

All variables prefixed with VITE_ are exposed in the browser bundle. This is intentional and safe for:

Public API keys (like Supabase anon key)
OIDC configuration (client ID, issuer URL)
Network configuration

Never use VITE_ prefix for truly secret values like service account tokens or private keys.

Redirect URI Security

The redirect URI must be an exact match in Zitadel. This prevents authorization code interception attacks.Always use:

https:// in production (except for internal VPN addresses)
Exact protocol, host, port, and path matches
No wildcards in redirect URIs

Troubleshooting

Variables not taking effect

If your environment variables aren’t being applied:

Ensure you’ve created .env file (not just .env.example)
Rebuild the application: npm run build
Restart the development server: npm run dev
Check that variables are prefixed with VITE_
Verify no syntax errors in .env file

Supabase connection fails

If you can’t connect to Supabase:

Verify project ID matches your Supabase project
Check that the anon key hasn’t been rotated
Ensure the URL includes https:// and .supabase.co
Test the URL in your browser to verify it’s accessible
Check Supabase project status in the dashboard

Zitadel authentication fails

If authentication with Zitadel doesn’t work:

Verify issuer URL is accessible from your browser
Check that client ID exactly matches Zitadel application
Ensure redirect URI is added to allowed URIs in Zitadel
Verify redirect URI matches exactly (protocol, host, port, path)
Check browser console for OIDC error messages

Network mode not working

If network isolation isn’t working:

Verify VITE_NETWORK_MODE is set to internal
Check that VITE_INTERNAL_HOST matches your VPN IP
Ensure you’re connected to the VPN: netbird status
Rebuild the application after changing variables
Test access from both inside and outside VPN

Next Steps

Database Setup

Configure and migrate your Supabase database

Network Configuration

Set up VPN-only access with Netbird

Zitadel OIDC

Configure Zitadel authentication

Self-Hosted Deployment

Complete deployment guide

Overview

Getting Started

Authentication & SSO

Core Features

Network & Infrastructure

Administration

Deployment

Overview

Variable Categories

Supabase

Zitadel

Network

Supabase Configuration

VITE_SUPABASE_PROJECT_ID

VITE_SUPABASE_PUBLISHABLE_KEY

VITE_SUPABASE_URL

Zitadel OIDC Configuration

VITE_ZITADEL_ISSUER_URL

VITE_ZITADEL_CLIENT_ID

VITE_ZITADEL_REDIRECT_URI

Network Configuration

VITE_NETWORK_MODE

VITE_INTERNAL_HOST

Complete Configuration Example

Environment-Specific Configurations

Development Environment

Production Environment

Validation

Build-Time vs Runtime

Security Considerations

Troubleshooting

Next Steps

Database Setup

Network Configuration

Zitadel OIDC

Self-Hosted Deployment

Build docs developers (and LLMs) love

Overview

Getting Started

Authentication & SSO

Core Features

Network & Infrastructure

Administration

Deployment

​Overview

​Variable Categories

Supabase

Zitadel

Network

​Supabase Configuration

​VITE_SUPABASE_PROJECT_ID

​VITE_SUPABASE_PUBLISHABLE_KEY

​VITE_SUPABASE_URL

​Zitadel OIDC Configuration

​VITE_ZITADEL_ISSUER_URL

​VITE_ZITADEL_CLIENT_ID

​VITE_ZITADEL_REDIRECT_URI

​Network Configuration

​VITE_NETWORK_MODE

​VITE_INTERNAL_HOST

​Complete Configuration Example

​Environment-Specific Configurations

​Development Environment

​Production Environment

​Validation

​Build-Time vs Runtime

​Security Considerations

​Troubleshooting

​Next Steps

Database Setup

Network Configuration

Zitadel OIDC

Self-Hosted Deployment

Build docs developers (and LLMs) love

Overview

Variable Categories

Supabase Configuration

VITE_SUPABASE_PROJECT_ID

VITE_SUPABASE_PUBLISHABLE_KEY

VITE_SUPABASE_URL

Zitadel OIDC Configuration

VITE_ZITADEL_ISSUER_URL

VITE_ZITADEL_CLIENT_ID

VITE_ZITADEL_REDIRECT_URI

Network Configuration

VITE_NETWORK_MODE

VITE_INTERNAL_HOST

Complete Configuration Example

Environment-Specific Configurations

Development Environment

Production Environment

Validation

Build-Time vs Runtime

Security Considerations

Troubleshooting

Next Steps