Skip to content
Klutch.sh Docs

Deploying EveryDocs

Introduction

EveryDocs Core is a simple yet powerful Document Management System (DMS) designed for private use. Built with Ruby on Rails, EveryDocs helps you organize your documents digitally with features like PDF uploading, folder organization, full-text search, and optional encryption for secure document storage. Whether you’re managing personal documents, business records, or family archives, EveryDocs provides an intuitive interface for keeping track of your important files.

The system extracts content from PDF files for comprehensive full-text search capabilities, allows you to add custom metadata like people and processing states to documents, and supports encrypted storage for sensitive files. With its REST API and mobile-friendly web interface, you can access and manage your documents from anywhere.

This guide walks you through deploying EveryDocs Core on Klutch.sh using Docker. You’ll learn how to set up MySQL for database storage, configure persistent volumes for document files, enable encryption features, and implement production-ready best practices for a secure and reliable document management system.

Prerequisites

Before deploying EveryDocs on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your EveryDocs project
  • A MySQL database (we’ll cover deployment on Klutch.sh)
  • Basic understanding of Docker and document management systems
  • Familiarity with Ruby on Rails applications (helpful but not required)

Why Deploy EveryDocs on Klutch.sh

  • Automatic Dockerfile Detection - Klutch.sh automatically detects and builds your Dockerfile without manual configuration
  • Persistent Document Storage - Attach volumes to ensure your uploaded documents persist across deployments
  • Database Integration - Easy connection to MySQL databases deployed on Klutch.sh or external services
  • Secure Environment Variables - Store sensitive database credentials and encryption keys securely
  • HTTP Traffic Routing - Built-in load balancing and SSL termination for web access
  • Continuous Deployment - Automatic builds and deployments when you push to GitHub
  • Scalable Infrastructure - Start small and scale as your document library grows
  • Custom Domains - Connect your own domain with automatic HTTPS certificates
  • Zero Downtime Updates - Rolling deployments keep your document system accessible during updates

Understanding EveryDocs Architecture

EveryDocs is built with several key components:

Core Features

Document Upload and Organization

  • Upload PDF documents with title, description, and creation date
  • Organize documents in folders and subfolders with hierarchical structure
  • Add people and processing states to track document workflows
  • Extract content from PDF files for full-text search capabilities

Security and Encryption

  • Encrypted storage of PDF files on disk (optional)
  • Automatic encryption activation for newly created users (v1.5.0+)
  • User-specific encryption keys for maximum security
  • Note: Encrypted documents don’t support full-text search

Search and Discovery

  • Search all documents by title, description, or content
  • Full-text search across extracted PDF content (for non-encrypted documents)
  • Quick filtering and organization by folders and metadata

Multi-User Support

  • Create multiple user accounts with individual encryption settings
  • Authentication via JsonWebToken (JWT)
  • REST API for programmatic access to all CRUD operations
  • Mobile-friendly web UI for on-the-go document management

Technology Stack

  • Backend: Ruby on Rails 8.0+ (Ruby 3.4+)
  • Database: MySQL/MariaDB for storing metadata and user information
  • File Storage: Local filesystem with optional encryption
  • Authentication: JWT-based authentication system
  • API: RESTful API for all document operations
  • Frontend: Mobile-friendly web interface (separate project: everydocs-web)

Preparing Your EveryDocs Repository

Step 1: Fork or Clone the EveryDocs Repository

Start by getting the EveryDocs Core source code:

Terminal window
# Clone the official repository
git clone https://github.com/jonashellmann/everydocs-core.git
cd everydocs-core


# Or fork it first on GitHub, then clone your fork
git clone https://github.com/your-username/everydocs-core.git
cd everydocs-core

Step 2: Review the Existing Dockerfile

EveryDocs Core includes a production-ready Dockerfile. Let’s examine it:

FROM ruby:3.4.2


LABEL org.opencontainers.image.authors="Jonas Hellmann <mail@jonas-hellmann.de>"


# Create directory for document storage
RUN mkdir -p /var/everydocs-files


WORKDIR /usr/src/app


# Set environment variables
ENV RAILS_ENV=production
ENV EVERYDOCS_DB_ADAPTER=mysql2
ENV EVERYDOCS_DB_NAME=everydocs
ENV EVERYDOCS_DB_USER=everydocs
ENV EVERYDOCS_DB_HOST=localhost
ENV EVERYDOCS_DB_PORT=3306


