Self-Hosting

Kubernetes + Helm Deployment

Enterprise Only: This deployment guide is exclusively for Enterprise customers. Self-hosting requires an Enterprise license and access to our private Helm chart repository. Contact us to discuss your self-hosting requirements and get access.

Kubernetes + Helm Deployment Guide

This guide provides the complete installation checklist for deploying Promptless on Kubernetes using Helm charts. Everything is parameterized through values.yaml—you should never need to edit the Helm chart itself.

Quick Start Checklist

This is the happy-path installation checklist for prospects:

1

Prerequisites

  • AWS account with EKS cluster version 1.27+, IRSA enabled
  • kubectl, helm, and aws-cli installed locally
  • Route 53 hosted zone for promptless.<corp>.com
2

Provision Infrastructure

  • EKS cluster & node groups
  • RDS PostgreSQL
  • S3-compatibile document store (e.g. a bucket named promptless-doc-store)
  • VPC Endpoints for RDS, S3, Bedrock (if using language models restricted within your AWS VPC)
  • IAM roles with scoped policies
3

Configure Container Images

Choose Option A (direct pull) or Option B (private registry)

4

Create Kubernetes Secrets

Set up database credentials and authentication secrets

5

Configure values.yaml

Customize deployment settings for your environment

6

Install Dependencies

Install cert-manager if not already present

7

Deploy Promptless

Install via Helm chart

8

Post-Installation

Verify deployment and configure user access

Architecture

The self-hosted deployment uses a microservices architecture running on Kubernetes:

API Server

Handles REST API requests, authentication, and core business logic

Worker Processes

Processes documentation generation jobs and integrations

Web Dashboard

User interface for project management and configuration

Prerequisites

Before installing Promptless, ensure you have the following:

Infrastructure Requirements

  • AWS account with EKS cluster version 1.27 or higher
  • IRSA (IAM Roles for Service Accounts) enabled
  • Node groups configured (including GPU nodes if using local LLMs)
  • RDS PostgreSQL instance (recommended: Aurora PostgreSQL)
  • S3 bucket for document storage (e.g., promptless-doc-store)
  • Route 53 hosted zone for your domain (e.g., promptless.corp.com)
  • VPC Endpoints for AWS services: STS, Bedrock, S3, Secrets Manager (plus GitHub Enterprise if applicable)

IAM Roles

Create the following IAM roles with scoped policies:

  • promptless-api: Access to Bedrock, S3, and Secrets Manager
  • promptless-worker: Background job processing permissions
  • promptless-dashboard: Web interface permissions

We can provide Terraform modules to provision the baseline infrastructure. Contact our support team at help@gopromptless.ai for infrastructure templates and IAM policy examples.

Installation Guide

Follow these steps to install Promptless on your Kubernetes cluster:

1

Provision Infrastructure

Set up the baseline AWS infrastructure. You can use the Terraform modules we provide or create resources manually.

Required Resources:

  • EKS cluster with node groups (including GPU nodes if using local LLMs)
  • RDS PostgreSQL
  • S3 bucket promptless-doc-store
  • VPC Endpoints for: STS, Bedrock, S3, Secrets Manager (plus GitHub Enterprise if applicable)
  • IAM roles: promptless-api, promptless-worker, promptless-dashboard with scoped policies for Bedrock, S3, RDS

Contact our support team for Terraform modules and infrastructure templates.

2

Configure Container Images

Choose your container image strategy:

Option A: Direct Pull (Recommended)

$# Allow EKS to pull directly from our public registry
># No additional configuration needed - images pulled from:
># public.ecr.aws/promptless/*

Option B: Private Registry

$# Import images to your private ECR and configure values.yaml:
>image:
>  registry: <account-id>.dkr.ecr.<region>.amazonaws.com
3

Create Kubernetes Secrets

Create a secret containing your database credentials and other sensitive configuration:

$kubectl create secret generic promptless-secrets \
>  --from-literal=POSTGRES_URL="postgresql://user:password@host:5432/promptless" \
>  --from-literal=JWT_SECRET="your-jwt-secret-key" \
>  --from-literal=OIDC_CLIENT_SECRET="your-oidc-client-secret"
4

