Skip to content
Klutch.sh Docs

Deploying an APITable App

Introduction

APITable is a powerful open-source, API-first alternative to Airtable that combines the simplicity of spreadsheets with the power of a visual database. Built with modern technologies including Node.js and React, APITable enables teams to build collaborative applications, manage complex data relationships, and automate workflows without writing code. Whether you’re managing projects, tracking customers, organizing content, or building internal tools, APITable provides a flexible, self-hosted solution with complete control over your data.

APITable stands out for its:

  • API-First Architecture: RESTful API and real-time updates via WebSocket for seamless integrations
  • Visual Database Interface: Spreadsheet-like UI with powerful database capabilities including views, filtering, and sorting
  • Collaborative Features: Real-time collaboration, permissions management, and team workspaces
  • Rich Field Types: Support for attachments, formulas, links to other records, single/multiple select, dates, and more
  • Automation Ready: Webhook support and API access for building automated workflows
  • Self-Hosted Control: Complete data ownership and privacy with flexible deployment options
  • Extensible Platform: Plugin system and widget framework for custom functionality
  • Multi-Database Support: Compatible with MySQL, PostgreSQL, and MariaDB

This comprehensive guide walks you through deploying APITable on Klutch.sh using Docker, with detailed instructions for installation, configuration, persistent storage setup, database connectivity, and production-ready best practices. By the end of this guide, you’ll have a fully functional APITable instance ready for team collaboration.

Prerequisites

Before you begin deploying APITable, ensure you have the following:

  • A Klutch.sh account
  • A GitHub account with a repository for your APITable project
  • Docker installed locally for testing (optional but recommended)
  • Basic understanding of Docker, databases, and environment variables
  • A MySQL, MariaDB, or PostgreSQL database instance (can be deployed separately on Klutch.sh or use an external service)

Installation and Setup

Step 1: Create Your Project Directory

Start by creating a new directory for your APITable deployment:

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

This directory will contain your Dockerfile and configuration files needed for deployment.

Step 2: Create the Dockerfile

Create a Dockerfile in your project root directory. This Dockerfile sets up the complete APITable environment with all necessary dependencies:

FROM node:18-bullseye-slim


# Install system dependencies
RUN apt-get update && apt-get install -y \
    curl \
    wget \
    git \
    python3 \
    make \
    g++ \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*


# Set working directory
WORKDIR /app


# Clone APITable repository (using a specific version for stability)
RUN git clone --depth 1 --branch main https://github.com/apitable/apitable.git . || \
    git clone --depth 1 https://github.com/apitable/apitable.git .


# Install dependencies
RUN npm install --production


# Create necessary directories for uploads and data
RUN mkdir -p /app/data/uploads /app/data/assets


# Expose the default APITable port
EXPOSE 8080


# Set environment variables (override these in Klutch.sh)
ENV NODE_ENV=production
ENV PORT=8080


# Start APITable
CMD ["npm", "start"]

Note: This Dockerfile provides a basic setup. For a production environment with specific version pinning and optimizations, see the advanced configuration section below.

Step 3: Advanced Production Dockerfile

For production deployments with better caching, security, and performance:

FROM node:18-bullseye-slim AS builder


# Install build dependencies
RUN apt-get update && apt-get install -y \
    curl \
    wget \
    git \
    python3 \
    make \
    g++ \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*


WORKDIR /app


# Clone APITable at a specific commit for reproducibility
ARG APITABLE_VERSION=main
RUN git clone --depth 1 --branch ${APITABLE_VERSION} https://github.com/apitable/apitable.git .


# Install dependencies
RUN npm ci --production --no-audit --no-fund


# Production stage
FROM node:18-bullseye-slim


# Install runtime dependencies only
RUN apt-get update && apt-get install -y \
    curl \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*


WORKDIR /app


# Copy application from builder
COPY --from=builder /app /app


# Create data directories
RUN mkdir -p /app/data/uploads /app/data/assets && \
    chown -R node:node /app