# Copy application code
COPY . .


# Clean up unnecessary files
RUN rm -f Gemfile.lock
RUN rm -rf .git/


# Install Ruby dependencies
RUN bundle install


# Install Node.js for asset compilation
RUN apt-get update
RUN apt-get install nodejs -y --no-install-recommends


# Initialize Rails credentials (required for production)
RUN EDITOR="mate --wait" bin/rails credentials:edit


# Expose application port
EXPOSE 5678


# Start script and Rails server
ENTRYPOINT ["./bin/entrypoint.sh"]
CMD ["rails", "server", "-b", "0.0.0.0", "--port", "5678"]

Step 3: Customize the Dockerfile (Optional)

For production deployment on Klutch.sh, you may want to create a customized version:

FROM ruby:3.4.2-alpine


LABEL org.opencontainers.image.authors="Your Name <your-email@example.com>"


# Install system dependencies
RUN apk add --no-cache \
    build-base \
    mysql-dev \
    nodejs \
    npm \
    tzdata \
    git \
    bash


# Create application directory and document storage
RUN mkdir -p /usr/src/app /var/everydocs-files
WORKDIR /usr/src/app


# Set environment defaults (will be overridden by Klutch.sh environment variables)
ENV RAILS_ENV=production
ENV EVERYDOCS_DB_ADAPTER=mysql2
ENV EVERYDOCS_DB_NAME=everydocs
ENV EVERYDOCS_DB_USER=everydocs
ENV EVERYDOCS_DB_HOST=localhost
ENV EVERYDOCS_DB_PORT=3306
ENV RAILS_LOG_TO_STDOUT=true
ENV RAILS_SERVE_STATIC_FILES=true


# Copy Gemfile and install dependencies
COPY Gemfile Gemfile.lock ./
RUN bundle config set --local deployment 'true' && \
    bundle config set --local without 'development test' && \
    bundle install --jobs=4 --retry=3


# Copy application code
COPY . .


# Precompile assets
RUN bundle exec rails assets:precompile


# Create a script to handle database setup and credentials
RUN echo '#!/bin/bash\n\
set -e\n\
\n\
# Set up Rails master key if not present\n\
if [ ! -f config/master.key ]; then\n\
  echo "Generating Rails master key..."\n\
  bundle exec rails credentials:edit --environment=production\n\
fi\n\
\n\
# Run database migrations\n\
echo "Running database migrations..."\n\
bundle exec rails db:migrate RAILS_ENV=production\n\
\n\
# Start the Rails server\n\
echo "Starting EveryDocs..."\n\
exec bundle exec rails server -b 0.0.0.0 -p ${PORT:-5678}\n\
' > /usr/src/app/docker-entrypoint.sh


RUN chmod +x /usr/src/app/docker-entrypoint.sh


# Expose application port
EXPOSE 5678


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


ENTRYPOINT ["/usr/src/app/docker-entrypoint.sh"]

Step 4: Create Environment Configuration

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

Terminal window
# Rails Configuration
RAILS_ENV=production
SECRET_KEY_BASE=generate_with_rails_secret_command


# Database Configuration
EVERYDOCS_DB_ADAPTER=mysql2
EVERYDOCS_DB_NAME=everydocs
EVERYDOCS_DB_USER=everydocs
EVERYDOCS_DB_PASSWORD=your_secure_database_password
EVERYDOCS_DB_HOST=mysql-app.klutch.sh
EVERYDOCS_DB_PORT=8000


# Application Configuration
PORT=5678
RAILS_SERVE_STATIC_FILES=true
RAILS_LOG_TO_STDOUT=true


# Encryption (Optional - for user document encryption)
# Generate with: openssl rand -hex 32
SECRET_KEY=your_encryption_secret_key


# Time Zone
TZ=America/New_York

Step 5: Create a README

Document your deployment with a README.md:

# EveryDocs Core - Klutch.sh Deployment


Document Management System deployed on Klutch.sh.


## Prerequisites


- MySQL database
- Persistent storage for documents


## Environment Variables


See `.env.example` for required configuration.


## Deployment


1. Deploy MySQL database on Klutch.sh
2. Set environment variables in Klutch.sh dashboard
3. Attach persistent volume to `/var/everydocs-files`
4. Deploy the application


## First-Time Setup


After deployment, access the web interface and create your first user account.


## Enabling Encryption


