New in Rulebricks: Reactive Rule Flows. More →
Private Deployment
Initial Setup

Initial Setup

The rulebricks init command guides you through creating your deployment configuration interactively. This guide explains each step of the initialization process.

Running the Init Wizard

Start the interactive setup:

rulebricks init

The wizard will prompt you for configuration options. You can also run in non-interactive mode by providing a configuration file or using flags (see Configuration Reference).

Configuration Steps

Project Information

Project Name

  • A Kubernetes-compatible name (lowercase, alphanumeric, hyphens only)
  • Used for namespace and resource naming
  • Example: my-rulebricks-app

Domain

  • Your application's primary domain
  • Must be a valid domain you control
  • Used for TLS certificate generation
  • Example: app.example.com

Admin Email

  • Email address for notifications and Let's Encrypt certificates
  • Must be a valid email address
  • Example: admin@example.com

License Key

  • Your Rulebricks license key
  • Can be provided via environment variable: env:RULEBRICKS_LICENSE_KEY
  • Or directly: your-license-key

Cloud Provider Selection

Choose your cloud provider: AWS, Azure, or GCP.

AWS Configuration

  • Region: AWS region (e.g., us-east-1, eu-west-1)
  • Instance Type: EC2 instance type (default: c8g.large - ARM-based Graviton)
  • VPC CIDR: VPC network range (default: 10.0.0.0/16)

