Skip to content
Klutch.sh Docs

Deploying Grist

Introduction

Grist is a powerful open-source spreadsheet and database platform that combines the flexibility of spreadsheets with the structure and power of databases. It provides a modern, user-friendly interface for organizing, analyzing, and collaborating on data with features like relational data structures, custom widgets, Python formulas, and access control.

Deploying Grist on Klutch.sh gives you a scalable, production-ready environment for your data management needs. With automatic Dockerfile detection, integrated persistent storage, and seamless GitHub integration, you can have your Grist instance running in minutes.

This comprehensive guide covers everything you need to deploy Grist on Klutch.sh using Docker, including installation steps, sample Dockerfiles, persistent storage configuration, and production best practices.

Prerequisites

Before you begin, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your Grist deployment
  • Basic familiarity with Docker and containerization concepts
  • Understanding of spreadsheet and database fundamentals

Getting Started: Setting Up Your Grist Repository

To deploy Grist on Klutch.sh, you’ll need to prepare a GitHub repository with the necessary configuration files.

    1. Create a new GitHub repository for your Grist deployment or fork the official Grist repository.

    2. Clone your repository locally:

      Terminal window
      git clone https://github.com/your-username/grist-deployment.git
      cd grist-deployment

    3. Create a Dockerfile in the root of your repository (see the sample Dockerfile section below).

    4. Commit and push your changes:

      Terminal window
      git add .
      git commit -m "Add Dockerfile for Grist deployment"
      git push origin main

For more details on repository setup and GitHub integration, refer to the Klutch.sh Quick Start Guide.

Sample Dockerfile for Grist

Klutch.sh automatically detects a Dockerfile when present in your repository’s root directory. Here’s a comprehensive example for deploying Grist:

Basic Dockerfile

# Use the official Grist image as base
FROM gristlabs/grist:latest


# Expose the default Grist port
EXPOSE 8484


# The official image already includes the start command
# CMD will be inherited from the base image

Dockerfile with Custom Configuration

For more advanced deployments with custom configurations:

# Use the official Grist image as base
FROM gristlabs/grist:latest


# Set working directory
WORKDIR /grist


# Copy custom configuration files (if any)
# COPY ./config/custom-config.json /grist/config/


# Set environment variables (can also be set in Klutch.sh UI)
ENV GRIST_SINGLE_ORG=1
ENV GRIST_HIDE_UI_ELEMENTS=1


# Create volume mount points for persistent data
VOLUME ["/persist"]


# Expose the Grist port
EXPOSE 8484


# Health check to ensure Grist is running properly
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD curl -f http://localhost:8484/ || exit 1


# Start Grist (inherited from base image)
# CMD is already defined in the base image

Multi-stage Dockerfile for Custom Builds

If you need to build from source or add custom plugins:

# Build stage
FROM node:18-alpine AS builder


WORKDIR /app


# Clone Grist (or copy your custom version)
# For this example, we'll use the base image instead
# If you need custom builds, adjust accordingly


# Runtime stage
FROM gristlabs/grist:latest


# Copy any custom built assets
# COPY --from=builder /app/dist /grist/


# Set up persistent storage
ENV GRIST_DATA_DIR=/persist


# Expose port
EXPOSE 8484

Deploying Grist on Klutch.sh

Once you have your Dockerfile ready, deploying to Klutch.sh is straightforward. Klutch.sh uses Nixpacks for builds, but will automatically detect and use your Dockerfile when present.

    1. Log in to the Klutch.sh dashboard at klutch.sh/app.

    2. Create a new project:

      • Click Create Project
      • Give your project a descriptive name (e.g., “My Grist Instance”)
      • Click “Create”

    3. Create a new app within your project:

      • Click Create App
      • Select your GitHub repository containing the Dockerfile
      • Choose the branch you want to deploy (typically main)
      • Select HTTP as the traffic type (Grist is a web application)
      • Set the internal port to 8484 (Grist’s default port)

    4. Configure deployment settings:

      • Region: Select the region closest to your users
      • Compute resources: Choose based on your expected load (start small, scale as needed)
      • Number of instances: Start with 1, increase for high availability

    5. Add environment variables (optional but recommended):

      GRIST_SINGLE_ORG=1
      GRIST_HIDE_UI_ELEMENTS=billing,support
      GRIST_DEFAULT_EMAIL=admin@example.com

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

      • Detect your Dockerfile automatically
      • Build your Docker image
      • Deploy your Grist instance
      • Provide you with a URL like example-app.klutch.sh

