Deploying ChartDB

ChartDB is an open-source database design and visualization platform that enables teams to collaborate on database schemas in real-time. It provides an intuitive visual interface for creating, editing, and sharing database designs, with support for multiple database systems including PostgreSQL, MySQL, MongoDB, and more. ChartDB simplifies complex database architecture planning and documentation for developers, database administrators, and technical architects.

This guide will walk you through deploying ChartDB on Klutch.sh, a modern cloud platform that simplifies containerized application deployment. By the end of this guide, you’ll have a fully functional ChartDB instance ready for your team’s database design collaboration.

Why Deploy ChartDB on Klutch.sh?

Klutch.sh provides an excellent platform for hosting ChartDB:

Docker-native deployment - Klutch.sh automatically detects and deploys Dockerized applications
Real-time collaboration - Enable your team to design databases together with persistent storage
Custom domains - Point your domain to your ChartDB instance for team access
Environment configuration - Manage secrets and configuration through the dashboard
Data persistence - Attach volumes for database designs and user data
Scalability - Easily scale resources as your team grows

Prerequisites

Before deploying ChartDB on Klutch.sh, you’ll need:

A Klutch.sh account (sign up for free)
Access to the Klutch.sh dashboard
A GitHub repository to store your ChartDB deployment configuration
A custom domain (optional but recommended for team collaboration)
Basic understanding of Docker and containerization

Deployment Steps

Create a Dockerfile

Create a Dockerfile in the root of your repository to containerize ChartDB:

FROM node:20-alpine

# Install system dependencies
RUN apk add --no-cache \
    build-base \
    python3 \
    git \
    curl

# Set working directory
WORKDIR /app

# Clone ChartDB repository
RUN git clone https://github.com/chartdb/chartdb.git . && \
    git checkout main

# Install dependencies
RUN npm install

# Build the application
RUN npm run build

# Create necessary directories
RUN mkdir -p /app/data /app/exports

# Expose port
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD node -e "require('http').get('http://localhost:3000/health', (r) => {if (r.statusCode !== 200) throw new Error(r.statusCode)})"

# Start the application
CMD ["npm", "start"]

Create Environment Configuration File

Create a .env.example file to document required environment variables:

# ChartDB Environment Configuration

# Application Settings
NODE_ENV=production
HOST=0.0.0.0
PORT=3000

# Database Configuration
DATABASE_URL=postgresql://chartdb:chartdbpass@localhost:5432/chartdb
DATABASE_HOST=db
DATABASE_PORT=5432
DATABASE_USER=chartdb
DATABASE_PASSWORD=chartdbpass
DATABASE_NAME=chartdb

# Redis Configuration (for sessions and caching)
REDIS_URL=redis://redis:6379

# JWT Configuration
JWT_SECRET=your-jwt-secret-here-change-in-production
JWT_EXPIRATION=7d

# File Upload Configuration
MAX_FILE_SIZE=52428800
UPLOAD_DIR=/app/data
EXPORT_DIR=/app/exports

# CORS Settings
CORS_ORIGIN=https://example-app.klutch.sh
CORS_CREDENTIALS=true

# Email Configuration (Optional)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM=noreply@example-app.klutch.sh

# Authentication
ENABLE_LOCAL_AUTH=true
ENABLE_OAUTH=false
OAUTH_CLIENT_ID=
OAUTH_CLIENT_SECRET=

# Administration
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=change-me-in-production

# Logging
LOG_LEVEL=info

# Analytics (Optional)
ENABLE_ANALYTICS=false
ANALYTICS_TOKEN=

# API Rate Limiting
RATE_LIMIT_WINDOW=900000
RATE_LIMIT_MAX_REQUESTS=100

Create Application Configuration File

Create a config.js file for application-specific settings:

