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

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

​
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

​
Running without AI features

While AI features enhance the experience, Basedash can run without them. Simply omit the AI configuration variables, and AI-powered features will be disabled.

​
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=noreply@your-domain.com
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)

​
Email features

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

​
Running without email

Email configuration is optional. Without it:
  • Users can still be added directly in the application
  • Sharing and collaboration features remain available
  • Alerts can be configured for other channels (e.g., Slack)

​
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

​
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, Backblaze B2, MinIO, and other S3-compatible services.

​
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 support@basedash.com 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