Deploying Chartbrew

Chartbrew is an open-source web application that enables users to create interactive, real-time dashboards and visualizations from multiple data sources. It supports connections to various databases including PostgreSQL, MySQL, MongoDB, and APIs, making it ideal for business intelligence, data analysis, and performance monitoring. Chartbrew simplifies the process of turning raw data into actionable insights through intuitive visualization tools.

This guide will walk you through deploying Chartbrew on Klutch.sh, a modern cloud platform that simplifies containerized application deployment. By the end of this guide, you’ll have a fully functional Chartbrew instance ready for your team’s data visualization and analytics needs.

Why Deploy Chartbrew on Klutch.sh?

Klutch.sh provides an excellent platform for hosting Chartbrew:

• Docker-native deployment - Klutch.sh automatically detects and deploys Dockerized applications
• Real-time dashboards - Enable your team to create and share data visualizations
• Custom domains - Point your domain to your Chartbrew instance for team access
• Environment configuration - Manage secrets and configuration through the dashboard
• Data persistence - Attach volumes for dashboards, databases, and user data
• Scalability - Easily scale resources as your analytics needs grow

Prerequisites

Before deploying Chartbrew 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 Chartbrew deployment configuration
• A custom domain (optional but recommended for team access)
• Basic understanding of Docker and containerization

Deployment Steps

1. Create a Dockerfile

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

   FROM node:20-alpine
   
   # Install system dependencies
   RUN apk add --no-cache \
       build-base \
       python3 \
       git \
       curl \
       cairo-dev \
       jpeg-dev \
       pango-dev \
       giflib-dev
   
   # Set working directory
   WORKDIR /app
   
   # Clone Chartbrew repository
   RUN git clone https://github.com/chartbrew/chartbrew.git . && \
       git checkout main
   
   # Install dependencies for client and server
   RUN npm install
   
   # Build the client application
   WORKDIR /app/client
   RUN npm run build
   
   # Move back to root directory
   WORKDIR /app
   
   # Create necessary directories
   RUN mkdir -p /app/uploads /app/data /app/logs
   
   # Expose ports
   EXPOSE 3000 3210
   
   # 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", "run", "start:prod"]

2. Create Environment Configuration File

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

   # Chartbrew Environment Configuration
   
   # Application Settings
   NODE_ENV=production
   PORT=3000
   API_PORT=3210
   
   # Server Configuration
   HOST=0.0.0.0
   REACT_APP_API_HOST=https://example-app.klutch.sh
   
   # Database Configuration
   DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=chartbrew
   DB_USER=chartbrew
   DB_PASSWORD=chartbrewpass
   DATABASE_URL=postgresql://chartbrew:chartbrewpass@localhost:5432/chartbrew
   
   # Session Management
   SESSION_SECRET=your-session-secret-change-in-production
   SESSION_TIMEOUT=86400
   
   # JWT Configuration
   JWT_SECRET=your-jwt-secret-change-in-production
   JWT_EXPIRATION=7d
   
   # File Upload Configuration
   MAX_FILE_SIZE=52428800
   UPLOAD_DIR=/app/uploads
   
   # Redis Configuration (for caching and sessions)
   REDIS_URL=redis://redis:6379
   REDIS_DB=0
   
   # 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_SIGNUP=true
   ENABLE_LOCAL_AUTH=true
   ENABLE_OAUTH=false
   
   # Google OAuth (Optional)
   GOOGLE_CLIENT_ID=
   GOOGLE_CLIENT_SECRET=
   
   # Monitoring and Analytics
   SENTRY_DSN=
   LOG_LEVEL=info
   
   # API Rate Limiting
   RATE_LIMIT_WINDOW=900000
   RATE_LIMIT_MAX_REQUESTS=100
   
   # CORS Settings
   CORS_ORIGIN=https://example-app.klutch.sh
   CORS_CREDENTIALS=true
   
   # Security
   SECURE_COOKIES=true
   HTTPS_REDIRECT=true

