> ## 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.

# Deploy

> Deploy Basedash using agent-based deployment or container registry

> **Note**: This guide assumes you have access to the Distr customer portal. If you haven't received your invite yet, see the [Getting started](/self-hosting/overview#getting-started) section in Overview.

## Deployment methods

Basedash uses [Distr](https://distr.sh/docs/getting-started/what-is-distr/), an enterprise software distribution platform, to manage self-hosted deployments. Choose the deployment method that best fits your infrastructure:

### Agent deployment (recommended)

**Best for**: New server deployments where you want a fully managed, automated deployment experience.

The Distr agent runs in your environment and automatically manages Basedash deployment, updates, and health monitoring.

**How it works**:

* Install the Distr agent on your target server with a single command
* Agent polls the Distr Hub every 5 seconds for deployment instructions
* Automatically pulls container images, deploys via Docker Compose, and reports status
* Provides automatic updates and version management through the Distr portal

**Benefits**:

* **Fully automated** - Agent handles deployment, updates, and rollbacks
* **Health monitoring** - Built-in status reporting and deployment health checks
* **Version control** - Manage versions and deployment schedules via Distr portal
* **Outbound-only connectivity** - No need to expose ports; agent connects outbound to Distr Hub

**Prerequisites**:

* Server with Docker installed
* Outbound HTTPS connectivity to Distr Hub
* Target credentials from Distr portal (targetId and targetSecret)

**Installation**:

1. Log in to your Distr customer portal
2. Navigate to your deployment target
3. Copy the installation command (format: `curl "https://<hub>/api/v1/connect?targetId=<id>&targetSecret=<secret>" | docker compose -f - up -d`)
4. Run the command on your target server
5. Agent will automatically deploy and manage Basedash

**Note**: The targetSecret is shown only once during setup. Store it securely.

### Container deployment

**Best for**: Existing Docker infrastructure where you want manual control or need to deploy Basedash alongside other containers.

Pull container images directly from the Distr registry and deploy using your own docker-compose configuration or orchestration tools.

**How it works**:

* Authenticate to Distr's private OCI-compliant registry using a Personal Access Token (PAT)
* Pull Basedash container images from the registry
* Deploy using provided docker-compose files or author your own
* Manually manage updates by pulling new image versions

**Benefits**:

* **Full control** - You decide when and how to deploy and update
* **Existing workflows** - Integrate with your CI/CD pipelines and deployment automation
* **Flexible** - Works with existing Docker infrastructure and multi-container setups
* **Air-gap compatible** - Pull once, deploy in isolated environments

**Prerequisites**:

* Server with Docker installed
* Personal Access Token from Distr portal
* Network access to data sources

**Installation**:

1. Log in to your Distr customer portal
2. Generate a Personal Access Token (PAT)
3. Authenticate to the Distr registry:
   ```bash theme={"dark"}
   echo "YOUR-ACCESS-TOKEN" | docker login registry.distr.sh --password-stdin -u -
   ```
4. Download the provided docker-compose file or author your own
5. Pull and run Basedash:

   ```bash theme={"dark"}
   docker compose pull
   docker compose up -d
   ```

   <Tip>
     On initial deployment, run without `-d` to inspect logs in real-time.
     Configuration errors may prevent the app from running. See the
     [Configure](/self-hosting/configure) section for setup details.
   </Tip>

**Updates**: Pull new image versions from the registry when you're ready to update:

```bash theme={"dark"}
docker compose pull
docker compose up -d
```

### Kubernetes deployment

**Best for**: Organizations with existing Kubernetes infrastructure who want to deploy Basedash using Helm.

Deploy Basedash to your Kubernetes cluster using our official Helm chart. This method gives you full control over the deployment while leveraging Kubernetes-native features like auto-scaling, rolling updates, and resource management.

**How it works**:

* Download the Helm chart from our chart repository
* Authenticate to Distr's container registry for the app image
* Configure your deployment using a values file
* Deploy using standard Helm commands

**Benefits**:

* **Kubernetes-native** - Uses standard Kubernetes resources (Deployments, StatefulSets, Services)
* **Helm managed** - Easy upgrades, rollbacks, and configuration management
* **Flexible** - Bring your own PostgreSQL, configure ingress, customize resources
* **Production ready** - Includes health checks, resource limits, and proper service dependencies

**Prerequisites**:

* Kubernetes cluster (1.24+)
* Helm 3.x installed
* `kubectl` configured for your cluster
* Personal Access Token from Distr portal (for container images)

**Installation**:

1. **Create image pull secret**

   Log in to your Distr customer portal and generate a Personal Access Token (PAT), then create a Kubernetes secret for pulling container images:

   ```bash theme={"dark"}
   kubectl create secret docker-registry distr-registry \
     --docker-server=registry.distr.sh \
     --docker-username=- \
     --docker-password=YOUR_DISTR_ACCESS_TOKEN
   ```

2. **Download the Helm chart**

   ```bash theme={"dark"}
   helm pull https://charts-self-hosted.sfo3.cdn.digitaloceanspaces.com/helm/basedash-charts-0.1.0.tgz
   ```

3. **Create your values file**

   Save as `values.yaml`:

   ```yaml theme={"dark"}
   # Image pull secret (required)
   imagePullSecrets:
     - name: distr-registry

   app:
     baseUrl: "https://charts.yourdomain.com"

   postgres:
     auth:
       password: "" # Generate: openssl rand -hex 24

   secrets:
     cryptoKey: "" # Generate: openssl rand -hex 32
     electricSecret: "" # Generate: uuidgen
     prismaFieldEncryptionKey: "" # Generate: npx @47ng/cloak generate

   email:
     provider: smtp
     smtp:
       host: "smtp.example.com"
       port: 587
       user: ""
       password: ""
       fromEmail: "noreply@yourdomain.com"
   ```

   See [Configuration](/self-hosting/configure) for all available options including AI, S3 storage, and Slack integration.

4. **Install the chart**

   ```bash theme={"dark"}
   helm install basedash-charts ./basedash-charts-0.1.0.tgz -f values.yaml
   ```

5. **Verify the deployment**

   ```bash theme={"dark"}
   kubectl get pods -l app.kubernetes.io/name=basedash-charts
   kubectl get svc
   ```

**Accessing Basedash**:

If using a LoadBalancer service:

```bash theme={"dark"}
kubectl get svc basedash-charts-app -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
```

Or configure ingress in your values file:

```yaml theme={"dark"}
ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: charts.yourdomain.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: charts-tls
      hosts:
        - charts.yourdomain.com
```

**Using external PostgreSQL**:

To bring your own PostgreSQL database instead of deploying one:

```yaml theme={"dark"}
postgres:
  enabled: false
  external:
    url: "postgresql://user:pass@your-postgres-host:5432/basedash"
```

<Warning>
  Your PostgreSQL must have `wal_level=logical` enabled for ElectricSQL sync to
  work.
</Warning>

**Updates**:

Download the new chart version and upgrade:

```bash theme={"dark"}
helm pull https://charts-self-hosted.sfo3.cdn.digitaloceanspaces.com/helm/basedash-charts-X.Y.Z.tgz
helm upgrade basedash-charts ./basedash-charts-X.Y.Z.tgz -f values.yaml
```

### Air-gapped deployment

For fully isolated environments with no internet connectivity, we support physical media transfers (USB/secure media) with encrypted updates. Contact our team to set up an air-gapped deployment plan.

## Machine specifications

> **Note**: These specifications assume the target machine is dedicated to running Basedash. If the machine is running other applications, you'll need to allocate additional resources accordingly.

### Minimum requirements

For 1-10 concurrent users:

* **vCPUs**: 2
* **RAM**: 8GB
* **Storage**: 50GB SSD

**Cloud provider options:**

* AWS: t3.large
* GCP: e2-standard-2
* Digital Ocean: 2vCPU/8GB Droplet

### Scaling guidelines

As your team grows, we recommend upgrading to:

* **10-50 users**: 4 vCPUs, 16GB RAM, 100GB SSD
* **50+ users**: 8 vCPUs, 32GB RAM, 200GB+ SSD

### Storage recommendations

* **SSD strongly recommended** for optimal performance
* Plan for approximately 1-5GB per 1,000 charts/dashboards, plus system overhead

### Network requirements

* **Ports**: 80 (HTTP) and 443 (HTTPS) must be accessible
* **Outbound internet access**: Required for AI features and email delivery
* **Agent deployment**: Outbound HTTPS to Distr Hub required