Skip to main content
Note: This guide assumes you have access to the Distr customer portal. If you haven’t received your invite yet, see the Getting started section in Overview.

​
Deployment methods

Basedash uses Distr, an enterprise software distribution platform, to manage self-hosted deployments. Choose the deployment method that best fits your infrastructure: 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: 
    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: 
    docker compose pull
docker compose up -d
    On initial deployment, run without -d to inspect logs in real-time. Configuration errors may prevent the app from running. See the Configure section for setup details.
Updates: Pull new image versions from the registry when you’re ready to update: 
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: 
    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 
    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: 
    # 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 for all available options including AI, S3 storage, and Slack integration.
  4. Install the chart 
    helm install basedash-charts ./basedash-charts-0.1.0.tgz -f values.yaml
  5. Verify the deployment 
    kubectl get pods -l app.kubernetes.io/name=basedash-charts
kubectl get svc
Accessing Basedash: If using a LoadBalancer service: 
kubectl get svc basedash-charts-app -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
Or configure ingress in your values file: 
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: 
postgres:
  enabled: false
  external:
    url: "postgresql://user:pass@your-postgres-host:5432/basedash"
Your PostgreSQL must have wal_level=logical enabled for ElectricSQL sync to work.
Updates: Download the new chart version and upgrade: 
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