Skip to content
Klutch.sh Docs

Deploying CryptPad

Introduction

CryptPad is a powerful open-source, zero-knowledge collaborative office suite that enables secure, end-to-end encrypted document editing, spreadsheet management, presentations, and real-time collaboration. Unlike traditional cloud office tools, CryptPad ensures that your data remains private and encrypted, making it an ideal solution for organizations prioritizing security and privacy.

Deploying CryptPad on Klutch.sh provides you with a scalable, production-ready infrastructure that automatically handles Docker container deployments, persistent storage, and seamless GitHub integration. Whether you’re setting up a secure workspace for your team or providing encrypted collaboration tools for your community, this guide will walk you through every step of deploying CryptPad with Docker on Klutch.sh.

Key Features of CryptPad:

  • End-to-end encryption for all documents and communications
  • Real-time collaborative editing for documents, spreadsheets, presentations, and more
  • Zero-knowledge architecture ensuring server administrators cannot access your data
  • Self-hosted solution giving you complete control over your data
  • Rich text editing, kanban boards, whiteboard, polls, and forms
  • User management and access controls

Why Deploy on Klutch.sh:

  • Automatic Docker detection and deployment from your GitHub repository
  • Built-in persistent storage support for user data and uploads
  • Automated builds triggered by GitHub commits
  • Scalable infrastructure with configurable compute resources
  • Secure environment variable management for secrets
  • HTTP/HTTPS traffic routing with custom domain support

Prerequisites

Before you begin deploying CryptPad on Klutch.sh, ensure you have the following:

  • A Klutch.sh account (sign up for free)
  • A GitHub account with a repository for your CryptPad deployment
  • Basic understanding of Docker and containerization concepts
  • Familiarity with Node.js applications (helpful but not required)
  • Git installed on your local machine for repository management

Recommended Knowledge:

  • Docker and Dockerfile syntax
  • Environment variable configuration
  • Linux file system and permissions
  • Basic networking concepts (ports, HTTP/HTTPS)

Understanding CryptPad Architecture

CryptPad consists of several components working together:

  • Node.js Application Server: Handles WebSocket connections and serves the application
  • Static Assets: HTML, CSS, JavaScript files for the client-side application
  • Data Storage: User files, documents, and encrypted data stored on disk
  • Configuration Files: Server settings, domain configuration, and feature toggles

When deploying on Klutch.sh, the platform automatically detects your Dockerfile in the root directory and builds a container image. CryptPad requires persistent storage for user data, which we’ll configure using Klutch.sh’s volume management.

Step 1: Prepare Your GitHub Repository

