Skip to main content

​
Environment configuration

Basedash requires several environment variables to be configured before deployment. The fastest way to get started is using our environment file generator.

​
Quick start: Generate environment file

Visit https://proud-dog-65.deno.dev/ to generate a ready-to-use .env file with securely generated secrets.
  • Fresh secrets every time: Refresh the page to generate a new set of random values
  • Copy and customize: Download the file and customize it for your deployment
  • Secure by default: All encryption keys, secrets, and passwords are randomly generated

​
Required core variables

These variables must be set for Basedash to function: Database connection: 
DATABASE_URL=postgresql://basedash:password@postgres:5432/basedash_charts
Encryption keys: 
# Used for encrypting configuration overrides (must be exactly 32 bytes/64 hex chars)
CRYPTO_KEY=your_crypto_key_here

# Used for encrypting sensitive database fields
# Format: k1.aesgcm256.[base64-string]
# Generate with: npx @47ng/cloak generate
PRISMA_FIELD_ENCRYPTION_KEY=your_prisma_encryption_key_here

​
Optional configuration

Application settings: 
# Base URL for your deployment (highly recommended for production)
BASE_URL=https://your-domain.com

# Log level (fatal, error, warn, info, debug, trace)
LOG_LEVEL=warn

# Application port
APP_PORT=3000
Why BASE_URL matters: Setting BASE_URL is highly recommended for production deployments as it’s used for:
  • Email links - Ensures invitation emails, password resets, and notifications contain the correct URL to access your Basedash instance
  • OAuth callbacks - Required for SSO and third-party integrations to redirect users back to your deployment
  • Shared dashboard links - Generated share links will use this URL so recipients can access dashboards
  • Webhooks and API callbacks - External services need the correct URL to communicate with your instance
  • CORS configuration - Helps ensure proper cross-origin request handling
Examples:
  • https://basedash.your-company.com - Production deployment with custom domain
  • https://analytics.acme.io - Custom branded URL
  • http://localhost:3000 - Local development only (not recommended for production)

​
PostgreSQL database

PostgreSQL is the only database dependency required by Basedash.

​
Automatic PostgreSQL setup

When using Agent deployment or our provided docker-compose file, PostgreSQL is automatically included and configured:
  • PostgreSQL 16 Alpine container is deployed alongside Basedash
  • Automatic migrations run on startup
  • Health checks ensure the database is ready before the app starts
  • Persistent storage via Docker volumes

​
PostgreSQL configuration

The following environment variables configure the PostgreSQL instance: 
POSTGRES_DB=basedash_charts
POSTGRES_USER=basedash
POSTGRES_PASSWORD=your_secure_password_here
POSTGRES_PORT=5432

​
Using an external PostgreSQL instance

If you prefer to use an existing PostgreSQL instance instead of the bundled one:
  1. Point DATABASE_URL to your external instance: 
    DATABASE_URL=postgresql://user:password@your-postgres-host:5432/dbname
  2. Ensure your PostgreSQL version is 16 or higher
  3. Create the database: 
    CREATE DATABASE basedash_charts;
  4. Migrations will run automatically on first startup

​
Database backups

For production deployments, we recommend regular backups: 
# Create backup
docker compose exec postgres pg_dump -U basedash basedash_charts > backup.sql

# Restore backup
docker compose exec -T postgres psql -U basedash basedash_charts < backup.sql

​
AI configuration

Basedash’s AI features require an AI provider. You can use OpenAI, Azure OpenAI, or other OpenAI-compatible providers.

​
OpenAI (default)

To use OpenAI’s API: 
# Provider selection (optional - defaults to OpenAI)
AI_PROVIDER=default

# OpenAI API key (required for AI features)
OPENAI_API_KEY=sk-your-openai-api-key

# Optional: Organization and project IDs
OPENAI_ORGANIZATION_ID=org-your-org-id
OPENAI_PROJECT_ID=proj_your-project-id

# Optional: Custom model
OPENAI_MODEL=gpt-4o

# Optional: Custom base URL for OpenAI-compatible APIs
OPENAI_BASE_URL=https://api.openai.com/v1

