Installation

Tapioca can be self-hosted on your own infrastructure. This guide covers installation options from simple Docker setups to production Kubernetes deployments.

Requirements

Minimum Requirements

• CPU: 2 cores
• RAM: 4GB
• Storage: 20GB SSD
• OS: Linux (Ubuntu 22.04+, Debian 12+, RHEL 9+)

Recommended for Production

• CPU: 4+ cores
• RAM: 8GB+
• Storage: 100GB+ SSD
• Database: PostgreSQL 15+ (external)
• Cache: Redis 7+ (external)

Quick Install with Docker

The fastest way to get started is with Docker Compose.

1. Download the Configuration

# Create a directory for Tapioca
mkdir tapioca && cd tapioca

# Download docker-compose.yml
curl -sL https://raw.githubusercontent.com/bcp-technology/tapioca/main/docker-compose.yml -o docker-compose.yml

# Download example environment file
curl -sL https://raw.githubusercontent.com/bcp-technology/tapioca/main/.env.example -o .env

2. Configure Environment

Edit the .env file with your settings:

# Required settings
TAPIOCA_DATABASE_URL=postgres://tapioca:password@postgres:5432/tapioca
TAPIOCA_REDIS_URL=redis://redis:6379
TAPIOCA_SECRET_KEY=your-secret-key-here  # Generate with: openssl rand -base64 32

# Domain configuration
TAPIOCA_DOMAIN=tapioca.example.com
TAPIOCA_TLS=true

# Email configuration (for notifications)
TAPIOCA_SMTP_HOST=smtp.example.com
TAPIOCA_SMTP_PORT=587
TAPIOCA_SMTP_USER=[email protected]
TAPIOCA_SMTP_PASSWORD=your-smtp-password

3. Start Services

# Start all services
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f tapioca

Tapioca will be available at http://localhost:3000 (or your configured domain).

Kubernetes Deployment

For production deployments, we recommend using Kubernetes with our Helm chart.

Prerequisites

• Kubernetes 1.28+
• Helm 3.12+
• kubectl configured for your cluster

1. Add the Helm Repository

helm repo add tapioca https://charts.tapioca.io
helm repo update

2. Create Values File

Create a values.yaml file for your deployment:

# values.yaml
replicaCount: 3

image:
  repository: ghcr.io/bcp-technology/tapioca
  tag: latest

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: tapioca.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: tapioca-tls
      hosts:
        - tapioca.example.com

postgresql:
  enabled: false  # Use external database

externalDatabase:
  host: your-postgres-host
  port: 5432
  database: tapioca
  user: tapioca
  existingSecret: tapioca-db-secret
  secretKey: password

redis:
  enabled: false  # Use external Redis

externalRedis:
  host: your-redis-host
  port: 6379
  existingSecret: tapioca-redis-secret

3. Install the Chart

# Create namespace
kubectl create namespace tapioca

# Install
helm install tapioca tapioca/tapioca 
  --namespace tapioca 
  --values values.yaml

4. Verify Installation

# Check pods
kubectl get pods -n tapioca

# Check services
kubectl get svc -n tapioca

# View logs
kubectl logs -n tapioca -l app.kubernetes.io/name=tapioca -f

Building from Source

For development or custom builds:

1. Clone the Repository

git clone https://github.com/bcp-technology/tapioca.git
cd tapioca

2. Build the Backend

# Install Go 1.22+
go build -o bin/tapiocad ./cmd/tapiocad

3. Build the Frontend

cd web
npm install
npm run build

4. Run

# Set environment variables
export TAPIOCA_DATABASE_URL="postgres://..."
export TAPIOCA_REDIS_URL="redis://..."

# Run the server
./bin/tapiocad

Post-Installation

Create Admin Account

On first launch, create your admin account:

1. Navigate to your Tapioca URL
2. Click “Create Admin Account”
3. Enter your email and password
4. Complete the organization setup

Configure SSO (Optional)

For enterprise deployments, configure SSO in Settings → Organization → SSO:

• OIDC providers (Okta, Auth0, Keycloak)
• SAML 2.0 integration
• Azure AD / Google Workspace

See the SSO Guide for detailed instructions.

Troubleshooting

Getting Help

• Check the FAQ
• Search GitHub Issues
• Join our Discord