Skip to content
Klutch.sh Docs

Deploying Corteza

Introduction

Corteza is a powerful, open-source Low-Code platform designed for building sophisticated business applications and workflows. As a comprehensive digital work platform, Corteza empowers organizations to create custom CRM systems, automate business processes, and integrate disparate data sources without extensive coding knowledge.

Corteza is known for its:

  • Low-Code Development: Build complex business applications with minimal coding through an intuitive visual interface
  • Workflow Automation: Create sophisticated automation workflows using a visual workflow composer
  • Data Integration: Connect and consolidate data from multiple sources into unified business applications
  • Extensibility: Customize and extend functionality using JavaScript and Vue.js
  • Self-Hosted Control: Maintain complete ownership and control of your business data
  • Modular Architecture: Deploy only the components you need with a flexible, microservices-based architecture

Deploying Corteza on Klutch.sh provides you with scalable, reliable infrastructure for your business applications, complete with automated deployments, persistent storage, and production-ready configurations.

This comprehensive guide walks you through deploying Corteza on Klutch.sh using Docker, including detailed installation steps, sample configurations, connection examples, and production-ready best practices for persistent storage.

Prerequisites

Before you begin, ensure you have the following:

Installation and Setup

Step 1: Create Your Project Directory

First, create a new directory for your Corteza deployment project:

Terminal window
mkdir corteza-klutch
cd corteza-klutch
git init

Step 2: Create the Dockerfile

Create a Dockerfile in your project root directory. This will define your Corteza container configuration:

FROM cortezaproject/corteza:2024.9


# Set working directory
WORKDIR /corteza


# Expose the default Corteza HTTP port
EXPOSE 80


# Health check to ensure Corteza is running
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s \
  CMD wget --no-verbose --tries=1 --spider http://localhost/healthcheck || exit 1


# The official image already has the correct entrypoint
# It will start the Corteza server automatically

Note: This uses the official Corteza Docker image which includes all necessary components (server, workflows, and web applications).

Step 3: Create Environment Configuration (Optional)

For local testing, you can create a .env.example file to document the required environment variables:

Terminal window
# Database Configuration
DB_DSN=postgres://username:password@database-host:8000/corteza?sslmode=disable


# Server Configuration
HTTP_ADDR=0.0.0.0:80


# Authentication
AUTH_JWT_SECRET=your-super-secret-random-string-change-this


# Base URL (update with your Klutch.sh URL after deployment)
CORTEZA_BASE_URL=https://example-app.klutch.sh


# Additional security settings
AUTH_SESSION_LIFETIME=24h
AUTH_SESSION_PERM_LIFETIME=720h

Important: Never commit real credentials to your repository. Use this file only as a template.

Step 4: Test Locally (Optional)

Before deploying to Klutch.sh, you can test your Corteza setup locally. First, ensure you have a PostgreSQL database running:

Terminal window
# Start a test PostgreSQL database (if you don't have one)
docker run -d \
  --name corteza-db \
  -e POSTGRES_PASSWORD=corteza_password \
  -e POSTGRES_USER=corteza \
  -e POSTGRES_DB=corteza \
  -p 5432:5432 \
  postgres:16-alpine


# Build the Corteza Docker image
docker build -t my-corteza .


# Run Corteza locally
docker run -d \
  --name corteza-test \
  -p 8080:80 \
  -e DB_DSN="postgres://corteza:corteza_password@host.docker.internal:5432/corteza?sslmode=disable" \
  -e AUTH_JWT_SECRET="change-this-to-a-long-random-string" \
  -e CORTEZA_BASE_URL="http://localhost:8080" \
  my-corteza


# Wait a moment for Corteza to initialize, then visit
# http://localhost:8080 in your browser


# Stop and remove test containers when done
docker stop corteza-test corteza-db
docker rm corteza-test corteza-db

Step 5: Push to GitHub

Commit your Dockerfile to your GitHub repository:

Terminal window
git add Dockerfile .env.example
git commit -m "Add Corteza Dockerfile and environment configuration"
git remote add origin https://github.com/yourusername/corteza-klutch.git
git push -u origin main