Azure Configuration

  • Region: Azure region (e.g., eastus, westeurope)
  • Subscription ID: Your Azure subscription ID
  • Resource Group: Resource group name (will be created if it doesn't exist)
  • VM Size: VM size (default: Standard_D4ps_v5 - ARM-based)

GCP Configuration

  • Project ID: Your GCP project ID (required)
  • Region: GCP region (e.g., us-central1, europe-west1)
  • Zone: GCP zone (auto-derived from region if not specified)
  • Machine Type: Machine type (default: t2a-standard-4 - ARM-based)

Kubernetes Cluster Configuration

Cluster Name

  • Name for your Kubernetes cluster
  • Auto-generated if not specified
  • Example: my-rulebricks-cluster

Node Count

  • Initial number of nodes in the cluster
  • Minimum: 3 nodes (recommended for production)
  • Can be scaled later with autoscaling

Autoscaling (Optional)

  • Enable cluster autoscaling
  • Min Nodes: Minimum nodes (default: same as initial count)
  • Max Nodes: Maximum nodes (default: 2x initial count)
💡

ARM-based instances are required (AWS Graviton, Azure Ampere, GCP Tau). The CLI will default to ARM instance types.

Database Configuration

Choose your database deployment type:

Self-Hosted (Default)

Deploys a complete Supabase stack in your Kubernetes cluster:

  • PostgreSQL database
  • Supabase Studio (admin UI)
  • Authentication services
  • Realtime subscriptions
  • Storage services

Pros: Full control, no external dependencies, cost-effective
Cons: You manage backups and scaling

Managed

Uses a managed Supabase project:

  • Fully managed PostgreSQL
  • Automatic backups and scaling
  • Global CDN for assets
  • Built-in monitoring

Configuration Required:

  • Project Name: Your Supabase project name
  • Region: Supabase region
  • Organization ID: (Optional) Your Supabase organization ID

Pros: Managed service, automatic backups, less operational overhead
Cons: External dependency, additional cost

External

Connect to an existing PostgreSQL database:

  • Provide connection string
  • Support for read replicas
  • Connection pooling available

Pros: Use existing infrastructure
Cons: You manage the database separately

Email Configuration

Provider

  • Choose: smtp, sendgrid, mailgun, ses, or resend
  • All providers use SMTP configuration

SMTP Settings

  • Host: SMTP server hostname
  • Port: SMTP port (typically 587 for TLS, 465 for SSL)
  • Username: SMTP username
  • Password: Password source (e.g., env:SMTP_PASSWORD)
  • Encryption: tls, ssl, or none
  • From Address: Email address for outgoing emails
  • From Name: Display name for outgoing emails

Security Configuration

TLS/SSL

  • Enabled: Enable automatic TLS certificate generation
  • Provider: cert-manager (Let's Encrypt) or custom
  • ACME Email: Email for Let's Encrypt notifications
  • Additional Domains: Extra domains for certificates (optional)

Network Security (Optional)

  • IP Whitelist: Restrict access to specific IP ranges
  • Rate Limiting: Enable rate limiting on ingress

Monitoring Configuration

Enable Monitoring

  • Choose whether to deploy monitoring infrastructure

Monitoring Mode

Local Mode (Default):

  • Full Prometheus and Grafana stack in your cluster
  • 30-day retention, 50Gi storage
  • Grafana accessible at https://grafana.your-domain.com
  • Best for: Development, isolated environments

Remote Mode:

  • Minimal Prometheus deployment
  • Forwards metrics to external monitoring
  • Supports: Grafana Cloud, New Relic, custom Prometheus endpoints
  • Best for: Production with existing monitoring

Disabled:

  • No monitoring infrastructure
  • Use if you have alternative monitoring solutions

Logging Configuration

Enable Logging

  • Enable centralized logging with Vector

Sink Type

  • Console: Output to stdout (default)
  • Elasticsearch: Elasticsearch endpoint
  • Datadog: Datadog logs
  • Splunk: Splunk HEC endpoint
  • AWS S3: S3 bucket (requires IAM setup)
  • GCS: Google Cloud Storage (requires IAM setup)
  • Azure Blob: Azure Blob Storage (requires IAM setup)
  • Loki: Loki endpoint
  • HTTP: Generic HTTP endpoint

See Vector Logging Setup for detailed configuration.

Performance Configuration

Volume Level

  • Small: Development/testing (<1000 rules/sec)
  • Medium: Production (1,000-10,000 rules/sec)
  • Large: High performance (>10,000 rules/sec)

The wizard will automatically configure:

  • HPS replicas and scaling
  • Worker pool size
  • Kafka partitions and retention
  • Resource requests and limits

You can customize these later in the configuration file.

Generated Configuration File

After completing the wizard, a rulebricks.yaml file is created in your current directory. This file contains all your configuration settings.

Example Configuration

version: "1.0"
 
project:
  name: my-rulebricks-app
  domain: app.example.com
  email: admin@example.com
  license: env:RULEBRICKS_LICENSE_KEY
  version: "1.0.0"
 
cloud:
  provider: aws
  region: us-east-1
  aws:
    instance_type: c8g.large
 
kubernetes:
  cluster_name: my-rulebricks-cluster
  node_count: 3
  enable_autoscale: true
  min_nodes: 3
  max_nodes: 10
 
database:
  type: self-hosted
 
email:
  provider: smtp
  from: noreply@example.com
  from_name: "Rulebricks"
  smtp:
    host: smtp.example.com
    port: 587
    username: smtp-user
    password_from: env:SMTP_PASSWORD
 
security:
  tls:
    enabled: true
    provider: cert-manager
    acme_email: admin@example.com
 
monitoring:
  enabled: true
  mode: local
 
logging:
  enabled: false
 
performance:
  volume_level: medium

Editing Your Configuration

You can edit rulebricks.yaml directly at any time. The file uses YAML syntax and includes comments explaining each option.

To validate your configuration:

rulebricks deploy --dry-run  # If supported

Or simply try deploying - the CLI will validate the configuration before starting.

Re-running the Wizard

To modify your configuration, you can:

  1. Edit the file directly - Recommended for small changes
  2. Re-run the wizard - The wizard will load existing values as defaults
  3. Start fresh - Delete rulebricks.yaml and run rulebricks init again

Next Steps

Once your configuration is ready:

  1. Review the configuration file - Ensure all settings are correct
  2. Set up environment variables - For secrets like license keys and passwords
  3. Verify cloud credentials - Ensure you're authenticated with your cloud provider
  4. Configure DNS - Point your domain to your cloud provider (can be done after deployment)
  5. Deploy - See Deployment Guide

Configuration Best Practices

  1. Use environment variables for secrets - Never commit secrets to version control
  2. Start with defaults - The wizard provides sensible defaults for most options
  3. Test in a development environment first - Use a separate project/region for testing
  4. Document custom settings - Add comments in your config file explaining non-standard choices
  5. Version control your config - Commit rulebricks.yaml (without secrets) to version control

Troubleshooting

Invalid Project Name

If you get an error about the project name:

  • Must be lowercase
  • Can contain alphanumeric characters and hyphens
  • Must start and end with alphanumeric characters
  • Maximum 63 characters

Domain Validation

The domain must be a valid domain format. You don't need to have DNS configured yet, but the domain format must be correct.

Cloud Provider Errors

If you see errors about cloud provider configuration:

  • Ensure you're authenticated: aws configure, gcloud auth login, or az login
  • Check that required fields are provided (especially GCP project ID)
  • Verify your cloud provider account has necessary permissions

For more help, see Status & Troubleshooting.

Configuration ReferenceDeployment