Configure - Basedash Documentation

Environment configuration

Basedash requires several environment variables to be configured before deployment. Generate secrets locally with the commands below, then copy them into your .env or Helm values.

Quick start: generate secrets

# CRYPTO_KEY — 32 bytes
openssl rand -hex 16

# PRISMA_FIELD_ENCRYPTION_KEY
npx @47ng/cloak generate

# POSTGRES_PASSWORD — use hex, not base64. Characters like +, /, and = break DATABASE_URL.
openssl rand -hex 24

Required core variables

These variables must be set for Basedash to function: Public URL: BASE_URL must be a full URL including http:// or https://. A hostname alone (basedash.example.com) will fail at login redirect.

# Direct to the app on the default port (plain HTTP)
BASE_URL=http://basedash.example.com:3000

# HTTPS on 443 (Caddy, nginx, Cloudflare, or another reverse proxy)
BASE_URL=https://basedash.example.com

License: Production self-hosted will not start without a valid key. Contact support@basedash.com if you do not have one.

LICENSE_KEY=your-license-key-here

App image (Compose only): Distr Compose releases pin this. Do not leave it empty.

APP_IMAGE=registry.distr.sh/basedash/charts-self-hosted-app:<version>

Database: For the bundled Compose Postgres, set POSTGRES_PASSWORD. Compose derives DATABASE_URL from POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB, using host postgres (the service name), not localhost. localhost inside the app container is the app itself.

POSTGRES_PASSWORD=your_secure_password_here
# Derived — leave this unless you use an external Postgres
# DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}

Encryption keys:

# Used for encrypting database passwords and configuration overrides
# Must be exactly 32 bytes. Generate with: openssl rand -hex 16
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:

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

# Application port published on the host. Default access is http://<host>:3000
APP_PORT=3000

Why BASE_URL matters: BASE_URL is required. It is used for:

Login redirects - The app builds /login from this URL. Missing http:// or https:// crashes the first page load
Email links - Invitation emails, password resets, and notifications
OAuth callbacks - SSO, MCP connection redirects, and third-party integrations
Shared dashboard links - Generated share links
Webhooks and API callbacks - External services calling back to your instance
CORS configuration - Cross-origin request handling

Examples:

https://basedash.your-company.com - TLS terminated on 443 (no port in the URL)
http://basedash.your-company.com:3000 - Direct to the app, no reverse proxy
http://localhost:3000 - Local development only

TLS and reverse proxy

HTTPS is not automatic. The app listens on port 3000 over HTTP. Direct access (default): open inbound TCP 3000 and use BASE_URL=http://<host>:3000. Caddy (Let’s Encrypt): the bundled Caddy service is opt-in and is not started by the Distr agent unless the Compose proxy profile is enabled.

Point DNS at the server
Open inbound 80 and 443
Set CADDY_HOST to the hostname (no scheme), BASE_URL=https://your-domain.com, and TRUST_PROXY=1
Start with docker compose --profile proxy up -d

Existing proxy (Cloudflare, nginx, load balancer): terminate TLS on 443, forward to :3000, set BASE_URL=https://your-domain.com and TRUST_PROXY=1. Cloudflare does not proxy port 3000.

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

Generate POSTGRES_PASSWORD with openssl rand -hex 24. Do not use base64 — characters like +, /, and = break DATABASE_URL parsing. Postgres only reads POSTGRES_PASSWORD the first time it initializes the data volume. Changing the env var later does not update an existing database. Reset the password inside the container (ALTER USER basedash WITH PASSWORD '...') or recreate the volume. Compose derives DATABASE_URL from these variables. You do not need to paste the password into the URL.

Using an external PostgreSQL instance

If you prefer to use an existing PostgreSQL instance instead of the bundled one:

Point DATABASE_URL to your external instance (this overrides the derived Compose URL):
DATABASE_URL=postgresql://user:password@your-postgres-host:5432/dbname
If the password contains reserved URL characters (+, /, =, @), percent-encode them in this value.
Ensure your PostgreSQL version is 16 or higher
Create the database:
CREATE DATABASE basedash_charts;
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

AI is optional on first boot. The app starts without keys and shows a banner until you add a provider. Chat and generation need a real API key. You can use OpenAI, Azure OpenAI, Anthropic, Amazon Bedrock, OpenRouter, 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 login codes, invitations, and automations.

First boot: log provider

The Compose and Helm templates default to EMAIL_PROVIDER=log. Login codes are written to the app logs instead of being emailed. Use this only until SMTP or SES is ready — anyone with log access can read codes.

EMAIL_PROVIDER=log

Read codes with docker compose logs app (or kubectl logs on Kubernetes).

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_SECURE=false
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)

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

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 automation 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 support@basedash.com to obtain your license key. Once you have it, add it to your environment configuration:

LICENSE_KEY=your-license-key-here

License behavior

Startup validation:

The server validates the license key against the Basedash license server on startup
If LICENSE_KEY is missing, the server refuses to start
If the license is invalid, expired, or inactive, the server refuses to start

Periodic heartbeats:

A heartbeat is sent to the Basedash license server every 6 hours
Heartbeats report basic usage metrics (organization and user counts) and app version for billing purposes
If a heartbeat fails, the app retries with exponential backoff (starting at 5 minutes, doubling up to 6 hours)

While running:

No banner is displayed when your license is active and valid
If the license expires or becomes invalid while the server is running, an error banner is displayed and new organization creation is disabled
If the license server cannot be reached during a heartbeat, a warning banner is displayed and new organization creation is disabled until the next successful heartbeat

Sandbox licenses

Sandbox licenses are intended for QA and CI environments. When using a sandbox license a “Sandbox environment” info banner is displayed at the top of the app and usage is not counted towards your billing.

Troubleshooting license issues

Server won’t start — missing license key: Add your LICENSE_KEY to your environment configuration and restart the application. Server won’t start — invalid, expired, or inactive license: The server validates the license on startup and will refuse to start if it is not valid. Check the server logs for the specific error, then contact Basedash at support@basedash.com to resolve. “Unable to verify license” warning banner: This appears when the server cannot reach the license server during a periodic heartbeat. The app continues to run but new organization creation is disabled until the next successful heartbeat.

Check that your deployment has outbound network access to charts.basedash.com
Verify no firewall rules are blocking HTTPS traffic
The application will retry with exponential backoff (5 minutes, then doubling up to 6 hours)

“License has expired” error banner: Contact Basedash at support@basedash.com to renew your license. While expired, new organization creation is disabled. “License has been deactivated” error banner: Your license has been manually deactivated. Contact support@basedash.com 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:

Check for new versions in the Distr customer portal
Pull the new image from the registry:
docker compose pull
Restart services to apply the update:
docker compose up -d
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

Google Cloud Storage setup

Follow these steps to configure Google Cloud Storage (GCS) as your S3-compatible storage backend.

Step 1: Create a Google Cloud Storage Bucket

Go to the Google Cloud Console
Navigate to Cloud Storage → Buckets
Click Create bucket
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)
Click Create

Step 2: Configure Bucket Permissions

Go to your bucket → Permissions tab
Click Grant Access
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)

Go to Cloud Storage → Settings (gear icon in the left sidebar)
Click the Interoperability tab
Under “Access keys for service accounts,” click Create a key for a service account
Select or create a service account with Storage Admin permissions for your bucket
Click Create key
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:

Install Google Cloud SDK if not already installed
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:

Try uploading a user avatar or organization icon
Check that the file appears in your GCS bucket
Verify the public URL works by accessing it directly

Summary of Environment Variables