# Switch to non-root user for security
USER node


# Expose APITable port
EXPOSE 8080


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD curl -f http://localhost:8080/health || exit 1


ENV NODE_ENV=production
ENV PORT=8080


CMD ["npm", "start"]

Step 4: Create Environment Configuration File

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

Terminal window
# APITable Configuration


# Database Configuration (MySQL, MariaDB, or PostgreSQL)
DATABASE_TYPE=mysql
DATABASE_HOST=mysql-host.klutch.sh
DATABASE_PORT=3306
DATABASE_NAME=apitable
DATABASE_USERNAME=apitable_user
DATABASE_PASSWORD=your-secure-password


# Redis Configuration (for caching and sessions)
REDIS_HOST=redis-host.klutch.sh
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password
REDIS_DB=0


# APITable Application Settings
API_BASE_URL=https://example-app.klutch.sh
FRONTEND_URL=https://example-app.klutch.sh
CORS_ORIGINS=https://example-app.klutch.sh


# Security Configuration
JWT_SECRET=your-generated-jwt-secret-minimum-32-characters
SESSION_SECRET=your-generated-session-secret-minimum-32-characters


# Storage Configuration
STORAGE_TYPE=local
STORAGE_PATH=/app/data/uploads


# Email Configuration (Optional - for notifications and invitations)
MAIL_TYPE=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=noreply@example.com
MAIL_PASSWORD=your-email-password
MAIL_FROM=APITable <noreply@example.com>


# Application Settings
NODE_ENV=production
PORT=8080
LOG_LEVEL=info

Security Warning: Never commit actual passwords or secrets to your repository. Use Klutch.sh environment variables for all sensitive values.

Step 5: Create Database Initialization Script (Optional)

Create a init-db.sql file for MySQL/MariaDB database initialization:

-- Create APITable database
CREATE DATABASE IF NOT EXISTS apitable CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;


-- Create APITable user
CREATE USER IF NOT EXISTS 'apitable_user'@'%' IDENTIFIED BY 'your-secure-password';


-- Grant privileges
GRANT ALL PRIVILEGES ON apitable.* TO 'apitable_user'@'%';
FLUSH PRIVILEGES;

For PostgreSQL, create init-db.sql:

-- Create APITable database
CREATE DATABASE apitable;


-- Create APITable user
CREATE USER apitable_user WITH PASSWORD 'your-secure-password';


-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE apitable TO apitable_user;

Step 6: Test Locally with Docker Compose (Optional)

For local testing before deploying to Klutch.sh, create a docker-compose.yml file:

version: '3.8'


services:
  apitable:
    build: .
    ports:
      - "8080:8080"
    environment:
      - DATABASE_TYPE=mysql
      - DATABASE_HOST=mysql
      - DATABASE_PORT=3306
      - DATABASE_NAME=apitable
      - DATABASE_USERNAME=apitable_user
      - DATABASE_PASSWORD=apitable_pass
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - JWT_SECRET=local-development-jwt-secret-change-in-production
      - SESSION_SECRET=local-development-session-secret-change-in-production
      - API_BASE_URL=http://localhost:8080
      - FRONTEND_URL=http://localhost:8080
    depends_on:
      - mysql
      - redis
    volumes:
      - apitable-data:/app/data


  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=rootpass
      - MYSQL_DATABASE=apitable
      - MYSQL_USER=apitable_user
      - MYSQL_PASSWORD=apitable_pass
    volumes:
      - mysql-data:/var/lib/mysql
    command: --default-authentication-plugin=mysql_native_password


  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data


volumes:
  apitable-data:
  mysql-data:
  redis-data:

Test locally:

Terminal window
# Build and start services
docker-compose up -d


# View logs
docker-compose logs -f apitable


# Access APITable at http://localhost:8080


# Stop services when done
docker-compose down

Note: Docker Compose is for local development only. Klutch.sh does not support Docker Compose for deployment.

Step 7: Create Documentation

Create a README.md file with deployment instructions:

# APITable Deployment on Klutch.sh


This repository contains the configuration for deploying APITable on Klutch.sh.


## Quick Start


1. Deploy database and Redis on Klutch.sh or use external services
2. Configure environment variables in Klutch.sh dashboard
3. Deploy this repository to Klutch.sh
4. Access your APITable instance at the provided URL


## Environment Variables


See `.env.example` for required environment variables.


## Documentation


For detailed deployment instructions, see the <a href="https://docs.klutch.sh/guides/open-source-software/apitable?utm_source=docs" target="_blank">Klutch.sh APITable guide</a>.

Step 8: Push to GitHub

Commit your files and push to GitHub:

Terminal window
# Add files
git add Dockerfile .env.example README.md docker-compose.yml


# Commit
git commit -m "Add APITable Dockerfile and configuration"


# Add remote and push
git remote add origin https://github.com/yourusername/apitable-klutch.git
git push -u origin main

Important: Do not commit .env files with actual secrets. Only commit .env.example as a template.

Deploying to Klutch.sh

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

Prerequisites for Deployment

Before deploying APITable, you’ll need:

  1. Database Instance: Deploy MySQL, MariaDB, or PostgreSQL. You can:

  2. Redis Instance: Deploy Redis for caching and session management. You can:

Deployment Steps

    1. Log in to Klutch.sh

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

    2. Deploy Database and Redis (if not using external services)

      Before deploying APITable, set up your database and Redis instances:

      For MySQL/MariaDB:

      • Create a new app in Klutch.sh
      • Use the official MySQL 8.0 or MariaDB Docker image
      • Configure TCP traffic type with internal port 3306
      • Attach a persistent volume to /var/lib/mysql for database storage
      • Note the connection details (hostname will be [app-name].klutch.sh:8000)

      For Redis:

      • Create a new app in Klutch.sh
      • Use the official Redis 7 Alpine Docker image
      • Configure TCP traffic type with internal port 6379
      • Optionally attach a persistent volume to /data for persistence
      • Note the connection details

    3. Create a New Project for APITable

      Go to your Klutch.sh dashboard and create a new project (e.g., “APITable Production”).

    4. Create a New App

      Click to create a new app and configure the following settings:

    5. Select Your Repository

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

    6. Configure Traffic Type

      • Traffic Type: Select HTTP (APITable serves a web interface via HTTP)
      • Internal Port: Set to 8080 (the default port that APITable listens on)

    7. Set Environment Variables

      Add all required environment variables for your APITable configuration. Click “Add Environment Variable” for each of the following:

      Database Configuration:

      • DATABASE_TYPE: Set to mysql, mariadb, or postgres
      • DATABASE_HOST: Your database hostname (e.g., mysql-app.klutch.sh for TCP or external hostname)
      • DATABASE_PORT: Database port (3306 for MySQL/MariaDB, 5432 for PostgreSQL, or 8000 for Klutch.sh TCP apps)
      • DATABASE_NAME: Database name (apitable)
      • DATABASE_USERNAME: Database username
      • DATABASE_PASSWORD: Database password (mark as secret)

      Redis Configuration:

      • REDIS_HOST: Redis hostname (e.g., redis-app.klutch.sh or external hostname)
      • REDIS_PORT: Redis port (6379 or 8000 for Klutch.sh TCP apps)
      • REDIS_PASSWORD: Redis password if configured (mark as secret)
      • REDIS_DB: Redis database number (default: 0)

      Application Configuration:

      • API_BASE_URL: Your app URL (e.g., https://example-app.klutch.sh)
      • FRONTEND_URL: Same as API_BASE_URL (e.g., https://example-app.klutch.sh)
      • CORS_ORIGINS: Same as API_BASE_URL or comma-separated list of allowed origins
      • PORT: Set to 8080
      • NODE_ENV: Set to production

      Security Configuration:

      • JWT_SECRET: Generate a strong random string (minimum 32 characters, mark as secret)
      • SESSION_SECRET: Generate a different strong random string (minimum 32 characters, mark as secret)

      Optional Email Configuration:

      • MAIL_TYPE: Set to smtp if using email
      • MAIL_HOST: SMTP server hostname
      • MAIL_PORT: SMTP port (typically 587 or 465)
      • MAIL_USERNAME: SMTP username
      • MAIL_PASSWORD: SMTP password (mark as secret)
      • MAIL_FROM: From address (e.g., APITable <noreply@example.com>)

      Storage Configuration:

      • STORAGE_TYPE: Set to local (for persistent volume storage)
      • STORAGE_PATH: Set to /app/data/uploads

      Generate Secrets: You can generate secure secrets using:

      Terminal window
      # On your local machine
      openssl rand -base64 32

    8. Attach Persistent Volumes

      APITable requires persistent storage for uploaded files and assets:

      Click “Add Volume” and configure:

      • Mount Path: /app/data/uploads
      • Size: Choose appropriate size based on expected usage (recommended: 10GB minimum, 50GB+ for production)

      Optionally add another volume for assets:

      • Mount Path: /app/data/assets
      • Size: 5GB or more

      Important: Persistent volumes are critical for maintaining uploaded files, attachments, and assets across deployments.

    9. Configure Compute Resources

      APITable can be resource-intensive depending on usage:

      • CPU: Minimum 1 CPU, recommended 2+ CPUs for production
      • Memory: Minimum 2GB RAM, recommended 4GB+ RAM for production
      • Instances: Start with 1 instance, scale horizontally as needed

    10. Deploy Your Application

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

      • Detect your Dockerfile automatically
      • Build the Docker image
      • Attach the persistent volumes
      • Configure environment variables
      • Start your APITable container
      • Assign a URL for external access (e.g., https://example-app.klutch.sh)

    11. Monitor Deployment Progress

      Watch the build logs to ensure everything compiles successfully. The initial build may take 5-10 minutes depending on network speed and build complexity.

    12. Access Your APITable Instance

      Once deployment is complete, navigate to your assigned URL (e.g., https://example-app.klutch.sh). You should see the APITable welcome screen.

    13. Create Your First Admin Account

      On first access, APITable will prompt you to create an admin account:

      • Enter your email address
      • Set a strong password
      • Complete the initial setup wizard
      • Create your first workspace

Getting Started with APITable

After successful deployment, here’s how to start using APITable:

Create Your First Workspace

  1. Log in to your APITable instance at https://example-app.klutch.sh
  2. Click “Create Workspace” or use the default workspace
  3. Give your workspace a name (e.g., “My Team” or “Project Management”)
  4. Invite team members via email (requires email configuration)

Create Your First Datasheet

APITable organizes data in “datasheets” which combine spreadsheet simplicity with database power:

  1. In your workspace, click “New Datasheet”
  2. Choose a template or start blank
  3. Add columns with different field types:
    • Text: Single-line or multi-line text
    • Number: Integers, decimals, currency, percentages
    • Date/DateTime: Calendar dates and timestamps
    • Single Select: Choose one option from a list
    • Multiple Select: Choose multiple options from a list
    • Attachment: Upload files and images
    • Link: Link to records in other datasheets
    • Formula: Computed fields using formulas
    • Checkbox: Boolean true/false values
    • Rating: Star ratings
    • Member: Assign team members

Example: Project Management Datasheet

Here’s a sample structure for a project management datasheet:

Columns:

  • Project Name (Text): Name of the project
  • Status (Single Select): Options: “Not Started”, “In Progress”, “Completed”, “On Hold”
  • Priority (Single Select): Options: “Low”, “Medium”, “High”, “Critical”
  • Assigned To (Member): Team member responsible
  • Due Date (Date): Project deadline
  • Budget (Currency): Project budget
  • Progress (Rating): Visual progress indicator
  • Notes (Multi-line Text): Additional information
  • Attachments (Attachment): Related files and documents

Using Views

Create different views of your data:

  1. Grid View: Traditional spreadsheet layout
  2. Gallery View: Card-based visual layout, perfect for images
  3. Kanban View: Drag-and-drop board organized by a single-select field
  4. Gantt View: Timeline view for project scheduling
  5. Calendar View: Display records by date field

API Access

APITable provides a comprehensive REST API for integrations:

  1. Navigate to Settings → API
  2. Generate an API token
  3. Use the API documentation to make requests:
Terminal window
# Get all datasheets in a workspace
curl -X GET 'https://example-app.klutch.sh/api/v1/spaces/{spaceId}/datasheets' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'


# Get records from a datasheet
curl -X GET 'https://example-app.klutch.sh/api/v1/datasheets/{datasheetId}/records' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'


# Create a new record
curl -X POST 'https://example-app.klutch.sh/api/v1/datasheets/{datasheetId}/records' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "records": [
      {
        "fields": {
          "Project Name": "New Project",
          "Status": "Not Started",
          "Priority": "High"
        }
      }
    ]
  }'

Automation with Webhooks

Set up webhooks to trigger actions when data changes:

  1. Go to Datasheet Settings → Webhooks
  2. Click “Create Webhook”
  3. Configure the webhook URL and events to watch
  4. APITable will POST data to your endpoint when triggers fire

Environment Variables Reference

Complete list of APITable environment variables you can configure in Klutch.sh:

Database Configuration

VariableDescriptionRequiredDefaultExample
DATABASE_TYPEDatabase typeYesmysqlmysql, mariadb, postgres
DATABASE_HOSTDatabase hostnameYes-mysql-app.klutch.sh
DATABASE_PORTDatabase portYes33063306, 5432, 8000
DATABASE_NAMEDatabase nameYes-apitable
DATABASE_USERNAMEDatabase userYes-apitable_user
DATABASE_PASSWORDDatabase passwordYes-secure-password
DATABASE_SSLUse SSL connectionNofalsetrue, false

Redis Configuration

VariableDescriptionRequiredDefaultExample
REDIS_HOSTRedis hostnameYes-redis-app.klutch.sh
REDIS_PORTRedis portYes63796379, 8000
REDIS_PASSWORDRedis passwordNo-redis-password
REDIS_DBRedis database numberNo00, 1, 2
REDIS_SSLUse SSL connectionNofalsetrue, false

Application Configuration

VariableDescriptionRequiredDefaultExample
API_BASE_URLBase URL for APIYes-https://example-app.klutch.sh
FRONTEND_URLFrontend URLYes-https://example-app.klutch.sh
CORS_ORIGINSAllowed CORS originsYes-https://example-app.klutch.sh
PORTApplication portNo80808080
NODE_ENVNode environmentNoproductionproduction, development
LOG_LEVELLogging levelNoinfodebug, info, warn, error

Security Configuration

VariableDescriptionRequiredDefaultExample
JWT_SECRETJWT signing secretYes-random-32-char-string
SESSION_SECRETSession signing secretYes-random-32-char-string
COOKIE_DOMAINCookie domainNo-.example.com

Storage Configuration

VariableDescriptionRequiredDefaultExample
STORAGE_TYPEStorage backendNolocallocal, s3, oss
STORAGE_PATHLocal storage pathNo/app/data/uploads/app/data/uploads
AWS_ACCESS_KEY_IDAWS S3 access keyNo-your-key
AWS_SECRET_ACCESS_KEYAWS S3 secret keyNo-your-secret
AWS_REGIONAWS S3 regionNo-us-east-1
AWS_BUCKETAWS S3 bucket nameNo-apitable-uploads

Email Configuration

VariableDescriptionRequiredDefaultExample
MAIL_TYPEEmail service typeNosmtpsmtp
MAIL_HOSTSMTP hostnameNo-smtp.gmail.com
MAIL_PORTSMTP portNo587587, 465
MAIL_USERNAMESMTP usernameNo-user@example.com
MAIL_PASSWORDSMTP passwordNo-your-password
MAIL_FROMFrom addressNo-APITable <noreply@example.com>
MAIL_SECUREUse TLS/SSLNotruetrue, false

Custom Domains and SSL

To use a custom domain with your APITable deployment:

Add Custom Domain

  1. Navigate to your app in the Klutch.sh dashboard
  2. Go to Settings → Domains
  3. Click “Add Domain”
  4. Enter your custom domain (e.g., apitable.yourdomain.com)
  5. Configure your DNS records as instructed:
    • Add a CNAME record pointing to your Klutch.sh app URL
    • Or add an A record pointing to the provided IP address

Update Environment Variables

After adding a custom domain, update these environment variables:

  • API_BASE_URL: https://apitable.yourdomain.com
  • FRONTEND_URL: https://apitable.yourdomain.com
  • CORS_ORIGINS: https://apitable.yourdomain.com

Klutch.sh automatically provisions and manages SSL/TLS certificates for your custom domain.

Production Best Practices

Security Recommendations

  • Strong Secrets: Generate cryptographically secure random strings for JWT_SECRET and SESSION_SECRET (minimum 32 characters)
  • Environment Variables: Store all sensitive credentials as environment variables in Klutch.sh, never commit them to your repository
  • Database Security: Use strong passwords, create dedicated database users with minimal required privileges
  • Regular Updates: Keep APITable, Node.js, and dependencies updated for security patches
  • Access Control: Configure proper workspace and datasheet permissions
  • HTTPS Only: Always use HTTPS URLs and enable HSTS if possible
  • CORS Configuration: Set specific allowed origins instead of * in production
  • Rate Limiting: Monitor API usage and implement rate limiting if needed
  • Backup Strategy: Regular automated backups of database and persistent volumes

Performance Optimization

  • Database Optimization:

    • Use indexed queries for better performance
    • Regular ANALYZE and OPTIMIZE TABLE operations for MySQL
    • Monitor slow queries and add indexes as needed
    • Use connection pooling efficiently

  • Redis Caching:

    • Ensure Redis is properly configured and accessible
    • Monitor Redis memory usage and configure eviction policies
    • Use Redis for session storage to enable horizontal scaling

  • Resource Allocation:

    • Start with 2 CPU cores and 4GB RAM
    • Scale vertically (more resources) or horizontally (more instances) based on usage
    • Monitor CPU, memory, and disk I/O metrics

  • Content Delivery:

    • Consider using a CDN for static assets if serving global users
    • Configure appropriate caching headers for static content
    • Optimize uploaded images and attachments

Database Management

  • Connection Pooling: Ensure proper connection pool sizing:

    Terminal window
    # Add to environment variables if supported
    DATABASE_POOL_SIZE=20
    DATABASE_MAX_CONNECTIONS=100

  • Regular Maintenance:

    • Schedule regular database backups (daily recommended)
    • Monitor database size and plan for growth
    • Archive old datasheets if no longer actively used
    • Optimize tables periodically

  • High Availability:

    • Use managed database services with automated failover
    • Configure read replicas for read-heavy workloads
    • Implement database monitoring and alerting

Monitoring and Logging

Monitor these key metrics:

  • Application Metrics:

    • Response times for API endpoints
    • Error rates and stack traces
    • Memory usage and garbage collection
    • Active connections and sessions

  • Database Metrics:

    • Query performance and slow queries
    • Connection pool utilization
    • Database size and growth rate
    • Replication lag (if using replicas)

  • Infrastructure Metrics:

    • CPU and memory usage
    • Disk I/O and storage usage
    • Network throughput
    • Request rates and status codes

  • Log Management:

    • Centralize logs for easier debugging
    • Set appropriate log levels (use info or warn in production)
    • Configure log rotation to prevent disk space issues
    • Monitor for error patterns and anomalies

Backup and Disaster Recovery

Implement a comprehensive backup strategy:

  1. Database Backups:

    Terminal window
    # MySQL backup example (run as a scheduled job)
    mysqldump -h $DATABASE_HOST -P $DATABASE_PORT \
      -u $DATABASE_USERNAME -p$DATABASE_PASSWORD \
      $DATABASE_NAME > apitable-backup-$(date +%Y%m%d).sql

  2. Volume Snapshots:

    • Regular snapshots of persistent volumes
    • Test restore procedures periodically
    • Store backups in separate location/region

  3. Disaster Recovery Plan:

    • Document recovery procedures
    • Test full recovery process
    • Maintain off-site backups
    • Define Recovery Time Objective (RTO) and Recovery Point Objective (RPO)

Scaling APITable

As your usage grows, you may need to scale your APITable deployment:

Vertical Scaling

Increase resources for your existing instance:

  1. In Klutch.sh dashboard, go to your app settings
  2. Increase CPU cores (2, 4, 8 cores)
  3. Increase memory (4GB, 8GB, 16GB)
  4. Monitor performance improvements

Horizontal Scaling

Run multiple instances of APITable:

  1. Ensure you’re using external Redis for session storage
  2. Use a managed database that supports multiple connections
  3. Configure storage to use object storage (S3, OSS) instead of local volumes
  4. Increase instance count in Klutch.sh
  5. Klutch.sh will automatically load balance traffic

Note: For horizontal scaling, you must use shared storage (S3/OSS) for uploads instead of local volumes.

Database Scaling

For database-intensive workloads:

  1. Read Replicas: Configure read-only database replicas for read operations
  2. Sharding: Partition data across multiple databases (requires application-level support)
  3. Caching: Increase Redis cache size and TTL for frequently accessed data
  4. Optimization: Regularly analyze and optimize database queries

Troubleshooting

Application Won’t Start

Symptoms: App fails to start, shows error in logs

Solutions:

  • Check all required environment variables are set
  • Verify database connection details are correct
  • Ensure database is accessible from your Klutch.sh app
  • Check if database user has proper permissions
  • Review startup logs for specific error messages
  • Verify Dockerfile builds successfully locally

Database Connection Errors

Symptoms: “Unable to connect to database” errors

Solutions:

  • Verify DATABASE_HOST and DATABASE_PORT are correct
  • For Klutch.sh TCP apps, ensure you’re using port 8000
  • Test database connectivity from a debug container
  • Check database credentials are correct
  • Ensure database server is running and accepting connections
  • Verify network connectivity between app and database
  • Check for firewall rules blocking the connection
Terminal window
# Test MySQL connection
mysql -h $DATABASE_HOST -P $DATABASE_PORT -u $DATABASE_USERNAME -p$DATABASE_PASSWORD $DATABASE_NAME


# Test PostgreSQL connection
psql -h $DATABASE_HOST -p $DATABASE_PORT -U $DATABASE_USERNAME -d $DATABASE_NAME

Redis Connection Issues

Symptoms: Session errors, cache failures

Solutions:

  • Verify REDIS_HOST and REDIS_PORT are correct
  • Check Redis password if authentication is enabled
  • Ensure Redis is running and accessible
  • Test connection with redis-cli:
    Terminal window
    redis-cli -h $REDIS_HOST -p $REDIS_PORT -a $REDIS_PASSWORD ping

File Upload Failures

Symptoms: Cannot upload files or attachments

Solutions:

  • Verify persistent volume is attached at /app/data/uploads
  • Check volume has sufficient free space
  • Ensure correct file permissions (directory should be writable)
  • Review STORAGE_TYPE and STORAGE_PATH environment variables
  • Check upload size limits in APITable configuration
  • Review application logs for specific upload errors

Performance Issues

Symptoms: Slow response times, timeouts

Solutions:

  • Monitor CPU and memory usage in Klutch.sh dashboard
  • Check database query performance and add indexes
  • Review Redis cache hit rates
  • Increase compute resources (CPU/memory)
  • Enable database query logging to identify slow queries
  • Consider scaling horizontally with multiple instances
  • Optimize large datasheets by archiving old data

Authentication Problems

Symptoms: Cannot log in, session expires immediately

Solutions:

  • Verify JWT_SECRET and SESSION_SECRET are set
  • Ensure secrets are at least 32 characters long
  • Check cookie domain settings if using custom domain
  • Clear browser cookies and try again
  • Verify Redis is functioning properly for session storage
  • Check system clock is synchronized (JWT tokens are time-sensitive)

API Requests Failing

Symptoms: API returns 401, 403, or CORS errors

Solutions:

  • Verify API token is valid and not expired
  • Check CORS_ORIGINS includes your frontend domain
  • Ensure API_BASE_URL matches your actual domain
  • Review API rate limiting settings
  • Check request headers include proper authentication
  • Verify API endpoint paths are correct

Advanced Configuration

Using Nixpacks Customizations

If you need to customize the build process with Nixpacks, you can use environment variables:

Change Build Command:

Terminal window
NIXPACKS_BUILD_CMD="npm install && npm run build"

Change Start Command:

Terminal window
NIXPACKS_START_CMD="npm start"

Install Additional Packages:

Terminal window
NIXPACKS_PKGS="python3 gcc make"

Add these as environment variables in the Klutch.sh dashboard.

Using Object Storage (S3, OSS)

For production deployments with multiple instances, use object storage:

AWS S3 Configuration:

Terminal window
STORAGE_TYPE=s3
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_REGION=us-east-1
AWS_BUCKET=apitable-uploads

Alibaba Cloud OSS Configuration:

Terminal window
STORAGE_TYPE=oss
OSS_ACCESS_KEY_ID=your-access-key
OSS_ACCESS_KEY_SECRET=your-secret-key
OSS_REGION=oss-us-east-1
OSS_BUCKET=apitable-uploads

Custom Plugins and Widgets

APITable supports custom plugins and widgets:

  1. Create your plugin following the APITable widget documentation
  2. Add plugin files to your repository
  3. Mount plugin directory as a volume or include in Docker image
  4. Configure plugin paths via environment variables

Upgrading APITable

To upgrade APITable to a new version:

Step 1: Update Dockerfile

Update the version in your Dockerfile:

# Change from:
ARG APITABLE_VERSION=main


# To specific version:
ARG APITABLE_VERSION=v1.5.0

Or update the git clone command to use a specific tag.

Step 2: Backup Before Upgrading

Critical: Always backup before upgrading:

Terminal window
# Backup database
mysqldump -h $DATABASE_HOST -P $DATABASE_PORT \
  -u $DATABASE_USERNAME -p$DATABASE_PASSWORD \
  $DATABASE_NAME > apitable-backup-pre-upgrade.sql


# Backup persistent volumes
# Use Klutch.sh dashboard to create volume snapshot

Step 3: Deploy Update

Terminal window
# Commit changes
git add Dockerfile
git commit -m "Upgrade APITable to v1.5.0"
git push


# Klutch.sh will automatically rebuild and redeploy

Step 4: Verify Upgrade

  1. Check application logs for any errors
  2. Test core functionality (login, create datasheet, upload file)
  3. Verify API endpoints are working
  4. Check database migrations completed successfully

Step 5: Rollback if Needed

If issues occur:

  1. Revert Dockerfile changes
  2. Push to GitHub to trigger rebuild
  3. Restore database from backup if necessary
  4. Restore volume snapshot if needed

Additional Resources

Conclusion

Deploying APITable on Klutch.sh with Docker provides a powerful, self-hosted collaborative database platform with complete control over your data. By following this comprehensive guide, you’ve set up a production-ready APITable instance with proper database connectivity, Redis caching, persistent storage, security configurations, and scalability options.

Your APITable deployment is now ready to serve as the foundation for building collaborative applications, managing complex data relationships, and automating workflows for your team. With the API-first architecture, you can integrate APITable with your existing tools and build custom solutions tailored to your specific needs.

For ongoing success, remember to implement regular backups, monitor performance metrics, keep your deployment updated with the latest security patches, and scale resources as your usage grows.