Environment Configuration

Configure MegaVault with environment variables for different deployment scenarios and security requirements.

Overview
Core Environment Variables
Storage Configuration
Storage Access Modes
Authentication Settings
Development Configuration
Production Configuration
Configuration Validation

Overview

MegaVault uses environment variables to configure authentication, storage, database connections, and other system settings. Proper configuration is essential for security and functionality.

💡

Environment Files

MegaVault supports multiple environment files:

.env - Default environment variables
.env.local - Local development overrides
.env.production - Production-specific settings
.env.docker - Docker deployment template

Development Setup

Quick configuration for local development

cp .env.example .env.local
# Edit .env.local with your settings

Production Setup

Secure configuration for production deployment

cp .env.docker .env
# Configure production values
# Use strong passwords and secrets

Core Environment Variables

These variables are required for basic MegaVault functionality and must be configured before starting the application.

Parameter	Type	Required	Description
`NODE_ENV`	string	Required	Application environment mode `production \| development \| test`
`NEXTAUTH_URL`	string	Required	Full URL where your application is hosted `https://yourdomain.com`
`NEXTAUTH_SECRET`	string	Required	Secret key for JWT token encryption (32+ characters) `your-super-secret-jwt-key-here-32-chars-min`
`USER_EMAIL`	string	Required	Admin user email for login `admin@yourdomain.com`
`USER_PASSWORD`	string	Required	Admin user password (minimum 8 characters) `SecurePassword123!`

⚠️

Security Notice

NEXTAUTH_SECRET must be a cryptographically secure random string of at least 32 characters. Never use predictable values or share this secret publicly.

Example Core Configuration

.env

NODE_ENV=production
NEXTAUTH_URL=https://vault.yourdomain.com
NEXTAUTH_SECRET=your-super-secure-secret-key-minimum-32-characters
USER_EMAIL=admin@yourdomain.com
USER_PASSWORD=SecureAdminPassword123!

Storage Configuration

MegaVault supports S3-compatible storage services. Cloudflare R2 is recommended for its performance and cost-effectiveness, but any S3-compatible service will work.

S3-Compatible Storage Variables

Parameter	Type	Required	Description
`S3_ENDPOINT`	string	Required	S3-compatible storage endpoint URL `https://your-account-id.r2.cloudflarestorage.com`
`S3_ACCESS_KEY_ID`	string	Required	S3-compatible access key for API authentication `AKIAIOSFODNN7EXAMPLE`
`S3_SECRET_ACCESS_KEY`	string	Required	S3-compatible secret key for API authentication `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`
`S3_BUCKET`	string	Required	Name of your storage bucket `megavault-storage`
`S3_REGION`	string	Optional	Storage region (usually auto for Cloudflare R2) `auto`

Setting Up Cloudflare R2 (Recommended)

Go to the Cloudflare Dashboard
Navigate to R2 Object Storage
Create a new bucket for MegaVault
Go to "Manage R2 API tokens" and create a new token
Grant the token "Object Read and Write" permissions
Copy the Access Key, Secret Key, and construct the endpoint URL

Complete Configuration Example

# ================================
# Storage Access Configuration
# ================================
# Choose between "bucket" (complete access) or "folder" (folder-specific access)
STORAGE_ACCESS_MODE=bucket
# USER_STORAGE_FOLDER=single-user-folder  # Only needed for folder mode

# ================================
# Storage Configuration (S3 Compatible)
# ================================
S3_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
S3_BUCKET=megavault-storage
S3_REGION=auto

Alternative S3 Services

You can also use other S3-compatible services:

AWS S3: Set region to your AWS region (e.g., us-east-1)
DigitalOcean Spaces: Use Spaces endpoint URL
MinIO: Self-hosted S3-compatible storage
Backblaze B2: Cost-effective cloud storage

Alternative Service Examples

# AWS S3 Configuration
S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
S3_ACCESS_KEY_ID=your-aws-access-key
S3_SECRET_ACCESS_KEY=your-aws-secret-key
S3_BUCKET=your-s3-bucket
S3_REGION=us-east-1

