> ## Documentation Index
> Fetch the complete documentation index at: https://basedash.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure

> Configure environment variables, AI models, email, and database

## 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/](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:**

```bash theme={"dark"}
DATABASE_URL=postgresql://basedash:password@postgres:5432/basedash_charts
```

**Encryption keys:**

```bash theme={"dark"}
# 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:**

```bash theme={"dark"}
# 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, MCP connection redirects, 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:

```bash theme={"dark"}
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:**

   ```bash theme={"dark"}
   DATABASE_URL=postgresql://user:password@your-postgres-host:5432/dbname
   ```

2. **Ensure your PostgreSQL version is 16 or higher**

3. **Create the database:**

   ```sql theme={"dark"}
   CREATE DATABASE basedash_charts;
   ```

4. **Migrations will run automatically** on first startup

### Database backups

For production deployments, we recommend regular backups:

```bash theme={"dark"}
# 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:

```bash theme={"dark"}
# 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:

```bash theme={"dark"}
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`:

```bash theme={"dark"}
# 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, automations, and user invitations. Basedash supports SMTP for outbound email.

### SMTP configuration

Configure your SMTP server:

```bash theme={"dark"}
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)

### Amazon SES configuration

Configure Amazon Simple Email Service (SES) directly:

```bash theme={"dark"}
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](/features/sso) 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:

```bash theme={"dark"}
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](mailto:support@basedash.com) to obtain your license key. Once you have it, add it to your environment configuration:

```bash theme={"dark"}
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](mailto: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.

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 retry with exponential backoff (5 minutes, then doubling up to 6 hours)

**"License has expired" error banner:**

Contact Basedash at [support@basedash.com](mailto: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](mailto: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:

1. **Check for new versions** in the Distr customer portal
2. **Pull the new image** from the registry:
   ```bash theme={"dark"}
   docker compose pull
   ```
3. **Restart services** to apply the update:
   ```bash theme={"dark"}
   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:

```bash theme={"dark"}
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:

```bash theme={"dark"}
S3_CDN_BASE_URL=https://cdn.example.com
```

<AccordionGroup>
  <Accordion title="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

    1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
    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`:

    ```json theme={"dark"}
    [
      {
        "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:

    ```bash theme={"dark"}
    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:

    ```bash theme={"dark"}
    # 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

    | 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    |
  </Accordion>
</AccordionGroup>

### Slack app (optional)

Enable Slack notifications and automations:

```bash theme={"dark"}
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:

```bash theme={"dark"}
# 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](mailto:support@basedash.com) for configuration assistance
* **Documentation** - Refer to deployment-specific guides in the portal

### Health monitoring

Check application health:

```bash theme={"dark"}
# 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