Setting up your GitHub repository correctly is crucial for a successful deployment.

    Create a New Repository

    1. Navigate to GitHub and create a new repository
    2. Name it something descriptive like cryptpad-deployment or my-cryptpad-instance
    3. Initialize with a README file for documentation
    4. Set the repository to private if you’ll be storing custom configurations

    Create Your Dockerfile

    Create a Dockerfile in the root of your repository. This file tells Klutch.sh how to build your CryptPad container:

    # Use the official CryptPad image as base
    FROM promasu/cryptpad:latest
    

    # Set working directory
    WORKDIR /cryptpad
    

    # Expose CryptPad's default port
    EXPOSE 3000
    

    # Optional: Copy custom configuration
    # COPY config/config.js /cryptpad/config/config.js
    

    # Optional: Copy custom application config
    # COPY customize /cryptpad/customize
    

    # The base image already has a startup command configured
    # But you can override it if needed:
    # CMD ["node", "server.js"]

    Important Notes:

    • Klutch.sh automatically detects the Dockerfile when present in your repository root
    • There’s no manual selection needed - Docker deployment is automatic when a Dockerfile is detected
    • The official CryptPad Docker image from promasu/cryptpad is well-maintained and production-ready

    Advanced Dockerfile with Custom Configuration

    For production deployments with custom branding and configuration:

    # Multi-stage build for a more optimized container
    FROM promasu/cryptpad:latest
    

    # Install additional dependencies if needed
    # RUN apk add --no-cache curl
    

    # Copy custom configuration files
    COPY config/config.js /cryptpad/config/config.js
    

    # Copy custom branding and styles
    COPY customize/application_config.js /cryptpad/customize/application_config.js
    COPY customize/translations/ /cryptpad/customize/translations/
    COPY customize/pages/ /cryptpad/customize/pages/
    

    # Set up data directory (will be mounted via volume)
    RUN mkdir -p /cryptpad/datastore /cryptpad/blob /cryptpad/block
    

    # Expose the application port
    EXPOSE 3000
    

    # Health check to verify application is running
    HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
      CMD node -e "require('http').get('http://localhost:3000/api/config', (res) => { process.exit(res.statusCode === 200 ? 0 : 1); })"
    

    # Start CryptPad server
    CMD ["node", "server.js"]

    Create Configuration Files

    Create a config directory in your repository with a config.js file:

    config/config.js
    module.exports = {
        // HTTP Server address and port
        httpAddress: '0.0.0.0',
        httpPort: 3000,
    

        // WebSocket path
        websocketPath: '/cryptpad_websocket',
    

        // Storage paths (will be mapped to persistent volumes)
        filePath: './datastore/',
        archivePath: './data/archive',
        pinPath: './data/pins',
        taskPath: './data/tasks',
        blockPath: './block',
        blobPath: './blob',
        blobStagingPath: './data/blobstage',
    

        // Admin contact and support
        adminEmail: 'admin@example.com',
        supportMailbox: 'support@example.com',
    

        // Maximum upload size (in bytes) - 50MB default
        maxUploadSize: 50 * 1024 * 1024,
    

        // Session lifetime (in seconds)
        inactiveTime: 90 * 24 * 3600, // 90 days
    

        // Enable account creation
        restrictRegistration: false,
    

        // Default storage limit per user (in bytes) - 1GB default
        defaultStorageLimit: 1024 * 1024 * 1024,
    

        // Disable telemetry
        disableIntegratedEviction: true,
        disableIntegratedTasks: false,
    

        // Application features
        AppConfig: {
            disableUserlistNotifications: false,
            maxWorkers: 8,
        }
    };

    Commit and Push Your Changes

    Terminal window
    git add Dockerfile config/
    git commit -m "Add Dockerfile and CryptPad configuration"
    git push origin main

Step 2: Deploy CryptPad on Klutch.sh

Now that your repository is ready, let’s deploy CryptPad on Klutch.sh.

    Create a New Project

    1. Log in to your Klutch.sh dashboard
    2. Click on “Create Project” or navigate to the projects section
    3. Enter a project name (e.g., “CryptPad Production”)
    4. Add an optional description to help you identify the project
    5. Click “Create” to initialize your project

    Create a New App

    1. Within your project, click “Create App” or the ”+” button
    2. Fill in the app details:
      • App Name: Choose a descriptive name like “cryptpad-app”
      • GitHub Repository: Select your CryptPad repository from the dropdown
      • Branch: Choose the branch to deploy (typically main or master)

    Configure App Settings

    Configure the following settings for your CryptPad deployment:

    Traffic Type:

    • Select HTTP as CryptPad is a web application that serves HTTP/HTTPS traffic
    • CryptPad does not require TCP traffic routing

    Internal Port Configuration:

    • Set the internal port to 3000 (CryptPad’s default port)
    • This is the port inside the container where CryptPad listens
    • Klutch.sh will automatically route external traffic to this internal port

    Compute Resources:

    • Region: Select a region closest to your users for optimal performance
    • Compute Size: Start with at least 1 CPU and 2GB RAM for basic usage
    • Instances: Begin with 1 instance, scale up as needed

    For production deployments with multiple users, consider:

    • 2 CPUs and 4GB RAM for medium usage (10-50 concurrent users)
    • 4 CPUs and 8GB RAM for high usage (50+ concurrent users)

    Environment Variables

    Add the following environment variables in the Klutch.sh dashboard:

    CRYPTPAD_HTTP_PORT=3000
    CRYPTPAD_ADMIN_EMAIL=your-email@example.com
    NODE_ENV=production

    For additional security, add these optional variables:

    CRYPTPAD_API_SECRET=your-random-secret-key-here
    CRYPTPAD_SUPPORT_MAILBOX=support@your-domain.com

    Important: Mark sensitive variables (like API secrets) as secret in the Klutch.sh UI to prevent them from being logged.

    Deploy the Application

    1. Review all your configuration settings
    2. Click “Create” to start the deployment
    3. Klutch.sh will:
      • Clone your GitHub repository
      • Detect the Dockerfile automatically
      • Build the Docker image
      • Create and start the container
      • Assign a default URL (e.g., cryptpad-app.klutch.sh)

    The initial deployment typically takes 2-5 minutes depending on image size and complexity.