# MinIO Configuration
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_BUCKET=megavault
S3_REGION=us-east-1

Storage Access Modes

MegaVault supports configurable storage access modes to provide flexibility in how files are organized and accessed within your storage bucket. This feature allows you to choose between complete bucket access or isolated folder-based access.

Storage Access Variables

Parameter	Type	Required	Description
`STORAGE_ACCESS_MODE`	string	Optional	Controls storage access scope: "bucket" for complete access or "folder" for restricted access `bucket \| folder (default: folder)`
`USER_STORAGE_FOLDER`	string	Optional	Folder name for isolated storage when using folder mode `single-user-folder`

Bucket Mode

Complete access to the entire storage bucket

# Complete bucket access
STORAGE_ACCESS_MODE=bucket
# USER_STORAGE_FOLDER not needed

Files are stored directly at the bucket root level. Provides maximum flexibility and is ideal for single-tenant deployments.

Folder Mode

Restricted access to a specific folder

# Folder-restricted access
STORAGE_ACCESS_MODE=folder
USER_STORAGE_FOLDER=single-user-folder

Files are isolated within the specified folder. Provides better organization and security for multi-tenant scenarios.

Choosing the Right Mode

🪣 Bucket Mode (Recommended for Single User)

• Complete access to the entire storage bucket
• Files stored at bucket root level
• Maximum flexibility for file organization
• Ideal for personal or single-tenant deployments
• Easier migration from other storage systems

📁 Folder Mode (Recommended for Multi-User)

• Files isolated within specified folder
• Better organization and security
• Prevents accidental access to other data
• Ideal for shared storage buckets
• Easier backup and data management

💡

Default Configuration

If STORAGE_ACCESS_MODE is not specified, MegaVault defaults to folder modewith USER_STORAGE_FOLDER=single-user-folder. This provides a safe default that isolates your data within the bucket.

Storage Path Examples

File Organization Examples

# Bucket Mode - Files stored at bucket root
bucket-name/
├── document.pdf
├── photos/
│   └── vacation.jpg
└── projects/
    └── code.zip

# Folder Mode - Files stored within user folder
bucket-name/
└── single-user-folder/
    ├── document.pdf
    ├── photos/
    │   └── vacation.jpg
    └── projects/
        └── code.zip

Migration Between Modes

⚠️

Mode Migration

Changing storage modes requires moving existing files to match the new structure. Consider using cloud storage tools or scripts to migrate data when switching between modes.

Migration Example (AWS CLI)

# Moving from bucket mode to folder mode
aws s3 cp s3://your-bucket/ s3://your-bucket/single-user-folder/ --recursive

# Moving from folder mode to bucket mode
aws s3 cp s3://your-bucket/single-user-folder/ s3://your-bucket/ --recursive

Authentication Settings

Configure Redis for session storage and caching. MegaVault supports both Upstash Redis (cloud) and local Redis instances.

Redis Configuration Variables

Parameter	Type	Required	Description
`UPSTASH_REDIS_REST_URL`	string	Required	Upstash Redis REST API URL `https://your-redis-url.upstash.io`
`UPSTASH_REDIS_REST_TOKEN`	string	Required	Upstash Redis REST API token `your-redis-rest-token-here`
`REDIS_URL`	string	Optional	Alternative Redis connection URL for local Redis `redis://localhost:6379`

Upstash Redis Setup (Recommended)

Go to Upstash Console
Create a new Redis database
Choose a region close to your deployment
Copy the REST URL and Token from the database details

Redis Configuration

# Upstash Redis (Cloud - Recommended)
UPSTASH_REDIS_REST_URL=https://your-redis-url.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-redis-rest-token-here

# OR Local Redis (Development)
REDIS_URL=redis://localhost:6379

💡

Redis Usage

MegaVault uses Redis for:

User session storage
File upload progress tracking
Temporary data caching
API rate limiting