For users who want encrypted document storage:
1. Generate a secret key: `openssl rand -hex 32`
2. Add the key to the user's database record
3. Set `encryption_activated_flag` to true in the users table
4. Note: Encrypted documents won't have full-text search


## License


GPL-3.0 - See LICENSE file for details

Step 6: Initialize Git Repository

If you’ve created a new directory or made customizations:

Terminal window
git init
git add .
git commit -m "Initial EveryDocs deployment setup for Klutch.sh"
git branch -M main
git remote add origin https://github.com/your-username/everydocs-klutch.git
git push -u origin main

Deploying MySQL Database

EveryDocs requires a MySQL database. You can deploy MySQL on Klutch.sh or use an external managed service.

Option 1: Deploy MySQL on Klutch.sh

    1. Create a MySQL Deployment

      In your Klutch.sh project, create a new app for MySQL. You can follow our comprehensive MySQL deployment guide or use this quick setup:

    2. Create a MySQL Repository

      Create a new GitHub repository with a Dockerfile:

      FROM mysql:8.4
      

      ENV MYSQL_DATABASE=everydocs
      ENV MYSQL_USER=everydocs
      ENV MYSQL_PASSWORD=secure_password_here
      ENV MYSQL_ROOT_PASSWORD=secure_root_password_here
      

      EXPOSE 3306

    3. Deploy MySQL on Klutch.sh

      • Go to klutch.sh/app
      • Create a new app and connect your MySQL repository
      • Select TCP as the traffic type
      • Set internal port to 3306
      • Deploy the application

    4. Attach Persistent Storage

      Add a persistent volume for MySQL data:

      • Mount Path: /var/lib/mysql
      • Size: 10GB or more depending on expected document volume

    5. Note Connection Details

      After deployment, your MySQL database will be accessible at:

      • Host: your-mysql-app.klutch.sh
      • Port: 8000 (Klutch.sh routes TCP traffic through port 8000)
      • Database: everydocs
      • Username: everydocs
      • Password: The password you set in the Dockerfile

Option 2: Use External MySQL Service

You can also use managed MySQL services like:

  • AWS RDS
  • Google Cloud SQL
  • Azure Database for MySQL
  • PlanetScale
  • DigitalOcean Managed Databases

Simply note the connection details (host, port, database name, username, password) for use in your EveryDocs configuration.