Configure values.yaml

Create a values.yaml file with your deployment configuration:

values.yaml
1global:
2  domain: promptless.corp.acme.com
3
4auth:
5  provider: oidc
6  oidcIssuerURL: https://sso.acme.com
7
8llm:
9  provider: bedrock
10  model: anthropic.claude-3-sonnet-20240229-v1:0
11
12observability:
13  mode: cloudwatch
14
15integrations:
16  github:
17    enabled: true
18    apiBaseURL: https://github.acme.com/api/v3
19
20# Resource configuration
21api:
22  replicas: 2
23  resources:
24    requests:
25      memory: "512Mi"
26      cpu: "250m"
27    limits:
28      memory: "1Gi"
29      cpu: "500m"

Authentication Providers:

  • oidc: OpenID Connect (recommended for enterprise)
  • saml: SAML 2.0
  • oauth: OAuth 2.0 with various providers

LLM Providers:

  • bedrock: AWS Bedrock (recommended)
  • openai: OpenAI API
  • anthropic: Anthropic Claude API
  • local: Self-hosted models

Observability:

  • cloudwatch: AWS CloudWatch
  • datadog: DataDog
  • prometheus: Prometheus + Grafana
5

Install cert-manager

If you don’t already have cert-manager installed:

$helm repo add jetstack https://charts.jetstack.io
>helm install cert-manager jetstack/cert-manager \
>  --namespace cert-manager \
>  --create-namespace \
>  --set installCRDs=true
6

Install Promptless

Add the Promptless Helm repository and install:

$# Add Helm repository
>helm repo add promptless https://charts.promptless.com
>helm repo update
>
># Install Promptless
>helm upgrade --install promptless promptless/server \
>  --namespace promptless \
>  --create-namespace \
>  -f values.yaml

The installation typically takes 3-5 minutes. Monitor the deployment with:

$kubectl get pods -n promptless -w
7

Post-Installation Verification

After installation, verify your deployment:

$# Check pod status
>kubectl get pods -n promptless
>
># Verify database migrations succeeded
>kubectl logs -l app=promptless-api -n promptless
>
># Check service endpoints
>kubectl get services -n promptless

Verification Checklist:

  • All pods are running and ready
  • Database migrations completed successfully
  • Services are accessible
  • SSL certificates are issued
8

Configure User Access

Set up user access through your identity provider:

  1. Invite Users: Use your IdP group mapping to grant access
  2. Verify Authentication: Test that users can log in successfully
Example IdP Configuration
1auth:
2  provider: oidc
3  oidcIssuerURL: https://sso.acme.com
4  groupMappings:
5    - idpGroup: "promptless-admins"
6      role: "admin"
7    - idpGroup: "promptless-users"
8      role: "user"
9

Test Documentation Generation

Verify the system is working by:

  1. Access Dashboard: Navigate to your Promptless domain
  2. Create Project: Set up a test project with integrations
  3. Trigger Test Ingestion: Test documentation generation via UI
  4. Validate S3 Objects: Check S3 bucket for generated assets
  5. Validate Bedrock Calls: Ensure LLM integration is working
  6. Monitor Logs: Check CloudWatch logs for any errors

If documentation generation completes successfully, your installation is ready for production use!

Configuration Reference

Environment Variables

Key environment variables for customizing your deployment:

POSTGRES_URL
stringRequired

PostgreSQL connection string for the application database

JWT_SECRET
stringRequired

Secret key for JWT token signing and verification

S3_BUCKET
stringRequired

S3 bucket name for document and asset storage

AWS_REGION
stringRequired

AWS region for Bedrock and other AWS services

Helm Chart Values

The Promptless Helm chart supports extensive customization through values.yaml:

1global:
2  domain: promptless.example.com
3  environment: production
4  imageRegistry: public.ecr.aws/promptless
1auth:
2  provider: oidc
3  oidcIssuerURL: https://auth.example.com
4  sessionTimeout: 24h
5  mfaRequired: true
1api:
2  replicas: 2
3  resources:
4    requests:
5      memory: "512Mi"
6      cpu: "250m"
7    limits:
8      memory: "1Gi"
9      cpu: "500m"
1integrations:
2  github:
3    enabled: true
4    apiBaseURL: https://api.github.com
5  slack:
6    enabled: true
7  linear:
8    enabled: true