​
Azure OpenAI

To use Azure OpenAI Service: 
AI_PROVIDER=azure-openai

AZURE_OPENAI_API_KEY=your-azure-api-key
AZURE_OPENAI_RESOURCE_NAME=your-resource-name
AZURE_OPENAI_API_VERSION=2024-02-15-preview
AZURE_OPENAI_BASE_URL=https://your-resource-name.openai.azure.com
AZURE_OPENAI_DEPLOYMENT_NAME=o3-mini

​
Alternative AI providers

Any OpenAI-compatible API can be used by setting a custom OPENAI_BASE_URL: 
# Example: Using a local LLM server
OPENAI_BASE_URL=http://localhost:8080/v1
OPENAI_API_KEY=your-api-key

​
AI feature considerations

When using custom AI models or providers:
  • SQL generation quality may vary from our tested models
  • Performance benchmarks are maintained for default OpenAI models only
  • New features may require specific model capabilities
  • Token limits and pricing vary by provider

​
Email configuration

Email is used for notifications, alerts, and user invitations. Basedash supports SMTP for outbound email.

​
SMTP configuration

Configure your SMTP server: 
EMAIL_PROVIDER=smtp

SMTP_HOST=smtp.your-provider.com
SMTP_PORT=587
SMTP_USER=your-smtp-username
SMTP_PASSWORD=your-smtp-password
SMTP_TLS=true
SMTP_FROM_EMAIL=[email protected]
Common SMTP providers:
  • Resend: smtp.resend.com:587
  • SendGrid: smtp.sendgrid.net:587
  • Mailgun: smtp.mailgun.org:587
  • AWS SES: email-smtp.us-east-1.amazonaws.com:587
  • Gmail: smtp.gmail.com:587 (requires app password)

​
Amazon SES configuration

Configure Amazon Simple Email Service (SES) directly: 
EMAIL_PROVIDER=ses

SES_ACCESS_KEY_ID=your-access-key-id
SES_SECRET_ACCESS_KEY=your-secret-access-key
SES_REGION=us-east-2
SES_FROM_EMAIL=[email protected]
Ensure your SES account is out of sandbox mode for production use, and that the SES_FROM_EMAIL address is verified in your SES configuration.

​
Email features

With email configured, users can:
  • Receive dashboard sharing invitations
  • Get alert notifications
  • Access password reset functionality
  • Receive scheduled report deliveries

​
Authentication and access control

  • SSO integration - Connect to your existing identity providers (see our SSO documentation for details)
  • Custom auth providers - We can add support for specific providers as needed
  • Multi-organization support - Deploy multiple workspaces or organizations
  • Granular permissions - Maintain the same access control features as cloud

​
Disable public signups

For private deployments where you want to restrict who can create accounts, you can disable public signups: 
DISABLE_PUBLIC_SIGNUPS=true
When enabled, this blocks manual signup while still allowing:
  • First user signup - Automatically allowed to bootstrap the instance
  • User invitations - Team members can still be invited via magic links
  • JWT SSO - Embedded authentication continues to work
  • Enterprise SSO - SAML/OIDC authentication is unaffected
  • Existing users - Login for users who already have accounts
This is useful when you want to control exactly who has access to your Basedash instance and prevent unauthorized users from creating new organizations.

​
License key

Self-hosted Basedash instances require a license key for proper operation. The license key enables license validation, usage tracking, and ensures you receive ongoing support and updates.

​
Obtaining a license key

Contact Basedash at [email protected] to obtain your license key. Once you have it, add it to your environment configuration: 
LICENSE_KEY=your-license-key-here

​
License behavior

Without a license key:
  • The application functions normally
  • An info banner is displayed prompting you to add a license key
  • No heartbeats are sent to the license server
With a valid license key:
  • The application sends periodic heartbeats (every 6 hours) to the Basedash license server
  • Heartbeats report basic usage metrics (organization and user counts) for billing purposes
  • No banner is displayed when your license is active and valid

​
Grace periods