Your Grist instance will be accessible at the provided URL once deployment completes (typically 2-5 minutes).

Configuring Persistent Storage

Grist requires persistent storage to maintain your data, documents, and configurations across deployments and restarts. Klutch.sh makes it easy to attach persistent volumes to your application.

Why Persistent Storage is Important

Without persistent storage, all data would be lost when:

  • Your container restarts
  • You deploy a new version
  • The instance is moved or scaled

Setting Up Persistent Volumes

    1. In the Klutch.sh dashboard, navigate to your Grist app settings.

    2. Go to the Volumes section and click “Add Volume”.

    3. Configure your volume:

      • Mount Path: /persist (recommended for Grist data)
      • Size: Start with at least 10GB, adjust based on your data needs
      • Click “Add Volume”

    4. Update your environment variables to use the persistent storage:

      GRIST_DATA_DIR=/persist

    5. Redeploy your app to apply the changes.

Depending on your configuration, you may want to mount volumes at different paths:

  • /persist - Main data directory (documents, databases)
  • /persist/config - Configuration files
  • /persist/uploads - User-uploaded files
  • /persist/plugins - Custom plugins (if applicable)

Volume Best Practices

  • Regular backups: Set up automated backups of your persistent volumes
  • Size monitoring: Monitor volume usage and scale as needed
  • Separate concerns: Consider using multiple volumes for different data types
  • Test restores: Regularly test your backup and restore procedures

Environment Variables and Configuration

Grist offers extensive configuration through environment variables. Here are the most important ones:

Essential Environment Variables

Terminal window
# Application Settings
GRIST_SINGLE_ORG=1                    # Run in single-organization mode
GRIST_ORG_NAME=MyOrganization         # Organization name
GRIST_DEFAULT_EMAIL=admin@example.com # Default admin email


# Data Storage
GRIST_DATA_DIR=/persist               # Where to store data


# Security
GRIST_SESSION_SECRET=your-secret-key  # Session encryption key (generate a secure random string)


# UI Customization
GRIST_HIDE_UI_ELEMENTS=billing,support # Hide specific UI elements
GRIST_PAGE_TITLE_SUFFIX=- My Grist    # Custom page title suffix

Database Configuration (Optional)

By default, Grist uses SQLite. For production deployments with higher loads, you can configure PostgreSQL:

Terminal window
TYPEORM_TYPE=postgres
TYPEORM_HOST=your-postgres-host
TYPEORM_PORT=5432
TYPEORM_DATABASE=grist
TYPEORM_USERNAME=grist_user
TYPEORM_PASSWORD=secure_password

Security Best Practices

    1. Never commit secrets to your repository

      • Use Klutch.sh environment variables for all sensitive data
      • Mark variables as “secret” in the Klutch.sh UI

    2. Generate strong session secrets:

      Terminal window
      # Generate a secure random string
      openssl rand -hex 32

    3. Use HTTPS: Klutch.sh provides automatic HTTPS for your deployments

    4. Enable authentication: Configure Grist’s authentication system for production use

    5. Regular updates: Keep your Grist image updated with the latest security patches

Advanced Configuration and Customization

Custom Plugins and Extensions

If you need to add custom plugins or extensions:

    1. Create a plugins directory in your repository
    2. Add your custom plugins
    3. Update your Dockerfile:
    FROM gristlabs/grist:latest
    

    # Copy custom plugins
    COPY ./plugins /grist/plugins
    

    ENV GRIST_DATA_DIR=/persist
    

    EXPOSE 8484

Authentication Configuration

Grist supports multiple authentication methods:

Terminal window
# Environment variables for authentication
GRIST_OIDC_SP_HOST=https://example-app.klutch.sh
GRIST_OIDC_IDP_ISSUER=https://your-idp.com
GRIST_OIDC_IDP_CLIENT_ID=your-client-id
GRIST_OIDC_IDP_CLIENT_SECRET=your-client-secret

Customizing Build and Start Commands

If you need to customize the build or start commands, you can set Nixpacks environment variables:

Terminal window
# Build-time environment variables
BUILD_COMMAND=npm install && npm run build


# Runtime environment variables
START_COMMAND=node server.js

Note: These are only needed if you’re not using a Dockerfile or need to override default behavior.

Monitoring and Performance

Health Checks