Deploying EveryDocs on Klutch.sh

    1. Log in to Klutch.sh

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

    2. Create a New Project (if you haven’t already)

      • Click “New Project”
      • Enter a project name (e.g., “Document Management”)
      • Select your organization or personal account

    3. Create a New App

      • Within your project, click “New App”
      • Give your app a name (e.g., “everydocs-core”)

    4. Connect Your GitHub Repository

      • Select GitHub as your Git source
      • Authorize Klutch.sh to access your repositories if prompted
      • Choose the repository containing your EveryDocs code
      • Select the branch to deploy (typically main or master)

    5. Configure Network Settings

      Klutch.sh will automatically detect your Dockerfile. Configure the following:

      • Traffic Type: Select HTTP (EveryDocs is a web application)
      • Internal Port: Set to 5678 (or the PORT you configured in your Dockerfile)

    6. Set Environment Variables

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

      Required Variables:

      RAILS_ENV=production
      SECRET_KEY_BASE=<generate with: rails secret>
      EVERYDOCS_DB_ADAPTER=mysql2
      EVERYDOCS_DB_NAME=everydocs
      EVERYDOCS_DB_USER=everydocs
      EVERYDOCS_DB_PASSWORD=<your mysql password>
      EVERYDOCS_DB_HOST=your-mysql-app.klutch.sh
      EVERYDOCS_DB_PORT=8000
      PORT=5678
      RAILS_SERVE_STATIC_FILES=true
      RAILS_LOG_TO_STDOUT=true

      Optional Variables:

      TZ=America/New_York
      SECRET_KEY=<openssl rand -hex 32 for encryption>

      Important: Mark SECRET_KEY_BASE, EVERYDOCS_DB_PASSWORD, and SECRET_KEY as sensitive/secret variables.

    7. Attach Persistent Volume for Documents

      EveryDocs needs persistent storage for uploaded PDF files:

      • Click “Add Volume” in the storage section
      • Mount Path: /var/everydocs-files
      • Size: Start with 20GB (adjust based on expected document volume)

      This ensures your uploaded documents persist across deployments and container restarts.

    8. Configure Additional Settings

      • Region: Choose the region closest to your users
      • Compute Resources: Minimum 512MB RAM, 1GB+ recommended for production
      • Instances: Start with 1 instance

    9. Deploy the Application

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

      • Detect your Dockerfile automatically
      • Build the Docker image
      • Install Ruby dependencies
      • Set up Rails environment
      • Run database migrations
      • Start the application server
      • Assign a URL (e.g., https://everydocs-app.klutch.sh)

    10. Wait for Deployment

      Monitor the build logs. The initial deployment may take 5-10 minutes as it:

      • Builds the Ruby environment
      • Installs gems
      • Compiles assets
      • Sets up database connections
      • Runs migrations

    11. Verify Deployment

      Once deployed, visit your application URL (https://your-app.klutch.sh). You should see the EveryDocs login/registration page.

Initial Setup and Configuration

Creating Your First User Account

    1. Access the Web Interface

      Navigate to your deployed EveryDocs URL (e.g., https://everydocs-app.klutch.sh)

    2. Create an Account

      • Click on “Sign Up” or “Register”
      • Enter your email address
      • Choose a strong password
      • Click “Create Account”

    3. Login

      • Use your new credentials to log in
      • You’ll be directed to the dashboard

Setting Up Document Encryption (Optional)

If you want encrypted document storage for enhanced security:

    1. Generate an Encryption Key

      Terminal window
      openssl rand -hex 32

    2. Add the Key to Your User Record

      You’ll need to access your MySQL database to set this up:

      Terminal window
      # Connect to your MySQL database
      mysql -h your-mysql-app.klutch.sh -P 8000 -u everydocs -p everydocs
      

      # Add the secret key and enable encryption for your user
      UPDATE users
      SET secret_key = 'your_generated_key_here',
          encryption_activated_flag = 1
      WHERE email = 'your-email@example.com';

    3. Understand Encryption Trade-offs

      Benefits:

      • Documents are encrypted at rest on disk
      • Enhanced security for sensitive files
      • User-specific encryption keys

      Limitations:

      • Encrypted documents don’t support full-text search
      • Content extraction is disabled for encrypted documents
      • You can only search by title and description metadata

Organizing Your First Documents

    1. Create Folders

      • Click “New Folder” from the dashboard
      • Enter a folder name (e.g., “Personal Documents”, “Tax Records”)
      • Create subfolders for better organization

    2. Upload a Document

      • Navigate to a folder
      • Click “Upload Document”
      • Select a PDF file from your computer
      • Add metadata:
        • Title: Document name
        • Description: Brief description of contents
        • Date: Document creation or relevant date
        • People: Associated individuals (optional)
        • Processing State: Current status (optional)
      • Click “Upload”

    3. Search Documents

      • Use the search bar to find documents by title, description, or content
      • Full-text search works for non-encrypted documents
      • Filter by folder, date, people, or processing state

Using the EveryDocs REST API

EveryDocs provides a comprehensive REST API for programmatic access to your documents.

Authentication

The API uses JWT (JsonWebToken) for authentication:

Terminal window
# Login to get JWT token
curl -X POST https://everydocs-app.klutch.sh/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "password": "your-password"
  }'


# Response includes JWT token
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

API Examples

List All Documents

Terminal window
curl -X GET https://everydocs-app.klutch.sh/api/documents \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Upload a Document

Terminal window
curl -X POST https://everydocs-app.klutch.sh/api/documents \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "document[title]=Invoice 2024-001" \
  -F "document[description]=Monthly service invoice" \
  -F "document[document_date]=2024-01-15" \
  -F "document[file]=@/path/to/invoice.pdf"

Get Document Details

Terminal window
curl -X GET https://everydocs-app.klutch.sh/api/documents/123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Update a Document

Terminal window
curl -X PATCH https://everydocs-app.klutch.sh/api/documents/123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "document": {
      "title": "Updated Invoice Title",
      "description": "Updated description"
    }
  }'

Delete a Document

Terminal window
curl -X DELETE https://everydocs-app.klutch.sh/api/documents/123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Search Documents

Terminal window
curl -X GET "https://everydocs-app.klutch.sh/api/documents/search?q=invoice" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Create a Folder

Terminal window
curl -X POST https://everydocs-app.klutch.sh/api/folders \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "folder": {
      "name": "Tax Documents 2024",
      "parent_id": null
    }
  }'

Viewing All Available API Routes