module.exports = {
  app: {
    name: 'ChartDB',
    version: '1.0.0',
    environment: process.env.NODE_ENV || 'production',
    port: process.env.PORT || 3000,
    host: process.env.HOST || '0.0.0.0'
  },
  database: {
    url: process.env.DATABASE_URL,
    host: process.env.DATABASE_HOST,
    port: parseInt(process.env.DATABASE_PORT) || 5432,
    user: process.env.DATABASE_USER,
    password: process.env.DATABASE_PASSWORD,
    database: process.env.DATABASE_NAME,
    pool: {
      min: 2,
      max: 10,
      idleTimeoutMillis: 30000,
      connectionTimeoutMillis: 2000
    }
  },
  redis: {
    url: process.env.REDIS_URL,
    retryStrategy: (times) => Math.min(times * 50, 2000),
    maxRetriesPerRequest: null
  },
  jwt: {
    secret: process.env.JWT_SECRET,
    expiresIn: process.env.JWT_EXPIRATION || '7d',
    algorithm: 'HS256'
  },
  fileUpload: {
    maxFileSize: parseInt(process.env.MAX_FILE_SIZE) || 52428800,
    uploadDir: process.env.UPLOAD_DIR || '/app/data',
    exportDir: process.env.EXPORT_DIR || '/app/exports',
    allowedMimeTypes: [
      'application/json',
      'application/xml',
      'image/svg+xml',
      'text/plain'
    ]
  },
  cors: {
    origin: process.env.CORS_ORIGIN || 'http://localhost:3000',
    credentials: process.env.CORS_CREDENTIALS === 'true'
  },
  auth: {
    enableLocalAuth: process.env.ENABLE_LOCAL_AUTH === 'true',
    enableOAuth: process.env.ENABLE_OAUTH === 'true',
    oauthClientId: process.env.OAUTH_CLIENT_ID,
    oauthClientSecret: process.env.OAUTH_CLIENT_SECRET
  },
  rateLimit: {
    windowMs: parseInt(process.env.RATE_LIMIT_WINDOW) || 900000,
    max: parseInt(process.env.RATE_LIMIT_MAX_REQUESTS) || 100
  }
};

Create Database Initialization Script

Create an init-db.sh file to set up the PostgreSQL database:

#!/bin/bash

set -e

echo "Initializing ChartDB database..."

# Wait for PostgreSQL to be ready
until PGPASSWORD=$DATABASE_PASSWORD psql -h "$DATABASE_HOST" -U "$DATABASE_USER" -d "postgres" -c "\q"; do
  echo 'Waiting for postgres...'
  sleep 1
done

echo "PostgreSQL is ready!"

# Create database if it doesn't exist
PGPASSWORD=$DATABASE_PASSWORD psql -h "$DATABASE_HOST" -U "$DATABASE_USER" -d "postgres" << EOF
CREATE DATABASE $DATABASE_NAME;
EOF

echo "Database created!"

# Run migrations
echo "Running database migrations..."
npm run migrate

echo "Database initialization complete!"

Make it executable:

chmod +x init-db.sh

Create Docker Compose for Local Development

Create a docker-compose.yml file for local development and testing (not used for Klutch.sh deployment):

version: '3.8'

services:
  chartdb:
    build: .
    container_name: chartdb-dev
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgresql://chartdb:chartdbpass@db:5432/chartdb
      - DATABASE_HOST=db
      - DATABASE_USER=chartdb
      - DATABASE_PASSWORD=chartdbpass
      - DATABASE_NAME=chartdb
      - REDIS_URL=redis://redis:6379
      - JWT_SECRET=dev-secret-key-change-in-production
      - UPLOAD_DIR=/app/data
      - EXPORT_DIR=/app/exports
      - CORS_ORIGIN=http://localhost:3000
      - ADMIN_EMAIL=admin@localhost
      - ADMIN_PASSWORD=admin123
    depends_on:
      - db
      - redis
    volumes:
      - ./data:/app/data
      - ./src:/app/src
    networks:
      - chartdb-network

  db:
    image: postgres:16-alpine
    container_name: chartdb-db
    environment:
      - POSTGRES_USER=chartdb
      - POSTGRES_PASSWORD=chartdbpass
      - POSTGRES_DB=chartdb
    volumes:
      - chartdb_db_data:/var/lib/postgresql/data
    networks:
      - chartdb-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U chartdb"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: chartdb-redis
    networks:
      - chartdb-network
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  chartdb_db_data:

networks:
  chartdb-network:
    driver: bridge

Create .gitignore File

Create a .gitignore file to exclude sensitive data from version control:

# Environment files
.env
.env.local
.env.*.local

# Node.js
node_modules/
npm-debug.log
yarn-error.log
package-lock.json
yarn.lock

# Build artifacts
dist/
build/
.next/
out/

# Data and uploads
data/
exports/
uploads/