Maintenance & Operations

Upgrades

Keep your Promptless installation up to date:

$# Update Helm repository
>helm repo update
>
># Upgrade to latest version
>helm upgrade promptless promptless/server \
>  --namespace promptless \

Always review the changelog before upgrading and test in a staging environment first.

Troubleshooting

Common Issues

Symptoms: Pods stuck in Pending or CrashLoopBackOff state

Solutions:

  1. Check resource availability: kubectl describe nodes
  2. Verify secrets exist: kubectl get secrets -n promptless
  3. Check pod logs: kubectl logs <pod-name> -n promptless
  4. Validate values.yaml configuration

Symptoms: API server logs show database connection errors

Solutions:

  1. Verify PostgreSQL URL in secrets
  2. Check RDS security groups and network connectivity
  3. Ensure database exists and migrations can run
  4. Test connection from a debug pod

Symptoms: Users cannot log in or receive authentication errors

Solutions:

  1. Verify OIDC/SAML configuration in values.yaml
  2. Check IdP connectivity and certificate validity
  3. Review authentication provider logs
  4. Validate redirect URLs and client secrets

Symptoms: Jobs fail or documents are not generated

Solutions:

  1. Check worker pod logs for errors
  2. Verify Bedrock/LLM provider connectivity
  3. Ensure S3 bucket permissions are correct

Getting Help

If you encounter issues not covered in this guide:

  1. Check Logs: Review CloudWatch logs for error messages
  2. Contact Support: Email help@gopromptless.ai with:
    • Deployment configuration (sanitized)
    • Error logs and symptoms
    • Steps to reproduce the issue

Our support team typically responds within 1 business hour for self-hosted deployments.

Security Considerations

Network Security

  • Use private subnets for database instances
  • Configure security groups to restrict access to necessary ports only
  • Enable VPC Flow Logs for network monitoring
  • Use AWS PrivateLink/VPC Endpoints for AWS service access

Data Protection

  • Enable encryption at rest for RDS and S3
  • Use TLS 1.2+ for all communications
  • Implement proper IAM roles with least privilege access
  • Regular security updates and vulnerability scanning

Compliance

Self-hosted Promptless supports various compliance requirements:

  • SOC 2: Audit logging and access controls
  • GDPR: Data residency and privacy controls
  • HIPAA: Enhanced encryption and access logging
  • FedRAMP: Government cloud deployment options

Contact our team to discuss specific compliance requirements for your deployment.

Example Architecture Diagram

The following diagram illustrates a typical EKS + Bedrock deployment architecture with self-hosted GitHub Enterprise and Slack integrations:

Architecture Components

Kubernetes Deployments
  • Backend API: Handles REST requests and core business logic
  • Frontend Dashboard: Web interface served at promptless.corp.com
  • Worker Processes: Background jobs for documentation generation
AWS Services
  • RDS PostgreSQL: Application database with VPC endpoint
  • S3 Bucket: Document and asset storage with VPC endpoint
  • Bedrock: LLM service for AI-powered documentation generation
External Integrations
  • GitHub Enterprise: Self-hosted Git platform integration
  • Slack: Corporate messaging platform integration
  • VPC Connectivity: Secure connections via VPC endpoints
Security Features
  • VPC Endpoints: Private connectivity to AWS services
  • Security Groups: Network-level access controls
  • IAM Roles: Service-specific permissions with IRSA

Key Architectural Benefits

  • Data Sovereignty: All data remains within your AWS VPC
  • Secure Connectivity: VPC endpoints eliminate internet traffic for AWS services
  • Scalable Design: Kubernetes deployments can scale based on demand
  • Enterprise Integration: Direct connectivity to self-hosted GitHub and Slack
  • Compliance Ready: Architecture supports SOC 2, GDPR, HIPAA, and FedRAMP requirements