Grist provides a health endpoint that you can use for monitoring:

Terminal window
# Test if Grist is responding
curl https://example-app.klutch.sh/

Performance Optimization

    1. Resource allocation:

      • Start with 1GB RAM, 0.5 CPU
      • Monitor usage and scale up as needed
      • Grist can handle significant loads with proper resources

    2. Database optimization:

      • For high-traffic sites, use PostgreSQL instead of SQLite
      • Enable connection pooling
      • Regular database maintenance

    3. Caching:

      • Grist includes built-in caching
      • Configure cache settings through environment variables

    4. Scaling:

      • Increase instance count for high availability
      • Use load balancing (handled automatically by Klutch.sh)
      • Monitor response times and adjust resources

Monitoring Best Practices

  • Set up uptime monitoring
  • Monitor resource usage (CPU, memory, disk)
  • Track response times and error rates
  • Set up alerts for critical issues
  • Review logs regularly

For more information, see the Klutch.sh Monitoring Guide.

Scaling and High Availability

Horizontal Scaling

To handle increased traffic:

    1. In your app settings, increase the number of instances
    2. Klutch.sh will automatically:
      • Deploy additional containers
      • Configure load balancing
      • Manage traffic distribution

Vertical Scaling

To handle more complex workloads per instance:

  1. Increase compute resources (CPU and RAM)
  2. Adjust based on your monitoring data
  3. Test thoroughly after scaling

High Availability Setup

For mission-critical deployments:

  • Deploy at least 2-3 instances
  • Use a managed PostgreSQL database (external or on Klutch.sh)
  • Set up regular automated backups
  • Implement monitoring and alerting
  • Plan for disaster recovery

Troubleshooting Common Issues

Container Won’t Start

Issue: Grist container fails to start or crashes immediately.

Solutions:

  • Check environment variables are correctly set
  • Verify persistent volume is properly mounted
  • Review logs in the Klutch.sh dashboard
  • Ensure the internal port (8484) is correctly configured

Data Not Persisting

Issue: Data is lost after redeployment or restart.

Solutions:

  • Verify persistent volume is attached
  • Check that GRIST_DATA_DIR points to the mounted volume
  • Ensure volume mount path matches your configuration
  • Test volume permissions

Performance Issues

Issue: Grist is slow or unresponsive.

Solutions:

  • Increase allocated resources (CPU/RAM)
  • Consider migrating from SQLite to PostgreSQL
  • Check for database size and optimize if needed
  • Monitor and optimize query performance

Authentication Problems

Issue: Users can’t log in or authentication fails.

Solutions:

  • Verify authentication environment variables
  • Check HTTPS configuration
  • Review authentication provider settings
  • Test with a simple authentication method first

Production Best Practices

Security Checklist

  • Enable HTTPS (automatic with Klutch.sh)
  • Configure authentication and access control
  • Use environment variables for all secrets
  • Regularly update Grist to the latest version
  • Implement backup and disaster recovery procedures
  • Use strong, unique passwords and keys
  • Enable audit logging
  • Restrict network access as needed

Backup Strategy

    1. Automated backups:

      • Set up regular volume snapshots
      • Back up your database separately
      • Test restore procedures regularly

    2. Backup frequency:

      • Daily backups for production systems
      • Retain backups for at least 30 days
      • Keep longer retention for compliance needs

    3. Disaster recovery:

      • Document recovery procedures
      • Test recovery process quarterly
      • Keep backups in multiple locations

Performance Optimization

  • Use a CDN for static assets if serving many users
  • Optimize database queries and indexes
  • Monitor and log performance metrics
  • Implement caching strategies
  • Regular database maintenance

Maintenance Windows

  • Schedule regular maintenance windows
  • Plan for updates and upgrades
  • Test updates in a staging environment first
  • Communicate maintenance schedules to users

Additional Resources

Documentation and Guides

Community and Support

Conclusion

Deploying Grist on Klutch.sh provides you with a powerful, scalable platform for modern data management and collaboration. With automatic Dockerfile detection, integrated persistent storage, and seamless GitHub integration, you can focus on using Grist to organize and analyze your data rather than managing infrastructure.

Whether you’re running a small team collaboration tool or a large-scale data management platform, Klutch.sh provides the reliability, performance, and ease of use you need for production deployments.

Start your Grist deployment today and experience the power of combining spreadsheets with databases in a modern, cloud-native environment.