To see all available API endpoints and their parameters:

Terminal window
# If you have access to the Rails console
bundle exec rails routes

This will show you all CRUD operations available for:

  • Documents
  • Folders
  • People
  • Processing states
  • Users (authentication)

Environment Variables Reference

Here’s a complete reference of all environment variables supported by EveryDocs:

Required Variables

VariableDescriptionExample
RAILS_ENVRails environment modeproduction
SECRET_KEY_BASERails secret key for encryptionGenerate with rails secret
EVERYDOCS_DB_ADAPTERDatabase adaptermysql2
EVERYDOCS_DB_NAMEDatabase nameeverydocs
EVERYDOCS_DB_USERDatabase usernameeverydocs
EVERYDOCS_DB_PASSWORDDatabase passwordYour secure password
EVERYDOCS_DB_HOSTDatabase hostmysql-app.klutch.sh
EVERYDOCS_DB_PORTDatabase port8000

Optional Variables

VariableDescriptionDefault
PORTApplication port5678
RAILS_SERVE_STATIC_FILESServe static assetstrue
RAILS_LOG_TO_STDOUTLog to standard outputtrue
TZTimezoneUTC
SECRET_KEYUser encryption keyEmpty (encryption disabled)
RAILS_MAX_THREADSMax threads per process5
WEB_CONCURRENCYNumber of worker processes2

Production Best Practices

Security Hardening

1. Use Strong Passwords

Generate secure passwords for all credentials:

Terminal window
# Generate SECRET_KEY_BASE
rails secret


# Generate encryption key
openssl rand -hex 32


# Generate database password
openssl rand -base64 32

2. Enable Encryption for Sensitive Documents

For highly sensitive documents, enable per-user encryption:

  • Generate unique secret keys for each user
  • Set encryption_activated_flag = 1 in the users table
  • Understand that encrypted documents won’t be searchable by content

3. Regular Security Updates

Keep EveryDocs and its dependencies updated:

Terminal window
# Update Ruby gems
bundle update


# Check for security vulnerabilities
bundle audit


# Update base Docker image
# Change FROM ruby:3.4.2 to latest stable version

4. Implement HTTPS Only

Klutch.sh provides HTTPS automatically, but ensure:

  • Force SSL in Rails: config.force_ssl = true
  • Set secure cookie flags
  • Use HSTS headers

5. Limit Access with Authentication

  • Don’t expose user registration publicly if not needed
  • Implement IP whitelisting for admin users if possible
  • Use strong password policies
  • Consider implementing two-factor authentication

Database Optimization

1. Regular Backups

Set up automated database backups:

Terminal window
# Manual backup
mysqldump -h your-mysql-app.klutch.sh -P 8000 -u everydocs -p everydocs > backup_$(date +%Y%m%d).sql


# Compress backup
gzip backup_$(date +%Y%m%d).sql

2. Index Optimization

Ensure proper database indexes for search performance:

-- Check existing indexes
SHOW INDEX FROM documents;


-- Add index for common searches
CREATE INDEX idx_documents_title ON documents(title);
CREATE INDEX idx_documents_created_at ON documents(created_at);
CREATE INDEX idx_folders_parent_id ON folders(parent_id);

3. Database Maintenance

Run regular maintenance:

-- Analyze tables for query optimization
ANALYZE TABLE documents, folders, users;


-- Optimize tables to reclaim space
OPTIMIZE TABLE documents;

Performance Optimization

1. Enable Caching

Configure Rails caching for better performance:

config/environments/production.rb
config.cache_store = :memory_store
config.action_controller.perform_caching = true

2. Asset Optimization

Ensure assets are precompiled and compressed:

Terminal window
RAILS_ENV=production bundle exec rails assets:precompile

3. Database Connection Pooling

Optimize database connections:

config/database.yml
production:
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  timeout: 5000

4. Monitor Resource Usage

Keep an eye on application resources:

  • CPU usage
  • Memory consumption
  • Disk space (especially /var/everydocs-files)
  • Database size and query performance

Storage Management

1. Monitor Volume Usage

Regularly check disk usage:

Terminal window
# Check document storage
du -sh /var/everydocs-files


# List largest files
du -h /var/everydocs-files | sort -rh | head -20

2. Implement Storage Policies

Consider implementing:

  • Document retention policies
  • Automatic archival of old documents
  • Storage quotas per user

3. Volume Scaling