Basedash includes grace periods to ensure your deployment remains operational during temporary issues:
  • License expiration: 14-day grace period after expiration. During this time, a warning banner is displayed but all features remain available. After the grace period, new organization creation is disabled.
  • Network issues: 7-day grace period if the license server cannot be reached. This ensures your deployment continues working during network outages or maintenance windows.

​
Troubleshooting license issues

“License key not configured” banner: Add your LICENSE_KEY to your environment configuration and restart the application. “Unable to verify license” warning:
  1. Check that your deployment has outbound network access to charts.basedash.com
  2. Verify no firewall rules are blocking HTTPS traffic
  3. The application will continue working during network issues (7-day grace period)
“License has expired” error: Contact Basedash at [email protected] to renew your license. During the 14-day grace period, all features remain available. After the grace period, new organization creation is disabled until you renew. “License has been deactivated” error: Your license has been manually deactivated. Contact Basedash support to resolve this issue.

​
Update management

​
Agent deployment updates

With Agent deployment, updates are managed through the Distr customer portal:
  • Automatic updates - Enable automatic updates for the latest features and fixes
  • Version pinning - Lock to a specific version for stability and testing
  • Update scheduling - Control when updates are applied
  • Rollback support - Revert to previous versions if needed

​
Container deployment updates

When using container deployment, you control the update process:
  1. Check for new versions in the Distr customer portal
  2. Pull the new image from the registry: 
    docker compose pull
  3. Restart services to apply the update: 
    docker compose up -d
  4. Verify deployment health after updating

​
Version locking for compliance

For organizations with strict change control:
  • Lock to specific versions for training periods or audits
  • Test updates in a staging environment before production
  • Coordinate updates with your internal release schedule

​
Advanced configuration

​
Storage (optional)

For avatar and icon uploads, configure S3-compatible storage: 
S3_BUCKET_NAME=your-bucket-name
S3_BUCKET_ACCESS_KEY_ID=your-access-key
S3_BUCKET_SECRET_ACCESS_KEY=your-secret-key
S3_BUCKET_REGION=us-east-1
S3_BUCKET_ENDPOINT=https://s3.amazonaws.com
Compatible with AWS S3, DigitalOcean Spaces, Google Cloud and other S3-compatible services. By default, the public CDN URL for uploaded files is constructed as https://{S3_BUCKET_NAME}.{S3_BUCKET_ENDPOINT_HOST}. If your CDN uses a different URL pattern (e.g., a custom domain or path-style URLs), set the CDN base URL explicitly: 
S3_CDN_BASE_URL=https://cdn.example.com
Follow these steps to configure Google Cloud Storage (GCS) as your S3-compatible storage backend.

​
Step 1: Create a Google Cloud Storage Bucket

  1. Go to the Google Cloud Console
  2. Navigate to Cloud Storage → Buckets
  3. Click Create bucket
  4. Configure the bucket:
    • Name: Choose a globally unique name (e.g., basedash-uploads-yourcompany)
    • Location type: Choose based on your needs (Regional is typically fine)
    • Region: Select a region close to your users
    • Storage class: Standard
    • Access control: Choose Fine-grained (required for ACL-based public-read access)
    • Public access prevention: Uncheck “Enforce public access prevention on this bucket” (since Basedash uploads files with public-read ACL)
  5. Click Create

​
Step 2: Configure Bucket Permissions

  1. Go to your bucket → Permissions tab
  2. Click Grant Access
  3. Add allUsers as a principal with the role Storage Object Viewer (this allows public read access to uploaded files)

​
Step 3: Enable Interoperability (S3-Compatible Access)

  1. Go to Cloud Storage → Settings (gear icon in the left sidebar)
  2. Click the Interoperability tab
  3. Under “Access keys for service accounts,” click Create a key for a service account
  4. Select or create a service account with Storage Admin permissions for your bucket
  5. Click Create key
  6. Save both values:
    • Access key (this is your S3_BUCKET_ACCESS_KEY_ID)
    • Secret (this is your S3_BUCKET_SECRET_ACCESS_KEY)

​
Step 4: Configure CORS