3. Create Application Configuration File

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

   module.exports = {
     app: {
       name: 'Chartbrew',
       version: '1.0.0',
       environment: process.env.NODE_ENV || 'production',
       port: process.env.PORT || 3000,
       apiPort: process.env.API_PORT || 3210,
       host: process.env.HOST || '0.0.0.0'
     },
     server: {
       apiHost: process.env.REACT_APP_API_HOST || 'http://localhost:3000',
       ssl: process.env.HTTPS_REDIRECT === 'true'
     },
     database: {
       host: process.env.DB_HOST,
       port: parseInt(process.env.DB_PORT) || 5432,
       user: process.env.DB_USER,
       password: process.env.DB_PASSWORD,
       database: process.env.DB_NAME,
       url: process.env.DATABASE_URL,
       pool: {
         min: 2,
         max: 10,
         idleTimeoutMillis: 30000,
         connectionTimeoutMillis: 2000
       }
     },
     redis: {
       url: process.env.REDIS_URL,
       db: parseInt(process.env.REDIS_DB) || 0,
       retryStrategy: (times) => Math.min(times * 50, 2000),
       maxRetriesPerRequest: null
     },
     session: {
       secret: process.env.SESSION_SECRET,
       timeout: parseInt(process.env.SESSION_TIMEOUT) || 86400,
       cookie: {
         secure: process.env.SECURE_COOKIES === 'true',
         httpOnly: true,
         sameSite: 'lax'
       }
     },
     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/uploads',
       allowedMimeTypes: [
         'application/json',
         'text/csv',
         'application/vnd.ms-excel',
         'text/plain'
       ]
     },
     cors: {
       origin: process.env.CORS_ORIGIN || 'http://localhost:3000',
       credentials: process.env.CORS_CREDENTIALS === 'true'
     },
     auth: {
       enableSignup: process.env.ENABLE_SIGNUP === 'true',
       enableLocalAuth: process.env.ENABLE_LOCAL_AUTH === 'true',
       enableOAuth: process.env.ENABLE_OAUTH === 'true',
       googleClientId: process.env.GOOGLE_CLIENT_ID,
       googleClientSecret: process.env.GOOGLE_CLIENT_SECRET
     },
     email: {
       host: process.env.SMTP_HOST,
       port: parseInt(process.env.SMTP_PORT) || 587,
       user: process.env.SMTP_USER,
       password: process.env.SMTP_PASSWORD,
       from: process.env.SMTP_FROM || 'noreply@chartbrew.local'
     },
     rateLimit: {
       windowMs: parseInt(process.env.RATE_LIMIT_WINDOW) || 900000,
       max: parseInt(process.env.RATE_LIMIT_MAX_REQUESTS) || 100
     }
   };

4. Create Database Initialization Script

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

   #!/bin/bash
   
   set -e
   
   echo "Initializing Chartbrew database..."
   
   # Wait for PostgreSQL to be ready
   until PGPASSWORD=$DB_PASSWORD psql -h "$DB_HOST" -U "$DB_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=$DB_PASSWORD psql -h "$DB_HOST" -U "$DB_USER" -d "postgres" << EOF
   CREATE DATABASE $DB_NAME;
   EOF
   
   echo "Database created!"
   
   # Run migrations
   echo "Running database migrations..."
   npm run migrate
   
   echo "Database initialization complete!"
   
   # Run seeders (optional)
   echo "Seeding initial data..."
   npm run seed || true
   
   echo "Setup complete!"

   Make it executable:

   chmod +x init-db.sh

5. 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:
     chartbrew:
       build: .
       container_name: chartbrew-dev
       ports:
         - "3000:3000"
         - "3210:3210"
       environment:
         - NODE_ENV=development
         - DB_HOST=db
         - DB_PORT=5432
         - DB_NAME=chartbrew
         - DB_USER=chartbrew
         - DB_PASSWORD=chartbrewpass
         - DATABASE_URL=postgresql://chartbrew:chartbrewpass@db:5432/chartbrew
         - REDIS_URL=redis://redis:6379
         - SESSION_SECRET=dev-secret-key-change-in-production
         - JWT_SECRET=dev-jwt-secret-change-in-production
         - REACT_APP_API_HOST=http://localhost:3000
         - CORS_ORIGIN=http://localhost:3000
         - ENABLE_SIGNUP=true
       depends_on:
         - db
         - redis
       volumes:
         - ./uploads:/app/uploads
         - ./src:/app/src
       networks:
         - chartbrew-network
   
     db:
       image: postgres:16-alpine
       container_name: chartbrew-db
       environment:
         - POSTGRES_USER=chartbrew
         - POSTGRES_PASSWORD=chartbrewpass
         - POSTGRES_DB=chartbrew
       volumes:
         - chartbrew_db_data:/var/lib/postgresql/data
       networks:
         - chartbrew-network
       healthcheck:
         test: ["CMD-SHELL", "pg_isready -U chartbrew"]
         interval: 10s
         timeout: 5s
         retries: 5
   
     redis:
       image: redis:7-alpine
       container_name: chartbrew-redis
       networks:
         - chartbrew-network
       healthcheck:
         test: ["CMD", "redis-cli", "ping"]
         interval: 10s
         timeout: 5s
         retries: 5
   
   volumes:
     chartbrew_db_data:
   
   networks:
     chartbrew-network:
       driver: bridge