Step 3: Configure Persistent Storage

CryptPad requires persistent storage to save user documents, uploads, and encrypted data. Without persistent volumes, all data would be lost when the container restarts.

    Understanding Storage Requirements

    CryptPad stores several types of data:

    • Datastore: Encrypted document contents and metadata
    • Blob Storage: File uploads, images, and media
    • Block Storage: User account data and public keys
    • Pins: User storage allocation and pinned documents

    All of this data needs to persist across container restarts and redeployments.

    Create a Persistent Volume

    1. In your app settings on Klutch.sh, navigate to the “Volumes” or “Storage” section
    2. Click “Add Volume” or “Create Volume”
    3. Configure the volume:
      • Mount Path: /cryptpad/datastore (primary data location)
      • Size: Start with at least 10GB, increase based on expected usage
      • For production: 50GB-100GB recommended for medium-sized teams

    For better organization and performance, create separate volumes:

    Blob Storage Volume:

    • Mount Path: /cryptpad/blob
    • Size: 20GB+ (stores uploaded files and media)

    Block Storage Volume:

    • Mount Path: /cryptpad/block
    • Size: 5GB+ (stores user account information)

    Volume Size Planning

    Calculate storage needs based on your use case:

    • Small team (5-10 users): 10-20GB total
    • Medium organization (25-50 users): 50-100GB total
    • Large deployment (100+ users): 200GB+ total

    Always monitor usage and scale up as needed. Klutch.sh allows you to resize volumes without data loss.

    Verify Volume Configuration

    After adding volumes:

    1. Check that mount paths are correctly configured
    2. Restart your app to apply volume changes
    3. Verify data persistence by creating a test document, restarting the container, and confirming the document remains accessible

Step 4: Configure Domain and Networking

Setting up proper domain configuration ensures your CryptPad instance is accessible and properly secured.

    Access Your Application

    After deployment, Klutch.sh provides a default URL:

    • Format: https://your-app-name.klutch.sh
    • Example: https://cryptpad-app.klutch.sh

    This URL is immediately accessible and includes automatic HTTPS/TLS encryption.

    Configure Custom Domain (Optional)

    To use your own domain:

    1. Navigate to your app settings in the Klutch.sh dashboard
    2. Go to the “Domains” section
    3. Click “Add Custom Domain”
    4. Enter your domain (e.g., cryptpad.yourdomain.com)
    5. Follow the DNS configuration instructions provided:
      • Add a CNAME record pointing to your Klutch.sh app URL
      • Or add an A record with the provided IP address
    6. Wait for DNS propagation (typically 5-60 minutes)
    7. Klutch.sh will automatically provision an SSL certificate

    Update CryptPad Configuration

    Update your config/config.js to reflect your domain:

    module.exports = {
        httpUnsafeOrigin: 'https://cryptpad.yourdomain.com',
        httpSafeOrigin: 'https://cryptpad-sandbox.yourdomain.com',
        // ... other settings
    };

    Important: CryptPad uses a “sandbox” domain for security. Set up a separate subdomain (e.g., cryptpad-sandbox.yourdomain.com) and configure it in the same way as your main domain.

    Commit Configuration Changes

    Terminal window
    git add config/config.js
    git commit -m "Update domain configuration"
    git push origin main

    Klutch.sh will automatically detect the changes and redeploy your application.