# Database
*.sqlite
*.sqlite3

# IDE
.vscode/
.idea/
*.swp
*.swo
*~
.DS_Store

# Logs
logs/
*.log

# Cache
.cache/
.turbo/

Push Configuration to GitHub

Push your repository to GitHub with all configuration files:

git add Dockerfile .env.example config.js init-db.sh \
  docker-compose.yml .gitignore
git commit -m "Initial ChartDB deployment configuration for Klutch.sh"
git push origin main

Deploy on Klutch.sh
1. Navigate to klutch.sh/app and log in to your dashboard
2. Click Create New App
3. Connect your GitHub repository containing the ChartDB deployment files (the Dockerfile will be automatically detected)
4. Configure your application settings:
  - Set your preferred app name
  - Review the detected Dockerfile configuration
  - Select a region for deployment
5. Click Deploy to start the deployment process
6. Monitor the deployment progress in the dashboard
7. Wait for the deployment to complete and your app to become active
Configure Environment Variables
1. In your app dashboard, navigate to Environment Variables section
2. Add all required variables from your .env.example file:
  - DATABASE_URL: Your PostgreSQL connection string
  - REDIS_URL: Your Redis connection string
  - JWT_SECRET: Generate a secure secret with openssl rand -base64 32
  - CORS_ORIGIN: Set to https://example-app.klutch.sh (or your custom domain)
  - ADMIN_EMAIL and ADMIN_PASSWORD: Your administrator credentials
3. Click Save to apply the environment variables
4. Your application will automatically restart with the new configuration
Configure Traffic Routes
1. In your app dashboard, navigate to Traffic settings
2. Select HTTP as the traffic type
3. Set the internal port to 3000 (ChartDB Node.js server default)
4. Configure any custom domain settings if you have a domain
5. Save your traffic configuration
Attach Persistent Volumes
ChartDB requires persistent storage for database designs and exported files.
1. In your app dashboard, navigate to Volumes settings
2. Click Add Volume to create storage for database designs:
  - Enter mount path: /app/data
  - Set volume size to 20GB (adjust based on number of projects)
  - Click Attach to create and mount the volume
3. Click Add Volume again for exported diagrams:
  - Enter mount path: /app/exports
  - Set volume size to 10GB (for exported files and backups)
  - Click Attach to create and mount the volume
Your ChartDB application will now be accessible at your configured domain or at example-app.klutch.sh.

Initial Setup and Configuration

After deploying ChartDB on Klutch.sh, complete the initial setup to prepare your database design collaboration platform.

Access Your ChartDB Instance

Navigate to https://example-app.klutch.sh in your web browser
You’ll see the ChartDB welcome page
Click Sign Up to create your administrator account
Enter your email and set a strong password
Complete the email verification process
Log in to your new ChartDB instance

Configure Your ChartDB Instance

Once logged in, configure these essential settings:

Workspace Settings:

Set your workspace name and description
Configure workspace branding
Set up user roles and permissions
Enable team collaboration features

Database Connections:

Add connections to your production databases
Configure connection strings for PostgreSQL, MySQL, MongoDB
Set up SSL/TLS for secure connections
Test database connectivity

Project Management:

Create projects for different database schemas
Organize projects by team or application
Set project visibility (private, team, public)
Configure project templates

Team Management:

Invite team members to your workspace
Assign roles (Owner, Admin, Editor, Viewer)
Set up team-based project access
Configure audit logging

Set Up User Authentication

To enable team collaboration securely:

In your app dashboard, navigate to Authentication settings
Configure email verification for new users
Set password requirements
Enable two-factor authentication for admins
Configure session timeout policies

Configure Backup Strategy

To protect your database designs:

In your app dashboard, navigate to Database settings
Enable automated daily backups
Set backup retention to at least 7 days
Configure backup notifications
Test backup restoration procedures

Set Up Export Integration (Optional)

For advanced features:

Configure export destinations for database diagrams
Set up automated exports to cloud storage
Enable export formats (SQL, JSON, XML)
Configure scheduled exports

Database Design Best Practices

Organizing Your Schemas

Create separate projects for each major system or application
Use consistent naming conventions across all schemas
Document relationships between different database designs
Maintain version history of schema changes

Collaboration Guidelines