Development Configuration

Additional settings for development environments to enable debugging, hot reloading, and development tools.

.env.local (Development)

# Development mode
NODE_ENV=development
NEXTAUTH_URL=http://localhost:3000

# Development credentials (change these!)
USER_EMAIL=dev@localhost
USER_PASSWORD=dev123456

# Storage access mode for development
STORAGE_ACCESS_MODE=bucket  # Use bucket mode for easier development

# Enable development features
NEXT_PUBLIC_DEBUG=true
NEXT_PUBLIC_API_URL=http://localhost:3000/api

# Local Redis for development
REDIS_URL=redis://localhost:6379

# Development S3 settings (use test bucket)
S3_BUCKET=megavault-dev

⚠️

Development Security

Never use development credentials or settings in production. Always use strong, unique passwords and secrets for production deployments.

Production Configuration

Production environments require additional security measures and performance optimizations.

.env (Production)

# Production mode
NODE_ENV=production
NEXTAUTH_URL=https://vault.yourdomain.com

# Strong production credentials
USER_EMAIL=admin@yourdomain.com
USER_PASSWORD=StrongProductionPassword123!
NEXTAUTH_SECRET=your-cryptographically-secure-secret-key-minimum-32-characters

# Storage access configuration
STORAGE_ACCESS_MODE=folder  # Use folder mode for better organization
USER_STORAGE_FOLDER=production-vault

# Production Redis
UPSTASH_REDIS_REST_URL=https://your-production-redis.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-production-redis-token

# Production storage
S3_ENDPOINT=https://your-production-endpoint.com
S3_ACCESS_KEY_ID=your-production-access-key
S3_SECRET_ACCESS_KEY=your-production-secret-key
S3_BUCKET=megavault-production

# Performance optimizations
NEXT_PUBLIC_API_TIMEOUT=30000
NEXT_PUBLIC_MAX_FILE_SIZE=100000000

Production Security Checklist

✅ Use HTTPS with valid SSL certificates
✅ Generate secure random NEXTAUTH_SECRET
✅ Use strong, unique passwords
✅ Restrict file permissions on .env files
✅ Enable Redis authentication
✅ Configure proper CORS settings
✅ Set up monitoring and logging

Configuration Validation

Verify your configuration is correct before deploying MegaVault.

Environment Validation Script

# Check required environment variables
npm run validate-env

# Test Redis connection
npm run test-redis

# Test storage connection
npm run test-storage

Manual Validation

validate-config.js

// Basic environment validation
const requiredVars = [
  'NEXTAUTH_URL',
  'NEXTAUTH_SECRET',
  'USER_EMAIL',
  'USER_PASSWORD',
  'UPSTASH_REDIS_REST_URL',
  'UPSTASH_REDIS_REST_TOKEN',
  'S3_ENDPOINT',
  'S3_ACCESS_KEY_ID',
  'S3_SECRET_ACCESS_KEY',
  'S3_BUCKET'
];

// Optional storage access variables with defaults
const storageMode = process.env.STORAGE_ACCESS_MODE || 'folder';
const userFolder = process.env.USER_STORAGE_FOLDER || 'single-user-folder';

requiredVars.forEach(varName => {
  if (!process.env[varName]) {
    console.error(`Missing required environment variable: ${varName}`);
  }
});

// Validate storage access mode
if (!['bucket', 'folder'].includes(storageMode)) {
  console.error('STORAGE_ACCESS_MODE must be either "bucket" or "folder"');
}

// Warn if folder mode but no folder specified
if (storageMode === 'folder' && !process.env.USER_STORAGE_FOLDER) {
  console.warn('Using default folder "single-user-folder" for folder mode');
}

console.log(`Storage configured in ${storageMode} mode`);
if (storageMode === 'folder') {
  console.log(`Using folder: ${userFolder}`);
}

✅

Configuration Complete

Once all environment variables are properly configured, start MegaVault and verify the health endpoint responds correctly at /api/health.