Step 5: Environment Variables and Secrets

Properly managing environment variables and secrets is crucial for security and configuration flexibility.

    Essential Environment Variables

    Configure these variables in the Klutch.sh dashboard under your app’s environment settings:

    # Application Settings
    NODE_ENV=production
    CRYPTPAD_HTTP_PORT=3000
    

    # Admin Configuration
    CRYPTPAD_ADMIN_EMAIL=admin@yourdomain.com
    CRYPTPAD_SUPPORT_MAILBOX=support@yourdomain.com
    

    # Security Settings (mark as secret)
    CRYPTPAD_ADMIN_PASSWORD=your-secure-password-here

    Advanced Configuration Variables

    For production deployments:

    # Performance Tuning
    NODE_OPTIONS=--max-old-space-size=4096
    CRYPTPAD_MAX_WORKERS=4
    

    # Storage Limits
    CRYPTPAD_DEFAULT_STORAGE_LIMIT=5368709120
    CRYPTPAD_MAX_UPLOAD_SIZE=52428800
    

    # Feature Flags
    CRYPTPAD_DISABLE_REGISTRATION=false
    CRYPTPAD_DISABLE_ANONYMOUS_ACCESS=false

    Using Environment Variables in Configuration

    Reference environment variables in your config.js:

    module.exports = {
        httpPort: process.env.CRYPTPAD_HTTP_PORT || 3000,
        adminEmail: process.env.CRYPTPAD_ADMIN_EMAIL || 'admin@example.com',
        maxUploadSize: parseInt(process.env.CRYPTPAD_MAX_UPLOAD_SIZE) || 50 * 1024 * 1024,
        // ... other settings
    };

    Security Best Practices

    • Never commit secrets to your Git repository
    • Use Klutch.sh’s secret marking feature for sensitive values
    • Rotate admin passwords regularly
    • Use strong, randomly generated passwords for admin accounts
    • Limit who has access to environment variable configuration

Step 6: Testing and Verification

After deployment, thoroughly test your CryptPad instance to ensure everything works correctly.

    Access the Application

    1. Open your CryptPad URL in a web browser
    2. You should see the CryptPad landing page
    3. If using a custom domain, verify HTTPS is working (look for the padlock icon)

    Create Test Documents

    1. Click “Create a new pad” on the homepage
    2. Choose a document type (Rich Text, Spreadsheet, Presentation, etc.)
    3. Create and edit a test document
    4. Share the document with another browser or user to test collaboration
    5. Verify real-time synchronization is working

    Test User Registration

    1. Click “Sign Up” or “Register”
    2. Create a test user account
    3. Log in with the new account
    4. Create a document while logged in
    5. Verify the document is saved to your account

    Verify Persistent Storage

    1. Create a document and note its content
    2. In Klutch.sh dashboard, restart your CryptPad app
    3. Wait for the app to come back online
    4. Access the document again - it should retain all content
    5. This confirms persistent volumes are working correctly

    Test File Uploads

    1. In a document, upload a file or image
    2. Verify the upload completes successfully
    3. Check that uploaded files are accessible and display correctly

    Monitor Application Logs

    1. In the Klutch.sh dashboard, navigate to your app’s logs
    2. Look for any error messages or warnings
    3. Verify CryptPad is listening on port 3000
    4. Check for successful WebSocket connections

Getting Started with CryptPad

Once your instance is deployed, here’s how to start using CryptPad effectively.