Connecting to Corteza

Once deployed, Corteza will be accessible via HTTPS at your assigned Klutch.sh URL. The platform provides a web-based interface for building and managing your business applications.

Accessing the Web Interface

Simply navigate to your deployment URL:

https://example-app.klutch.sh

The first time you access Corteza, you’ll need to complete the initial setup:

  1. Create your first admin user account
  2. Set up your organization
  3. Begin creating your business applications

API Access

Corteza also provides a comprehensive REST API for programmatic access. Here are examples for different languages:

JavaScript/Node.js:

const fetch = require('node-fetch');


const CORTEZA_URL = 'https://example-app.klutch.sh';
const API_TOKEN = 'your-api-token-here';


async function fetchRecords() {
  const response = await fetch(`${CORTEZA_URL}/api/compose/namespace/your-namespace/module/your-module/record/`, {
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    }
  });


  const data = await response.json();
  console.log('Records:', data);
}


fetchRecords();

Python:

import requests


CORTEZA_URL = 'https://example-app.klutch.sh'
API_TOKEN = 'your-api-token-here'


headers = {
    'Authorization': f'Bearer {API_TOKEN}',
    'Content-Type': 'application/json'
}


response = requests.get(
    f'{CORTEZA_URL}/api/compose/namespace/your-namespace/module/your-module/record/',
    headers=headers
)


records = response.json()
print('Records:', records)

Go:

package main


import (
    "fmt"
    "io/ioutil"
    "net/http"
)


func main() {
    cortezaURL := "https://example-app.klutch.sh"
    apiToken := "your-api-token-here"


    client := &http.Client{}
    req, _ := http.NewRequest("GET",
        cortezaURL+"/api/compose/namespace/your-namespace/module/your-module/record/",
        nil)
    req.Header.Add("Authorization", "Bearer "+apiToken)
    req.Header.Add("Content-Type", "application/json")


    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()


    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println("Response:", string(body))
}

Deploying to Klutch.sh

Now that your Corteza project is ready and pushed to GitHub, follow these steps to deploy it on Klutch.sh with persistent storage.