6. 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/
   client/build/
   
   # Uploads and data
   uploads/
   data/
   public/uploads/
   
   # Database
   *.sqlite
   *.sqlite3
   
   # IDE
   .vscode/
   .idea/
   *.swp
   *.swo
   *~
   .DS_Store
   
   # Logs
   logs/
   *.log
   
   # Cache
   .cache/
   .turbo/

7. 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 Chartbrew deployment configuration for Klutch.sh"
   git push origin main

8. 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 Chartbrew 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

9. Configure Environment Variables

   1. In your app dashboard, navigate to Environment Variables section
   2. Add all required variables from your .env.example file:
      • DB_HOST: Your PostgreSQL hostname
      • DB_NAME: Database name (chartbrew)
      • DB_USER: Database user
      • DB_PASSWORD: Secure database password
      • DATABASE_URL: Full PostgreSQL connection string
      • REDIS_URL: Your Redis connection string
      • JWT_SECRET: Generate a secure secret with openssl rand -base64 32
      • SESSION_SECRET: Generate a secure session secret
      • REACT_APP_API_HOST: Set to https://example-app.klutch.sh (or your custom domain)
      • CORS_ORIGIN: Set to https://example-app.klutch.sh (or your custom domain)
   3. Click Save to apply the environment variables
   4. Your application will automatically restart with the new configuration

10. 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 (Chartbrew frontend server default)
    4. Configure any custom domain settings if you have a domain
    5. Save your traffic configuration

11. Attach Persistent Volumes

    Chartbrew requires persistent storage for uploaded files, databases, and application data.

    1. In your app dashboard, navigate to Volumes settings
    2. Click Add Volume to create storage for uploaded data:
       • Enter mount path: /app/uploads
       • Set volume size to 50GB (adjust based on expected file uploads)
       • Click Attach to create and mount the volume
    3. Click Add Volume again for application logs:
       • Enter mount path: /app/logs
       • Set volume size to 10GB
       • Click Attach to create and mount the volume

    Your Chartbrew application will now be accessible at your configured domain or at example-app.klutch.sh.

Initial Setup and Configuration

After deploying Chartbrew on Klutch.sh, complete the initial setup to prepare your data visualization platform.

Access Your Chartbrew Instance

1. Navigate to https://example-app.klutch.sh in your web browser
2. You’ll see the Chartbrew login page
3. Click Sign Up to create your first administrator account
4. Enter your email and set a strong password
5. Complete the email verification process
6. Log in to your new Chartbrew instance

Configure Your Chartbrew Instance

Once logged in, configure these essential settings:

Workspace Settings:

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

Data Source Connections:

• Add connections to your data sources (PostgreSQL, MySQL, MongoDB, APIs)
• Configure connection strings and credentials
• Test each connection to ensure accessibility
• Set up SSL/TLS for secure connections

Dashboard Creation:

• Create your first dashboard for testing
• Add various chart types (bar, line, pie, table, etc.)
• Connect charts to your data sources
• Configure chart filters and parameters
• Set up real-time data refresh intervals

Team Management:

• Invite team members to your workspace
• Assign roles (Owner, Editor, Viewer)
• Configure project access permissions
• Set up audit logging for compliance

Set Up User Authentication

To enable secure team collaboration:

1. In your app dashboard, navigate to Authentication settings
2. Configure email verification for new users
3. Set password requirements and complexity rules
4. Enable two-factor authentication for administrators
5. Configure session timeout policies

Configure Backup Strategy

To protect your dashboards and configurations:

1. In your app dashboard, navigate to Database settings
2. Enable automated daily backups
3. Set backup retention to at least 7 days
4. Configure backup notifications to your email
5. Test backup restoration procedures

Set Up Scheduled Reports (Optional)

For advanced analytics features:

1. Configure email settings for report delivery
2. Set up scheduled dashboard exports
3. Configure report recipients and frequency
4. Enable automated data snapshot exports
5. Set up alert thresholds for anomaly detection

Dashboard Creation Best Practices

Organizing Your Dashboards

• Create separate dashboards for different departments or metrics
• Use consistent naming conventions for easy navigation
• Group related charts and metrics together
• Establish a dashboard hierarchy for complex setups

Data Connection Best Practices

• Use database views to simplify complex queries
• Implement proper indexing on frequently queried columns
• Use connection pooling for better performance
• Secure sensitive credentials using environment variables

Chart Configuration

• Choose appropriate chart types for your data
• Use meaningful labels and titles
• Configure color schemes for visual consistency
• Set up interactive filters for data exploration
• Enable drill-down capabilities for detailed analysis

Deployment Best Practices

Security Measures

• Keep Chartbrew 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
• Encrypt sensitive data connections

Monitoring and Maintenance

• Monitor disk usage for uploads and logs
• Set up alerts for deployment failures
• Review logs regularly for errors or security issues
• Schedule maintenance windows for updates
• Test backup restoration procedures monthly
• Monitor database query performance

Scaling Considerations

As your analytics needs grow:

• Increase volume sizes proactively before running out of space
• Monitor database performance and optimize queries
• Implement caching strategies for frequently accessed data
• Consider query optimization for large datasets
• Archive completed projects and old dashboards

Accessing Chartbrew

Once deployment is complete and configured:

1. Users access Chartbrew at your configured domain or example-app.klutch.sh
2. Users can create projects and dashboards
3. Real-time data visualization and exploration
4. Scheduled report generation and delivery
5. Export functionality for dashboards and charts
6. Admin panel for workspace 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
• Verify client build completed successfully

Database Connection Errors

Steps to resolve:

• Verify DATABASE_URL environment variable format
• Ensure database is running and accessible
• Check database user credentials and permissions
• Verify network connectivity between services
• Test database connectivity from application logs

Dashboard Loading Issues

Possible solutions:

• Verify data source connections are active
• Check query performance and timeouts
• Review browser console for JavaScript errors
• Verify API responses with network inspection
• Check user permissions for data source access

Performance Issues

Optimization steps:

• Increase application memory allocation
• Enable Redis caching for frequently accessed data
• Optimize database queries and add indexes
• Implement pagination for large datasets
• Consider query result caching

Advanced Configuration

Environment Variables for Customization

You can customize Chartbrew behavior with these environment variables:

# Data Query Settings
QUERY_TIMEOUT=30000
MAX_QUERY_SIZE=1000000

# Cache Configuration
CACHE_TTL=3600
CACHE_ENABLED=true

# 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_CHARTS=true
ENABLE_EXPORTS=true
ENABLE_SCHEDULED_REPORTS=true
ENABLE_ANOMALY_DETECTION=false

# Performance Tuning
REDIS_MAX_RETRIES=3
DB_QUERY_TIMEOUT=30000
API_RATE_LIMIT=100

Custom Domain Setup

To use a custom domain with your Chartbrew instance:

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

Integrating External Data Sources

To add connections to various databases:

1. In Chartbrew dashboard, navigate to Data Sources
2. Click Add New Data Source
3. Select your database type (PostgreSQL, MySQL, MongoDB, etc.)
4. Enter connection credentials and test connectivity
5. Configure query limits and timeout settings
6. Save the data source for use in dashboards

Additional Resources

Learn more about Chartbrew and Klutch.sh:

• Chartbrew GitHub Repository - Source code and contribution guidelines
• Chartbrew Documentation - Comprehensive platform documentation
• Chartbrew 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 Chartbrew instance running on Klutch.sh! Your collaborative data visualization and analytics platform is ready for your team to explore and analyze data.

With the robust infrastructure provided by Klutch.sh and the powerful features of Chartbrew, you can create compelling dashboards and gain insights from your data. Remember to:

• Keep your application updated with the latest Chartbrew releases
• Monitor system performance and storage usage regularly
• Maintain regular backups of your dashboards and configurations
• Follow security best practices for data access
• Scale your infrastructure as your data volume grows

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

Tip

Start by connecting to a single data source and creating sample dashboards to familiarize your team with Chartbrew’s features before expanding to multiple data sources and complex analytics scenarios. Gradually scale your infrastructure based on actual usage patterns and data volume.