Since Basedash uploads files directly from the browser using pre-signed URLs, you need to configure CORS. Create a file called cors.json:
[
  {
    "origin": ["https://your-basedash-domain.com", "http://localhost:3000"],
    "method": ["GET", "PUT", "HEAD"],
    "responseHeader": ["Content-Type", "Content-Length", "x-amz-acl"],
    "maxAgeSeconds": 3600
  }
]
Apply the CORS configuration using the gcloud CLI:
gcloud storage buckets update gs://YOUR_BUCKET_NAME --cors-file=cors.json
Or via the Console:
  1. Install Google Cloud SDK if not already installed
  2. Run the command above

​
Step 5: Set Environment Variables

Add these environment variables to your Basedash deployment:
# Required
S3_BUCKET_NAME=your-bucket-name
S3_BUCKET_ENDPOINT=https://storage.googleapis.com
S3_BUCKET_REGION=auto
S3_BUCKET_ACCESS_KEY_ID=GOOG1E...  # Your interoperability access key
S3_BUCKET_SECRET_ACCESS_KEY=...    # Your interoperability secret

# Optional - CDN URL for serving files
# S3_CDN_BASE_URL=https://your-cdn-domain.com
Note about the CDN URL: If you don’t set up a CDN, Basedash will automatically construct the public URL using S3_BUCKET_NAME and S3_BUCKET_ENDPOINT. Only set S3_CDN_BASE_URL if you have configured a CDN (like Google Cloud CDN) to serve files from your bucket.

​
Step 6: Verify the Setup

After deploying with the new environment variables:
  1. Try uploading a user avatar or organization icon
  2. Check that the file appears in your GCS bucket
  3. Verify the public URL works by accessing it directly

​
Summary of Environment Variables

VariableValueDescription
S3_BUCKET_NAMEyour-bucket-nameThe GCS bucket name
S3_BUCKET_ENDPOINThttps://storage.googleapis.comGCS S3-compatible endpoint
S3_BUCKET_REGIONautoCan be auto or your bucket’s region
S3_BUCKET_ACCESS_KEY_IDYour HMAC access keyFrom Interoperability settings
S3_BUCKET_SECRET_ACCESS_KEYYour HMAC secretFrom Interoperability settings
S3_CDN_BASE_URLhttps://your-cdn-domain.com(Optional) Only set if using a CDN

​
Slack integration (optional) - ALPHA

Note: Slack integration is currently in alpha and not fully supported for self-hosted deployments.
Enable Slack notifications and alerts: 
SLACK_CLIENT_ID=your-slack-client-id
SLACK_CLIENT_SECRET=your-slack-client-secret
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_BOT_TOKEN=xoxb-your-bot-token

​
Logging

Control application verbosity: 
# Minimal logging (default) - warnings and errors only
LOG_LEVEL=warn

# Standard production - includes informational messages
LOG_LEVEL=info

# Debugging - detailed diagnostic information
LOG_LEVEL=debug

# Maximum verbosity - trace-level details
LOG_LEVEL=trace
Log levels: fatal, error, warn, info, debug, trace

​
Support and troubleshooting

​
Getting help

  • Distr customer portal - Monitor deployment health and access support resources
  • Email support - Reach out to [email protected] for configuration assistance
  • Documentation - Refer to deployment-specific guides in the portal

​
Health monitoring

Check application health: 
# Application health endpoint
curl http://localhost:3000/health

# Database connectivity
docker compose exec postgres pg_isready -U basedash

# View application logs
docker compose logs -f app

# View database logs
docker compose logs -f postgres

​
Common configuration issues

Application won’t start:
  1. Verify all required environment variables are set
  2. Check DATABASE_URL format and accessibility
  3. Ensure CRYPTO_KEY is exactly 64 hex characters
  4. Review logs: docker compose logs app
AI features not working:
  1. Verify OPENAI_API_KEY is set correctly
  2. Check API key has sufficient credits/quota
  3. Test connectivity to AI provider endpoint
Email delivery failing:
  1. Verify SMTP credentials and host
  2. Check SMTP_PORT matches your provider (usually 587 or 465)
  3. Ensure firewall allows outbound connections on SMTP port
  4. Test with a simple SMTP client to verify credentials