If you’re running out of space:

  • Increase volume size in Klutch.sh dashboard
  • Consider moving old documents to archival storage
  • Implement document compression for older files

Backup and Disaster Recovery

1. Automated Backups

Set up regular automated backups:

backup-everydocs.sh
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backups"


# Backup database
mysqldump -h your-mysql-app.klutch.sh -P 8000 -u everydocs -p${DB_PASSWORD} everydocs | gzip > ${BACKUP_DIR}/db_${DATE}.sql.gz


# Backup documents (if accessible)
tar -czf ${BACKUP_DIR}/documents_${DATE}.tar.gz /var/everydocs-files


# Keep only last 7 days of backups
find ${BACKUP_DIR} -name "*.gz" -mtime +7 -delete


echo "Backup completed: ${DATE}"

2. Test Restore Procedures

Regularly test your backup restoration:

Terminal window
# Restore database
gunzip < db_backup.sql.gz | mysql -h your-mysql-app.klutch.sh -P 8000 -u everydocs -p everydocs


# Restore documents
tar -xzf documents_backup.tar.gz -C /

3. Off-Site Backup Storage

Store backups in multiple locations:

  • Cloud storage (AWS S3, Google Cloud Storage)
  • External backup service
  • Local encrypted backups

Monitoring and Logging

1. Application Monitoring

Monitor application health:

Terminal window
# Check application status
curl -f https://everydocs-app.klutch.sh/ || echo "Application down"


# Monitor response times
time curl -s -o /dev/null https://everydocs-app.klutch.sh/

2. Log Management

Configure proper logging:

config/environments/production.rb
config.log_level = :info
config.logger = ActiveSupport::Logger.new(STDOUT)
config.log_formatter = ::Logger::Formatter.new

3. Error Tracking

Consider integrating error tracking services:

  • Sentry
  • Honeybadger
  • Rollbar
  • Bugsnag

4. Performance Metrics

Track key metrics:

  • Request response times
  • Database query performance
  • Document upload/download speeds
  • Search query performance
  • User session duration

Troubleshooting Common Issues

Database Connection Errors

Problem: Application can’t connect to MySQL database

ActiveRecord::ConnectionNotEstablished
Could not connect to database

Solutions:

  1. Verify MySQL is running and accessible:

    Terminal window
    mysql -h your-mysql-app.klutch.sh -P 8000 -u everydocs -p

  2. Check environment variables are set correctly:

    Terminal window
    echo $EVERYDOCS_DB_HOST
    echo $EVERYDOCS_DB_PORT
    echo $EVERYDOCS_DB_NAME

  3. Ensure database exists:

    CREATE DATABASE IF NOT EXISTS everydocs;

  4. Verify user permissions:

    GRANT ALL PRIVILEGES ON everydocs.* TO 'everydocs'@'%';
    FLUSH PRIVILEGES;

Application Won’t Start

Problem: Container starts but application crashes

Solutions:

  1. Check logs in Klutch.sh dashboard for error messages

  2. Verify SECRET_KEY_BASE is set:

    Terminal window
    # Generate if missing
    rails secret

  3. Run database migrations:

    Terminal window
    bundle exec rails db:migrate RAILS_ENV=production

  4. Check for missing environment variables:

    Terminal window
    env | grep EVERYDOCS
    env | grep RAILS

Document Upload Failures

Problem: PDF uploads fail or timeout

Solutions:

  1. Check persistent volume is attached:

    Terminal window
    ls -la /var/everydocs-files

  2. Verify write permissions:

    Terminal window
    chmod 777 /var/everydocs-files

  3. Check disk space:

    Terminal window
    df -h /var/everydocs-files

  4. Increase file upload limits if needed:

    config/application.rb
    config.action_dispatch.max_request_upload_size = 50.megabytes

Full-Text Search Not Working

Problem: Search doesn’t find document content

Solutions:

  1. Check if encryption is enabled - Encrypted documents don’t support full-text search:

    SELECT email, encryption_activated_flag FROM users;

  2. Verify PDF text extraction - Ensure documents have extractable text:

    • Scanned PDFs without OCR won’t be searchable
    • Check if PDF has text layer using a PDF viewer

  3. Rebuild search index (if applicable):

    Terminal window
    bundle exec rails db:seed # Or equivalent reindexing command

Slow Performance

Problem: Application is slow or unresponsive