Use comments to document complex relationships
Share read-only access for stakeholders
Use the approval workflow for schema changes
Maintain a changelog for tracking modifications

Performance Optimization

Regularly index frequently queried columns
Archive completed or deprecated schema projects
Optimize query patterns before implementation
Monitor schema complexity metrics

Deployment Best Practices

Security Measures

Keep ChartDB updated to the latest version
Use strong, unique passwords for all accounts
Enable two-factor authentication for administrators
Configure firewall rules to restrict access if needed
Use HTTPS for all communications (automatic with Klutch.sh)
Regularly review user access permissions

Monitoring and Maintenance

Monitor disk usage for design and export storage
Set up alerts for deployment failures
Review logs regularly for errors or security issues
Schedule maintenance windows for updates
Test backup restoration procedures monthly

Scaling Considerations

As your team grows and creates more projects:

Increase volume sizes proactively before running out of space
Monitor database performance and optimize indexes
Archive old or completed projects
Consider implementing database sharding for large schemas
Implement caching strategies for frequently accessed designs

Accessing ChartDB

Once deployment is complete and configured:

Team members access ChartDB at your configured domain or example-app.klutch.sh
Users can create and manage database schema projects
Real-time collaboration enables simultaneous editing
Export functionality allows saving designs in multiple formats
Admin panel provides workspace and user management

Troubleshooting Deployment Issues

Application Won’t Start

Check the following:

Verify all required environment variables are set
Ensure database connection string is correct
Check that Redis is accessible
Review application logs in the dashboard

Database Connection Errors

Steps to resolve:

Verify DATABASE_URL environment variable format
Ensure database is running and accessible
Check database user credentials
Verify network connectivity between services

Storage Issues

Possible solutions:

Verify persistent volumes are properly attached
Check available disk space on volumes
Ensure /app/data directory has write permissions
Archive old projects to free up space

Performance Issues

Optimization steps:

Increase application memory allocation
Enable Redis caching
Optimize database queries
Review and optimize schema files
Consider upgrading to higher performance storage

Advanced Configuration

Environment Variables for Customization

You can customize ChartDB behavior with these environment variables:

# Session Configuration
SESSION_TIMEOUT=3600
SESSION_SECRET=your-session-secret

# Database Connection Pool
DB_POOL_MIN=2
DB_POOL_MAX=10
DB_IDLE_TIMEOUT=30000

# File Upload Restrictions
MAX_FILE_SIZE=52428800
MAX_CONCURRENT_UPLOADS=5

# Feature Flags
ENABLE_REAL_TIME_COLLAB=true
ENABLE_VERSION_HISTORY=true
ENABLE_COMMENTS=true
ENABLE_EXPORTS=true

# Performance Tuning
CACHE_TTL=3600
REDIS_MAX_RETRIES=3
DB_QUERY_TIMEOUT=30000

Custom Domain Setup

To use a custom domain with your ChartDB instance:

In your Klutch.sh dashboard, navigate to Domains
Add your custom domain
Follow the DNS configuration instructions
Update your environment variables with the new domain:
- CORS_ORIGIN=https://your-domain.com
Save and redeploy your application

Import Existing Database Schemas

If importing from another tool or existing databases:

Export your current database schema (DDL scripts)
Upload the SQL file to ChartDB
Use the import feature to create visual representations
Verify all tables and relationships are correctly imported
Share the project with your team

Additional Resources

Learn more about ChartDB and Klutch.sh:

ChartDB GitHub Repository - Source code and contribution guidelines
ChartDB Documentation - Comprehensive platform documentation
ChartDB Issue Tracker - Report bugs and request features
Klutch.sh Official Website - Learn more about the deployment platform
Klutch.sh Documentation - Platform guides and API reference

Conclusion

You now have a fully functional ChartDB instance running on Klutch.sh! Your collaborative database design platform is ready for your team to use for schema planning, visualization, and documentation.

With the robust infrastructure provided by Klutch.sh and the powerful features of ChartDB, you can streamline database design workflows and improve team collaboration. Remember to:

Keep your application updated with the latest ChartDB releases
Monitor system performance and storage usage regularly
Maintain regular backups of your database designs
Follow security best practices for team authentication
Scale your infrastructure as your team and projects grow

For additional support or questions about deploying ChartDB on Klutch.sh, refer to the documentation and community resources linked above.