Skip to content
Klutch.sh Docs

Deploying Docspell

Introduction

Docspell is a powerful open-source document management system (DMS) designed to help you organize, tag, and search through your documents efficiently. Built with Scala and Elm, Docspell provides automatic text recognition (OCR), full-text search, multi-user support, and intelligent tagging capabilities. Whether you’re managing personal documents, business records, or digital archives, Docspell offers a self-hosted solution that puts you in complete control of your data.

This comprehensive guide walks you through deploying Docspell on Klutch.sh using a Dockerfile. You’ll learn how to set up persistent storage for your documents and database, configure environment variables for secure operation, and implement best practices for a production-ready deployment. Klutch.sh automatically detects your Dockerfile and builds your application, making deployment seamless and efficient.

By the end of this guide, you’ll have a fully functional Docspell instance running on Klutch.sh, ready to handle your document management needs with automatic backups, scalable infrastructure, and secure document storage.

What You’ll Need

Before starting this deployment, ensure you have:

  • A Klutch.sh account - sign up here if you don’t have one
  • A GitHub repository for your Docspell deployment
  • Basic understanding of Docker and containerization concepts
  • PostgreSQL database (recommended) or H2 database for smaller deployments
  • Basic knowledge of document management systems and web applications

Understanding Docspell Architecture

Docspell consists of two main components:

  1. REST Server - The backend API that handles document processing, OCR, database operations, and business logic
  2. Joex - The job executor that processes documents asynchronously, performing OCR, text extraction, and metadata extraction

For a complete deployment, you’ll need to run both components. This guide focuses on deploying the all-in-one Docker image that includes both services, simplifying the deployment process on Klutch.sh.

Step 1: Setting Up Your GitHub Repository

    1. Create a new GitHub repository or use an existing one for your Docspell deployment:

      Terminal window
      mkdir docspell-deploy
      cd docspell-deploy
      git init

    2. Create a .gitignore file to exclude sensitive files:

      # Environment files
      .env
      .env.local
      

      # Data directories
      data/
      logs/
      

      # Docker
      docker-compose.yml

      Note: Docker Compose is not supported by Klutch.sh for deployment, but you can use it for local development if needed.

    3. Commit and push your initial repository structure to GitHub:

      Terminal window
      git add .
      git commit -m "Initial Docspell repository setup"
      git remote add origin https://github.com/YOUR_USERNAME/docspell-deploy.git
      git push -u origin main

For detailed instructions on connecting your GitHub repository to Klutch.sh, refer to the Quick Start Guide.

Step 2: Creating the Dockerfile

Create a Dockerfile in the root of your repository. Klutch.sh will automatically detect this Dockerfile when you deploy your application.

Here’s a production-ready Dockerfile for Docspell:

# Use the official Docspell all-in-one image with a specific version
FROM eikek0/docspell:v0.41.0


# Set working directory
WORKDIR /opt/docspell


# Create directories for persistent data
RUN mkdir -p /opt/docspell/data && \
    mkdir -p /opt/docspell/config


# Expose the default Docspell port
EXPOSE 7880


# The default entrypoint starts both REST server and Joex components
# No CMD needed - use the image's default entrypoint

Advanced Dockerfile with Custom Configuration

For more control over your deployment, you can create a custom Dockerfile with additional configuration:

FROM eikek0/docspell:v0.41.0


WORKDIR /opt/docspell