Solutions:

  1. Check resource allocation:

    • Increase CPU/RAM in Klutch.sh dashboard
    • Monitor resource usage during peak times

  2. Optimize database queries:

    -- Check slow queries
    SHOW FULL PROCESSLIST;
    

    -- Add missing indexes
    SHOW INDEX FROM documents;

  3. Clear Rails cache:

    Terminal window
    bundle exec rails cache:clear

  4. Reduce document storage size:

    • Archive old documents
    • Compress PDF files before upload

Authentication Issues

Problem: Can’t log in or JWT token errors

Solutions:

  1. Verify SECRET_KEY_BASE hasn’t changed:

    • Changing this invalidates all existing sessions

  2. Clear browser cookies and try again

  3. Check user exists in database:

    SELECT * FROM users WHERE email = 'your-email@example.com';

  4. Reset user password if needed:

    Terminal window
    bundle exec rails console
    user = User.find_by(email: 'your-email@example.com')
    user.update(password: 'newpassword')

Updating EveryDocs

To update your EveryDocs deployment to a newer version:

    1. Check for Updates

      Terminal window
      cd everydocs-core
      git fetch origin
      git log HEAD..origin/master --oneline

    2. Review Changelog

      Check the EveryDocs releases page for breaking changes and migration notes.

    3. Backup Everything

      Terminal window
      # Backup database
      mysqldump -h your-mysql-app.klutch.sh -P 8000 -u everydocs -p everydocs > backup_before_update.sql
      

      # Note current document count
      ls -1 /var/everydocs-files | wc -l

    4. Update Code

      Terminal window
      git pull origin master
      bundle install

    5. Run Migrations

      Terminal window
      bundle exec rails db:migrate RAILS_ENV=production

    6. Push to GitHub

      Terminal window
      git add .
      git commit -m "Update to EveryDocs version X.X.X"
      git push origin main

    7. Klutch.sh Auto-Deploy

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

    8. Verify Update

      • Check application logs for errors
      • Test document upload
      • Verify search functionality
      • Test API endpoints

Advanced Configuration

Integrating the Web Interface

EveryDocs Core provides the API backend. For the full web interface, deploy the companion project:

EveryDocs Web Interface

To integrate:

  1. Deploy everydocs-web separately
  2. Configure it to point to your EveryDocs Core API URL
  3. Set CORS headers in EveryDocs Core to allow the web interface domain

Custom Domain Setup

    1. Add Domain in Klutch.sh

      • Go to your app settings
      • Add your custom domain (e.g., docs.yourcompany.com)

    2. Configure DNS

      Add a CNAME record pointing to your Klutch.sh app:

      docs.yourcompany.com CNAME your-app.klutch.sh

    3. Update Environment Variables

      Update any hardcoded URLs to use your custom domain:

      APP_URL=https://docs.yourcompany.com

Email Notifications (Future Enhancement)

While EveryDocs Core doesn’t include built-in email notifications, you can extend it:

# Add to Gemfile
gem 'mail'


# Configure in config/environments/production.rb
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: 'smtp.gmail.com',
  port: 587,
  user_name: ENV['SMTP_USERNAME'],
  password: ENV['SMTP_PASSWORD'],
  authentication: 'plain',
  enable_starttls_auto: true
}

Multi-User Management

For organizations with multiple users:

  1. Create Admin User

    UPDATE users SET is_admin = 1 WHERE email = 'admin@company.com';

  2. Implement Role-Based Access

    Extend the user model to include roles:

    • Admin: Full access
    • Editor: Upload and edit documents
    • Viewer: Read-only access

  3. Set Up User Invitations

    Instead of open registration, implement invite-only user creation.

Resources and Further Reading

Official Documentation

Community and Support

Additional Tools

Conclusion

You’ve successfully deployed EveryDocs Core on Klutch.sh! Your document management system is now running with persistent storage for documents, MySQL database integration, and full API access. With features like full-text search, folder organization, optional encryption, and a mobile-friendly interface, you have a powerful tool for managing your digital documents.

Remember to:

  • Regularly backup your database and document files
  • Monitor disk usage as your document library grows
  • Keep the application and dependencies updated
  • Implement proper security measures for production use
  • Consider enabling encryption for sensitive documents

Whether you’re organizing personal documents, managing business records, or building a custom document workflow, EveryDocs on Klutch.sh provides a reliable, self-hosted solution with the flexibility to scale as your needs grow.

For questions or issues, consult the troubleshooting section above or reach out to the EveryDocs community on GitHub.