Creating Your First Document

// Example: Customizing the welcome message
// In customize/application_config.js
define(function() {
    var AppConfig = {};


    AppConfig.name = "My Organization CryptPad";
    AppConfig.welcomeMessage = "Welcome to our secure collaboration platform!";


    return AppConfig;
});

Setting Up Admin Account

  1. Access your CryptPad instance
  2. Register an account using your admin email
  3. In your server, access the container:
Terminal window
# This is for reference - Klutch.sh manages containers automatically
# To grant admin privileges, edit the database directly or use environment variables

For Klutch.sh deployments, configure admin email in environment variables before deployment.

Customizing Your Instance

Create a customize directory in your repository:

customize/
├── application_config.js    # Application settings
├── translations/            # Custom translations
│   └── messages.en.json
└── pages/                   # Custom pages
    ├── index.html
    └── privacy.html

Example customize/application_config.js:

define(function() {
    var AppConfig = {};


    // Instance name
    AppConfig.name = "MyCompany CryptPad";


    // Instance description
    AppConfig.description = "Secure collaborative documents for MyCompany";


    // Custom logo
    AppConfig.logoURL = "/customize/logo.png";


    // Disable certain apps
    AppConfig.availablePadTypes = ['drive', 'pad', 'code', 'slide', 'sheet'];


    // Default pad settings
    AppConfig.defaultPadStyle = {
        'richText': {
            'defaultTextFontFamily': 'Arial, sans-serif',
            'defaultTextFontSize': '14pt'
        }
    };


    return AppConfig;
});

Commit and push these customizations:

Terminal window
git add customize/
git commit -m "Add custom branding and configuration"
git push origin main

Sample Dockerfile with All Best Practices

Here’s a complete, production-ready Dockerfile incorporating all recommendations:

# Use specific version for reproducibility
FROM promasu/cryptpad:5.7.0


# Set working directory
WORKDIR /cryptpad


# Install additional tools for health checks and monitoring
RUN apk add --no-cache curl


# Create data directories
RUN mkdir -p \
    /cryptpad/datastore \
    /cryptpad/blob \
    /cryptpad/block \
    /cryptpad/data/pins \
    /cryptpad/data/tasks \
    /cryptpad/data/archive \
    /cryptpad/data/blobstage


# Copy custom configuration
COPY config/config.js /cryptpad/config/config.js


# Copy customization files
COPY customize/ /cryptpad/customize/


# Set proper permissions
RUN chown -R cryptpad:cryptpad /cryptpad


# Switch to non-root user for security
USER cryptpad


# Expose application port
EXPOSE 3000


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


# Set environment defaults (can be overridden in Klutch.sh)
ENV NODE_ENV=production \
    CRYPTPAD_HTTP_PORT=3000


# Start CryptPad
CMD ["node", "server.js"]

Troubleshooting Common Issues

Issue: Application Won’t Start

Symptoms: Container keeps restarting, logs show errors

Solutions:

  1. Check logs in Klutch.sh dashboard for specific error messages
  2. Verify environment variables are set correctly
  3. Ensure internal port is set to 3000
  4. Check that Dockerfile EXPOSE directive matches the port
  5. Verify persistent volumes are properly mounted

Issue: Data Not Persisting

Symptoms: Documents disappear after container restart

Solutions:

  1. Verify persistent volumes are attached in Klutch.sh settings
  2. Check mount paths match CryptPad’s data directories
  3. Ensure volumes have sufficient space
  4. Restart the app after adding volumes
  5. Test by creating a document, restarting, and checking if it persists

Issue: Cannot Access Application

Symptoms: URL doesn’t load, connection timeout

Solutions:

  1. Check that HTTP traffic type is selected (not TCP)
  2. Verify internal port is set to 3000
  3. Check application logs for startup errors
  4. Ensure container has finished building and is running
  5. Try accessing the default .klutch.sh URL first before custom domain

Issue: WebSocket Connection Failed