Variable	Value	Description
`S3_BUCKET_NAME`	`your-bucket-name`	The GCS bucket name
`S3_BUCKET_ENDPOINT`	`https://storage.googleapis.com`	GCS S3-compatible endpoint
`S3_BUCKET_REGION`	`auto`	Can be `auto` or your bucket’s region
`S3_BUCKET_ACCESS_KEY_ID`	Your HMAC access key	From Interoperability settings
`S3_BUCKET_SECRET_ACCESS_KEY`	Your HMAC secret	From Interoperability settings
`S3_CDN_BASE_URL`	`https://your-cdn-domain.com`	(Optional) Only set if using a CDN

Slack app (optional)

Enable Slack notifications and automations:

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:

Verify all required environment variables are set (LICENSE_KEY, CRYPTO_KEY, PRISMA_FIELD_ENCRYPTION_KEY, POSTGRES_PASSWORD, BASE_URL, and for Compose APP_IMAGE)
For bundled Postgres, leave DATABASE_URL derived from POSTGRES_PASSWORD (host postgres, not localhost). Override it only for an external database
Ensure BASE_URL includes http:// or https://
Ensure CRYPTO_KEY is exactly 32 bytes (openssl rand -hex 16)
Review logs: docker compose logs app

Postgres password authentication failed after changing env: Postgres only applies POSTGRES_PASSWORD the first time the data volume is created. Changing the env var later does not update the database. Reset it inside the container (ALTER USER basedash WITH PASSWORD '...') so it matches POSTGRES_PASSWORD, or recreate the volume (this deletes data). If you overrode DATABASE_URL, that password must match the database as well. Browser never loads, but Distr shows healthy: Distr health checks /health inside the container. The default publish port is 3000 (plain HTTP). Confirm:

curl http://127.0.0.1:3000/health on the host
Inbound TCP 3000 is open on the cloud security group / firewall
You are using http://<host>:3000, not https://
If the hostname is on Cloudflare, port 3000 is not proxied — try the server IP or grey-cloud the record

“Something went wrong” on first page load: Open the Error message expander on that screen, or check app logs. The usual cause is BASE_URL set to a hostname without http:// or https://. AI features not working: The app starts without AI keys and shows a banner. Chat needs a real key:

Set AI_OPENAI_API_KEY (or another provider key) and a matching AI_MODEL
Check API key credits/quota
Test connectivity to the AI provider endpoint

Email delivery failing:

If EMAIL_PROVIDER=log, codes are in the app logs, not email
For SMTP, verify host, port, and credentials
Use port 587 with SMTP_SECURE=false or 465 with SMTP_SECURE=true
Ensure firewall allows outbound SMTP

Connecting a database shows “Database connection not found”: CRYPTO_KEY must be exactly 32 bytes. Generate with openssl rand -hex 16, restart the app, and try connecting again. Safe to replace if you have not successfully saved a database connection.

​Environment configuration

​Quick start: generate secrets

​Required core variables

​Optional configuration

​TLS and reverse proxy

​PostgreSQL database

​Automatic PostgreSQL setup

​PostgreSQL configuration

​Using an external PostgreSQL instance

​Database backups

​AI configuration

​OpenAI (default)

​Azure OpenAI

​Alternative AI providers

​AI feature considerations

​Email configuration

​First boot: log provider

​SMTP configuration

​Amazon SES configuration

​Email features

​Authentication and access control

​Disable public signups

​License key

​Obtaining a license key

​License behavior

​Sandbox licenses

​Troubleshooting license issues

​Update management

​Agent deployment updates

​Container deployment updates

​Version locking for compliance

​Advanced configuration

​Storage (optional)

​Step 1: Create a Google Cloud Storage Bucket

​Step 2: Configure Bucket Permissions

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

​Step 4: Configure CORS

​Step 5: Set Environment Variables

​Step 6: Verify the Setup

​Summary of Environment Variables

​Slack app (optional)

​Logging

​Support and troubleshooting

​Getting help

​Health monitoring

​Common configuration issues