Deployment Steps

    1. Log in to Klutch.sh

      Navigate to klutch.sh/app and sign in to your account.

    2. Create a New Project

      Go to Create Project and give your project a meaningful name (e.g., “Corteza Business Platform”).

    3. Create a New App

      Navigate to Create App and configure the following settings:

    4. Select Your Repository

      • Choose GitHub as your Git source
      • Select the repository containing your Dockerfile
      • Choose the branch you want to deploy (usually main or master)

    5. Configure Traffic Type

      • Traffic Type: Select HTTP (Corteza is a web application that serves HTTP traffic)
      • Internal Port: Set to 80 (the port your Corteza container listens on)

    6. Set Environment Variables

      Add the following environment variables for your Corteza configuration:

      • DB_DSN: Your PostgreSQL connection string (format: postgres://username:password@your-db-host:8000/corteza?sslmode=disable)
      • AUTH_JWT_SECRET: A long, random string for JWT token signing (generate a secure random string)
      • CORTEZA_BASE_URL: Set to your Klutch.sh app URL (e.g., https://example-app.klutch.sh)
      • HTTP_ADDR: Set to 0.0.0.0:80 to listen on all interfaces
      • AUTH_SESSION_LIFETIME: (Optional) Session lifetime, e.g., 24h
      • AUTH_SESSION_PERM_LIFETIME: (Optional) Permanent session lifetime, e.g., 720h

      Security Note: Always use strong, unique secrets for production deployments. Use a password generator for the AUTH_JWT_SECRET.

    7. Attach a Persistent Volume

      Corteza may need persistent storage for file uploads and certain configuration data:

      • In the Volumes section, click “Add Volume”
      • Mount Path: Enter /corteza/data (this is where Corteza stores uploaded files and attachments)
      • Size: Choose an appropriate size based on your expected data volume (e.g., 10GB, 20GB, etc.)

      Important: Persistent storage ensures your uploaded files and data persist across deployments and restarts.

    8. Configure Additional Settings

      • Region: Select the region closest to your users for optimal latency
      • Compute Resources: Choose CPU and memory based on your workload (minimum 1GB RAM recommended for small deployments)
      • Instances: Start with 1 instance (you can scale later as needed)

    9. Deploy Your Application

      Click “Create” to start the deployment. Klutch.sh will:

      • Automatically detect your Dockerfile in the repository root
      • Build the Docker image
      • Attach the persistent volume
      • Start your Corteza container
      • Assign a URL for external access

    10. Access Your Corteza Platform

      Once deployment is complete, you’ll receive a URL like example-app.klutch.sh. Visit this URL in your browser to access your Corteza installation and complete the initial setup wizard.

Production Best Practices

Security Recommendations

  • Strong JWT Secret: Use a cryptographically secure random string of at least 32 characters for AUTH_JWT_SECRET
  • Environment Variables: Store all sensitive credentials as environment variables in Klutch.sh, never in your Dockerfile or code
  • HTTPS Only: Klutch.sh provides HTTPS by default - ensure your CORTEZA_BASE_URL uses https://
  • Database Security: Use strong database passwords and consider restricting database access to only your Corteza application
  • Regular Updates: Keep Corteza updated to the latest stable version to receive security patches
  • User Access Control: Implement proper role-based access control (RBAC) within Corteza for your users

Performance Optimization

  • Database Indexing: Ensure your PostgreSQL database has proper indexes for frequently queried fields
  • Resource Allocation: Monitor your application performance and adjust compute resources as needed
  • Caching: Configure Corteza’s built-in caching mechanisms for improved performance
  • Connection Pooling: Use database connection pooling for better resource utilization
  • Static Asset Delivery: Consider using a CDN for static assets in high-traffic scenarios

Database Configuration

Corteza works best with PostgreSQL. Key database recommendations:

  • Version: Use PostgreSQL 13 or later for optimal compatibility
  • Backup Strategy: Implement regular automated backups of your database
  • Connection Limits: Configure appropriate connection limits based on your expected concurrent users
  • Maintenance: Schedule regular VACUUM and ANALYZE operations for optimal database performance

Monitoring and Maintenance

Monitor your Corteza deployment for:

  • Application response times and error rates
  • Database connection pool utilization
  • Disk usage (especially for the persistent volume)
  • CPU and memory utilization
  • User activity and concurrent sessions

Set up alerts for:

  • High error rates or application crashes
  • Disk space approaching capacity
  • Elevated response times
  • Failed database connections

Troubleshooting

Cannot Access Corteza Web Interface

  • Verify that the deployment completed successfully in the Klutch.sh dashboard
  • Check that the internal port is correctly set to 80
  • Ensure HTTP traffic type is selected
  • Review application logs for any startup errors

Database Connection Errors

  • Verify your DB_DSN environment variable is correctly formatted
  • Ensure your database is accessible from your Corteza app
  • Check that database credentials are correct
  • Verify the database host uses port 8000 if it’s deployed on Klutch.sh

JWT Token Errors

  • Ensure AUTH_JWT_SECRET is set and is a sufficiently long random string
  • If you changed the secret after initial setup, existing sessions will be invalidated
  • Never commit the JWT secret to your repository

File Upload Issues

  • Verify that the persistent volume is correctly mounted at /corteza/data
  • Check that the volume has sufficient space allocated
  • Review file size limits in your Corteza configuration

Performance Issues

  • Review your compute resource allocation and increase if necessary
  • Check database performance and optimize slow queries
  • Monitor memory usage - Corteza may need more than the minimum 1GB for larger deployments
  • Consider scaling to multiple instances if CPU is a bottleneck

Additional Resources

Conclusion

Deploying Corteza to Klutch.sh with Docker provides a robust, scalable platform for building and running your business applications. By following this guide, you’ve set up a production-ready Corteza installation with proper data persistence, security configurations, and connection capabilities. Your platform is now ready to support custom CRM systems, workflow automation, and integrated business processes.

For advanced configurations, you can explore Corteza’s extensive customization options, build custom modules with the Low-Code composer, or integrate with external services through workflows and API connections.