Symptoms: Real-time collaboration not working, connection errors in browser console

Solutions:

  1. Ensure WebSocket path is correctly configured in config.js
  2. Check that reverse proxy settings don’t block WebSocket connections
  3. Verify HTTPS is properly configured (WebSockets require secure connections)
  4. Check browser console for specific error messages

Issue: Uploads Failing

Symptoms: Cannot upload files or images

Solutions:

  1. Verify blob storage volume is mounted at /cryptpad/blob
  2. Check file size limits in configuration
  3. Ensure blob directory has write permissions
  4. Verify sufficient storage space in volume
  5. Check maxUploadSize setting in configuration

Viewing Logs

Access application logs through the Klutch.sh dashboard:

  1. Navigate to your app
  2. Click on “Logs” or “Monitoring”
  3. Look for errors, warnings, or startup messages
  4. Filter logs by severity if needed

Getting Help

If you continue to experience issues:

Production Best Practices

Security Hardening

  • Use HTTPS Only: Ensure all traffic uses HTTPS/TLS encryption
  • Regular Updates: Keep CryptPad and base images updated
  • Strong Admin Credentials: Use complex passwords and change them regularly
  • Restrict Registration: Consider disabling public registration for private deployments
  • Enable Admin Panel: Set up admin account for instance management
  • Implement Rate Limiting: Protect against abuse and DDoS attacks

Performance Optimization

  • Resource Allocation: Monitor CPU and memory usage, scale as needed
  • Database Optimization: Regular maintenance of storage structures
  • CDN Usage: Consider CDN for static assets in multi-region deployments
  • Caching Strategy: Configure appropriate cache headers
  • Load Balancing: Use multiple instances for high-availability deployments

Backup and Disaster Recovery

  • Regular Backups: Schedule automated backups of persistent volumes
  • Test Restores: Periodically test backup restoration procedures
  • Version Control: Keep Dockerfile and configs in version control
  • Monitoring: Set up alerts for storage capacity and application health
  • Documentation: Maintain runbooks for common operational tasks

Monitoring and Maintenance

Monitor these key metrics:

  • Storage Usage: Track volume capacity and usage trends
  • Active Users: Monitor concurrent user connections
  • Response Times: Measure API and page load performance
  • Error Rates: Track application errors and exceptions
  • Resource Utilization: CPU, memory, and network usage

Set up alerts for:

  • Storage capacity above 80%
  • Application downtime or restart loops
  • High error rates in logs
  • Resource exhaustion (CPU/memory)

Scaling Considerations

As your CryptPad instance grows:

  • Vertical Scaling: Increase CPU and RAM for single instance
  • Horizontal Scaling: Add multiple instances with load balancing
  • Storage Scaling: Expand persistent volume sizes as needed
  • Database Optimization: Consider separate database instances for large deployments
  • Geographic Distribution: Deploy in multiple regions for global teams

Resources and Further Reading

Official Documentation

Klutch.sh Documentation

Community and Support

Conclusion

Deploying CryptPad on Klutch.sh provides a robust, secure, and scalable solution for end-to-end encrypted collaboration. With automatic Docker detection, persistent storage support, and seamless GitHub integration, Klutch.sh simplifies the deployment process while maintaining production-grade reliability.

By following this guide, you’ve learned how to:

  • Set up a complete CryptPad deployment with Docker
  • Configure persistent storage for user data
  • Manage environment variables and secrets securely
  • Customize your CryptPad instance with branding and configuration
  • Implement production best practices for security and performance
  • Troubleshoot common deployment issues

Your CryptPad instance is now ready to provide secure, privacy-focused collaboration for your team or organization. As you grow, Klutch.sh makes it easy to scale your resources, add custom domains, and maintain your deployment with minimal operational overhead.

For advanced configurations, multi-region deployments, or enterprise support, explore the additional resources linked throughout this guide or reach out to the Klutch.sh support team.