# Install additional tools for health checks and OCR languages
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    curl \
    ca-certificates \
    tesseract-ocr \
    tesseract-ocr-eng \
    tesseract-ocr-deu && \
    rm -rf /var/lib/apt/lists/*


# Create necessary directories
RUN mkdir -p /opt/docspell/data \
             /opt/docspell/config \
             /opt/docspell/logs


# Copy custom configuration if you have one
# COPY ./config/docspell.conf /opt/docspell/config/


# Optional: Health check (requires curl installed above)
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD curl -f http://localhost:7880/api/info/version || exit 1


EXPOSE 7880


# Use the default entrypoint from the base image

Step 3: Configuring Environment Variables

Docspell requires several environment variables for proper operation. These should be configured in the Klutch.sh dashboard under your app’s environment variables section.

Required Environment Variables

Terminal window
# Database Configuration
DOCSPELL_DB_TYPE=postgresql
DOCSPELL_DB_HOST=your-postgres-host
DOCSPELL_DB_PORT=5432
DOCSPELL_DB_NAME=docspell
DOCSPELL_DB_USER=docspell_user
DOCSPELL_DB_PASSWORD=your-secure-password


# Server Configuration
DOCSPELL_BASE_URL=https://example-app.klutch.sh
DOCSPELL_BIND_ADDRESS=0.0.0.0
DOCSPELL_BIND_PORT=7880


# Security
DOCSPELL_SERVER_SECRET=your-random-secret-key-min-64-chars

Optional Environment Variables

Terminal window
# OCR Configuration
DOCSPELL_OCR_ENABLED=true
DOCSPELL_OCR_LANGUAGES=eng,deu


# File Storage
DOCSPELL_FILES_CHUNK_SIZE=524288


# Admin Account (First-time setup - CHANGE THESE IMMEDIATELY!)
DOCSPELL_ADMIN_USER=admin
DOCSPELL_ADMIN_PASSWORD=change-this-secure-password-immediately


# Logging
DOCSPELL_LOG_LEVEL=Info

Security Warning: The admin password shown above is just an example. You must change this to a strong, unique password immediately after first login. Never use simple passwords like “admin” in production.

Using Nixpacks Build/Runtime Environment Variables

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

Terminal window
# Custom start command
NIXPACKS_START_CMD=/opt/docspell/docspell-restserver


# Build-time environment variables
NIXPACKS_BUILD_ENV=NODE_ENV=production

Important: Store all sensitive values (database passwords, secret keys) as environment variables in Klutch.sh. Never commit these to your repository. Use the Klutch.sh dashboard at klutch.sh/app to securely manage environment variables.

Step 4: Setting Up Persistent Storage

Docspell requires persistent storage to maintain your documents, database files, and configuration across deployments.

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

    2. Go to the Volumes section of your app

    3. Create a volume for document storage:

      • Mount Path: /opt/docspell/data
      • Size: Minimum 10GB (adjust based on your document volume)

    4. Create a volume for configuration:

      • Mount Path: /opt/docspell/config
      • Size: 1GB

    5. (Optional) Create a volume for logs:

      • Mount Path: /opt/docspell/logs
      • Size: 5GB

Note: Klutch.sh volumes only require you to specify the mount path and size. The volume names are managed automatically by the platform.

Volume Structure

Your persistent volumes should follow this structure:

/opt/docspell/data/        # Uploaded documents and processed files
/opt/docspell/config/      # Configuration files
/opt/docspell/logs/        # Application logs

For more details on managing volumes, see the Volumes Guide.

Step 5: Deploying to Klutch.sh

Now that you have your Dockerfile and configuration ready, let’s deploy Docspell to Klutch.sh.

    1. Push your code to GitHub:

      Terminal window
      git add Dockerfile
      git commit -m "Add Docspell Dockerfile"
      git push origin main

    2. Create a new app in Klutch.sh:

      • Log in to klutch.sh/app
      • Click New App or Create Project
      • Select your GitHub repository

    3. Configure your app:

      • App Name: docspell (or your preferred name)
      • Branch: main (or your default branch)
      • Klutch.sh will automatically detect your Dockerfile in the root directory

    4. Configure traffic settings:

      • Select HTTP traffic type (Docspell is a web application)
      • Set the internal port to 7880 (Docspell’s default port)

    5. Add environment variables:

      • Add all the environment variables from Step 3
      • Mark sensitive variables (passwords, secrets) as secret

    6. Attach persistent volumes:

      • Add the volumes you configured in Step 4
      • Verify the mount paths are correct

    7. Deploy:

      • Click Deploy or Create
      • Klutch.sh will build your Docker image and deploy your application

Your Docspell instance will be available at https://example-app.klutch.sh (replace with your actual app URL).

Step 6: Setting Up the Database

Docspell requires a database to store metadata, user information, and document indexes. While H2 (embedded database) works for testing, PostgreSQL is recommended for production.

    1. Create a PostgreSQL database on Klutch.sh or use an external provider

    2. Set the following environment variables in your Klutch.sh app:

      Terminal window
      DOCSPELL_DB_TYPE=postgresql
      DOCSPELL_DB_HOST=your-postgres-host
      DOCSPELL_DB_PORT=5432
      DOCSPELL_DB_NAME=docspell
      DOCSPELL_DB_USER=docspell_user
      DOCSPELL_DB_PASSWORD=your-secure-password

    3. Docspell will automatically create the necessary tables on first startup

Option B: Using H2 Database (Testing Only)

For quick testing or development, you can use the embedded H2 database:

Terminal window
DOCSPELL_DB_TYPE=h2
DOCSPELL_DB_PATH=/opt/docspell/data/docspell.db

Warning: H2 is not recommended for production use due to performance limitations and lack of concurrent access support.

Step 7: Initial Configuration

After your first deployment, you’ll need to complete the initial setup:

    1. Access Docspell: Navigate to your app URL (e.g., https://example-app.klutch.sh)

    2. Create the first user:

      • If you set DOCSPELL_ADMIN_USER and DOCSPELL_ADMIN_PASSWORD, log in with those credentials
      • Otherwise, register a new user through the web interface

    3. Configure OCR languages:

      • Go to Settings → Processing
      • Select the languages you need for OCR (English, German, etc.)

    4. Set up integrations (optional):

      • Email integration for document import
      • Scanner integration
      • Mobile app connection

    5. Test document upload:

      • Upload a test document
      • Verify OCR processing works
      • Check that documents are stored in your persistent volume

Advanced Configuration

Custom Configuration File

If you need more control over Docspell’s configuration, create a custom configuration file:

config/docspell.conf
docspell {
  server {
    bind {
      address = "0.0.0.0"
      port = 7880
    }


    base-url = "https://example-app.klutch.sh"


    backend {
      jdbc {
        url = "jdbc:postgresql://${DOCSPELL_DB_HOST}:${DOCSPELL_DB_PORT}/${DOCSPELL_DB_NAME}"
        user = ${DOCSPELL_DB_USER}
        password = ${DOCSPELL_DB_PASSWORD}
      }


      signup {
        mode = "invite"
      }


      files {
        chunk-size = 524288
      }
    }
  }


  joex {
    bind {
      address = "0.0.0.0"
      port = 7878
    }


    scheduler {
      pool-size = 2
    }
  }
}

Mount this configuration file using a persistent volume or include it in your Docker image.

Email Integration

To enable email-based document import:

Terminal window
# Environment variables for email integration
DOCSPELL_IMAP_ENABLED=true
DOCSPELL_IMAP_HOST=imap.gmail.com
DOCSPELL_IMAP_PORT=993
DOCSPELL_IMAP_USER=your-email@gmail.com
DOCSPELL_IMAP_PASSWORD=your-app-password
DOCSPELL_IMAP_SSL=true

Scaling Considerations

For high-volume document processing:

  1. Increase Joex pool size: Set DOCSPELL_JOEX_POOL_SIZE to a higher value
  2. Add more memory: Allocate at least 2GB RAM for OCR-heavy workloads
  3. Use external object storage: Configure S3-compatible storage for documents
  4. Separate Joex workers: Deploy additional Joex instances for parallel processing

Monitoring and Maintenance

Health Checks

Docspell includes a health check endpoint at /api/info/version. Monitor this endpoint to ensure your application is running correctly.

Logs

Access application logs through the Klutch.sh dashboard or by mounting a logs volume:

Terminal window
# View logs in Klutch.sh dashboard
# Or mount a volume to /opt/docspell/logs

Backups

Critical: Regularly backup your persistent volumes and database:

    1. Database backups:

      Terminal window
      pg_dump -h your-host -U docspell_user docspell > backup-$(date +%Y%m%d).sql

    2. Document backups: Backup the /opt/docspell/data volume regularly

    3. Configuration backups: Keep your environment variables and configuration files in a secure location

Updates

To update Docspell to a new version:

    1. Update the Docker image version in your Dockerfile:

      FROM eikek0/docspell:v0.41.0

    2. Commit and push the changes:

      Terminal window
      git add Dockerfile
      git commit -m "Update Docspell to v0.41.0"
      git push origin main

    3. Klutch.sh will automatically rebuild and redeploy your application

Troubleshooting

Common Issues

Application won’t start:

  • Check environment variables are set correctly
  • Verify database connection settings
  • Ensure persistent volumes are mounted correctly
  • Check logs in the Klutch.sh dashboard

OCR not working:

  • Verify Tesseract is installed in your Docker image
  • Check DOCSPELL_OCR_ENABLED=true is set
  • Ensure sufficient memory is allocated (minimum 1GB)

Database connection errors:

  • Verify database host, port, username, and password
  • Check network connectivity between app and database
  • Ensure database exists and is accessible

File upload failures:

  • Check persistent volume has sufficient space
  • Verify file permissions on mounted volumes
  • Check DOCSPELL_FILES_CHUNK_SIZE setting

Performance Optimization

  1. Increase memory allocation: OCR processing is memory-intensive
  2. Use PostgreSQL: Much faster than H2 for production workloads
  3. Adjust chunk size: Increase DOCSPELL_FILES_CHUNK_SIZE for larger files
  4. Enable caching: Configure Redis for session caching
  5. Optimize database: Regular vacuum and analyze operations

Security Best Practices

  1. Use strong passwords: Generate secure passwords for database and admin accounts
  2. Enable HTTPS: Klutch.sh provides automatic HTTPS for all deployments
  3. Restrict signup mode: Set signup.mode = "invite" for production
  4. Regular updates: Keep Docspell and dependencies updated
  5. Backup encryption: Encrypt backups of sensitive documents
  6. Environment variables: Never commit secrets to your repository
  7. Access control: Use Docspell’s built-in user management and permissions

Next Steps

Now that you have Docspell running on Klutch.sh, consider these next steps:

  • Configure email integration for automatic document import
  • Set up mobile app access for on-the-go document scanning
  • Integrate with your existing document workflows
  • Configure automatic tagging and classification rules
  • Set up scheduled backups for your documents and database
  • Explore Docspell’s API for custom integrations

Resources

Deploying Docspell on Klutch.sh gives you a powerful, self-hosted document management solution with automatic builds, persistent storage, and scalable infrastructure. With this guide, you’re equipped to manage documents efficiently while maintaining full control over your data. For questions or support, visit the Klutch.sh community or consult the official Docspell documentation.