Skip to content
Klutch.sh Docs

Deploying a Cozy Cloud App

Introduction

Cozy Cloud is a personal cloud platform that puts you in control of your data. Unlike traditional cloud services where your information lives on someone else’s servers, Cozy Cloud gives you a private space where you can store files, manage contacts, sync calendars, backup photos, and run applications while maintaining complete ownership of your data.

What makes Cozy Cloud special is its approach to data sovereignty and privacy. Your data lives on infrastructure you control, yet you still get the convenience of cloud services. Cozy Cloud combines the functionality of Dropbox, Google Calendar, iCloud Photos, and more into a single, unified platform where your data remains truly yours. The platform also features an application store where you can install web apps that work with your data while respecting your privacy.

Whether you’re concerned about privacy, want to self-host your digital life, or simply prefer having complete control over your personal information, Cozy Cloud provides the tools and flexibility you need. Deploying Cozy Cloud on Klutch.sh gives you a production-ready personal cloud with persistent storage for your files and data, automated backups, and the ability to access your information from anywhere.

This comprehensive guide walks you through deploying Cozy Cloud on Klutch.sh, setting up persistent storage for your files and application data, configuring user accounts and authentication, installing applications from the Cozy store, and implementing best practices for maintaining your personal cloud infrastructure.

Why Deploy Cozy Cloud on Klutch.sh?

  • Automated Docker Detection: Klutch.sh automatically detects your Dockerfile in the repository root and builds your container without manual configuration
  • Data Sovereignty: Keep complete control of your personal data while enjoying cloud convenience
  • Persistent Storage: Built-in support for persistent volumes ensures your files, photos, and application data survive deployments
  • Secure by Default: Environment variables for sensitive credentials are encrypted and never exposed in logs
  • Production-Ready Infrastructure: Deploy your personal cloud with confidence using containerized infrastructure
  • Scalable Storage: Easily expand your storage capacity as your data grows
  • Global Accessibility: Access your personal cloud from anywhere with HTTPS enabled by default

Prerequisites

Before you begin deploying Cozy Cloud on Klutch.sh, ensure you have:

  • A Klutch.sh account with dashboard access
  • A GitHub account for repository hosting
  • Docker installed locally for testing (optional but recommended)
  • Basic understanding of personal cloud platforms and file synchronization
  • Familiarity with web applications and data management
  • Knowledge of Docker containers and deployment concepts
  • A domain name for your Cozy Cloud instance (recommended for production use)
  • Understanding of data backup strategies and recovery procedures

Understanding Cozy Cloud Architecture

Technology Stack

Cozy Cloud is built on modern web technologies designed for privacy and extensibility:

Core Platform:

  • Go (Golang) for the stack server with excellent performance and concurrency
  • CouchDB for flexible document storage with synchronization capabilities
  • Node.js for application runtime and build system
  • JavaScript/TypeScript for web applications and client interfaces
  • React for building interactive user interfaces

Key Components:

  • Stack Server: Core server written in Go that handles authentication, routing, and application management
  • CouchDB Database: Document database for storing application data with built-in replication and sync
  • File Storage System: Manages file uploads, versioning, and sharing with support for large files
  • Application Registry: Manages installed applications and their permissions
  • Authentication System: Handles user login, sessions, and OAuth integrations
  • Synchronization Engine: Keeps data synchronized across devices and applications
  • Permissions Framework: Granular control over what applications can access which data
  • Notification System: Manages real-time notifications and updates
  • Job Scheduler: Handles background tasks like file indexing and data synchronization

Features:

  • File storage and synchronization across devices
  • Contact management with CardDAV support
  • Calendar management with CalDAV support
  • Photo backup and organization with automatic uploads
  • Note-taking and document editing
  • Application marketplace for extending functionality
  • Data encryption at rest and in transit
  • WebDAV support for file access
  • Real-time collaboration on documents
  • Automatic file versioning and recovery
  • OAuth authentication with third-party services
  • Mobile applications for iOS and Android
  • Desktop synchronization clients
  • Two-factor authentication support

Installation and Setup

Step 1: Create Your Project Directory

Start by creating a new directory for your Cozy Cloud deployment project and initialize a Git repository:

Terminal window
mkdir cozy-cloud-klutch
cd cozy-cloud-klutch
git init

This directory will contain your Dockerfile, configuration files, and initialization scripts for your personal cloud.

Step 2: Create the Dockerfile

Create a Dockerfile in your project root directory. Klutch.sh will automatically detect this file and use it to build your container. Here’s a production-ready Dockerfile for Cozy Cloud:

FROM debian:bookworm-slim


# Set environment variables
ENV DEBIAN_FRONTEND=noninteractive
ENV COZY_ADMIN_PASSPHRASE=changeme


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


# Add Cozy repository and install Cozy Stack
RUN echo "deb [signed-by=/usr/share/keyrings/cozy-archive-keyring.gpg] https://apt.cozy.io/debian bookworm stable" \
    > /etc/apt/sources.list.d/cozy.list \
    && curl -fsSL https://apt.cozy.io/cozy.gpg.key | gpg --dearmor -o /usr/share/keyrings/cozy-archive-keyring.gpg \
    && apt-get update \
    && apt-get install -y cozy-stack \
    && rm -rf /var/lib/apt/lists/*


# Install CouchDB
RUN curl -fsSL https://couchdb.apache.org/repo/keys.asc | gpg --dearmor -o /usr/share/keyrings/couchdb-archive-keyring.gpg \
    && echo "deb [signed-by=/usr/share/keyrings/couchdb-archive-keyring.gpg] https://apache.jfrog.io/artifactory/couchdb-deb/ bookworm main" \
    > /etc/apt/sources.list.d/couchdb.list \
    && apt-get update \
    && apt-get install -y couchdb \
    && rm -rf /var/lib/apt/lists/*


# Create necessary directories
RUN mkdir -p /var/lib/cozy \
    /var/log/cozy \
    /etc/cozy \
    /data/cozy-storage \
    && chown -R couchdb:couchdb /var/lib/couchdb \
    && chown -R cozy:cozy /var/lib/cozy /var/log/cozy /data/cozy-storage


# Copy configuration files
COPY cozy.yml /etc/cozy/cozy.yml
COPY start-cozy.sh /usr/local/bin/start-cozy.sh
RUN chmod +x /usr/local/bin/start-cozy.sh


# Expose Cozy Stack port
EXPOSE 8080


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


# Start Cozy Stack
CMD ["/usr/local/bin/start-cozy.sh"]

Key Features of This Dockerfile:

  • Based on Debian Bookworm for stability and long-term support
  • Installs Cozy Stack from official repositories
  • Includes CouchDB for data persistence
  • Creates necessary directories for data storage
  • Exposes port 8080 for web interface access
  • Includes health check for monitoring
  • Supports environment variable configuration

Step 3: Create Cozy Configuration File

Create a cozy.yml configuration file for Cozy Stack:

# cozy.yml - Cozy Stack Configuration


host: 0.0.0.0
port: 8080


# Admin interface
admin:
  host: 0.0.0.0
  port: 6060


# File system configuration
fs:
  url: file:///data/cozy-storage


# CouchDB configuration
couchdb:
  url: http://127.0.0.1:5984


# Authentication
authentication:
  # Use environment variables for security
  secret: ${COZY_ADMIN_SECRET}


# Session configuration
sessions:
  secret: ${COZY_SESSION_SECRET}


# Vault for encryption
vault:
  credentials_encryptor_key: ${COZY_VAULT_KEY}
  credentials_decryptor_key: ${COZY_VAULT_KEY}


# Mail configuration (optional)
mail:
  host: ${MAIL_HOST}
  port: ${MAIL_PORT}
  username: ${MAIL_USERNAME}
  password: ${MAIL_PASSWORD}
  disable_tls: false


# Log level
log:
  level: info


# Assets
assets:
  path: /usr/share/cozy


# Download directory
downloads:
  url: file:///data/cozy-storage/downloads

Step 4: Create Startup Script

Create a start-cozy.sh script to initialize CouchDB and start Cozy Stack:

#!/bin/bash
set -e


echo "Starting Cozy Cloud services..."


# Start CouchDB in the background
echo "Starting CouchDB..."
su - couchdb -s /bin/bash -c '/opt/couchdb/bin/couchdb &'


# Wait for CouchDB to be ready
echo "Waiting for CouchDB to be ready..."
until curl -s http://127.0.0.1:5984/ > /dev/null; do
  echo "CouchDB is unavailable - sleeping"
  sleep 2
done


echo "CouchDB is ready"


# Initialize CouchDB if needed
if [ ! -f /var/lib/couchdb/.initialized ]; then
  echo "Initializing CouchDB..."


  # Set up CouchDB admin
  curl -X PUT http://127.0.0.1:5984/_node/_local/_config/admins/admin \
    -d "\"${COUCHDB_PASSWORD:-cozycloud}\""


  # Create system databases
  curl -X PUT http://admin:${COUCHDB_PASSWORD:-cozycloud}@127.0.0.1:5984/_users
  curl -X PUT http://admin:${COUCHDB_PASSWORD:-cozycloud}@127.0.0.1:5984/_replicator
  curl -X PUT http://admin:${COUCHDB_PASSWORD:-cozycloud}@127.0.0.1:5984/_global_changes


  touch /var/lib/couchdb/.initialized
  echo "CouchDB initialized"
fi


# Generate secrets if not provided
export COZY_ADMIN_SECRET=${COZY_ADMIN_SECRET:-$(openssl rand -hex 32)}
export COZY_SESSION_SECRET=${COZY_SESSION_SECRET:-$(openssl rand -hex 32)}
export COZY_VAULT_KEY=${COZY_VAULT_KEY:-$(openssl rand -hex 32)}


# Initialize Cozy Stack
echo "Initializing Cozy Stack..."
cozy-stack config passwd /etc/cozy/cozy.yml


# Start Cozy Stack
echo "Starting Cozy Stack..."
exec cozy-stack serve --config /etc/cozy/cozy.yml

Step 5: Create Instance Setup Script

Create an init-instance.sh script for creating your first Cozy instance:

#!/bin/bash


# init-instance.sh - Create a new Cozy instance


set -e


INSTANCE_DOMAIN="${COZY_DOMAIN:-cozy.local}"
INSTANCE_EMAIL="${COZY_EMAIL:-admin@example.com}"
INSTANCE_PASSPHRASE="${COZY_PASSPHRASE:-changeme}"


echo "Creating Cozy instance: ${INSTANCE_DOMAIN}"


# Wait for Cozy Stack to be ready
until curl -s http://localhost:8080/status > /dev/null; do
  echo "Waiting for Cozy Stack..."
  sleep 2
done


# Create instance
cozy-stack instances add ${INSTANCE_DOMAIN} \
  --email ${INSTANCE_EMAIL} \
  --passphrase ${INSTANCE_PASSPHRASE} \
  --apps home,store,drive,photos,contacts,notes,settings


echo "Cozy instance created successfully"
echo "Domain: ${INSTANCE_DOMAIN}"
echo "Email: ${INSTANCE_EMAIL}"
echo "You can now access your Cozy at http://${INSTANCE_DOMAIN}:8080"

Step 6: Test Locally with Docker (Optional)

Before deploying to Klutch.sh, you can test your Cozy Cloud setup locally:

Terminal window
# Build the Docker image
docker build -t my-cozy-cloud .


# Create a volume for persistent data
docker volume create cozy-data
docker volume create couchdb-data


# Run the container
docker run -d \
  --name cozy-cloud \
  -p 8080:8080 \
  -e COZY_DOMAIN=localhost \
  -e COZY_EMAIL=admin@example.com \
  -e COZY_PASSPHRASE=secure_password_here \
  -e COUCHDB_PASSWORD=couchdb_password \
  -v cozy-data:/data/cozy-storage \
  -v couchdb-data:/var/lib/couchdb \
  my-cozy-cloud


# Check logs
docker logs -f cozy-cloud


# Access Cozy at http://localhost:8080

When you’re done testing:

Terminal window
# Stop and remove containers
docker stop cozy-cloud
docker rm cozy-cloud
docker volume rm cozy-data couchdb-data

Step 7: Prepare Your Repository for Deployment

Commit your configuration files to your GitHub repository:

Terminal window
git add Dockerfile cozy.yml start-cozy.sh init-instance.sh
git commit -m "Add Cozy Cloud Docker configuration and setup scripts"
git remote add origin https://github.com/yourusername/cozy-cloud-klutch.git
git branch -M main
git push -u origin main

Environment Variables Configuration

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

Essential Environment Variables

Cozy Instance Configuration:

COZY_DOMAIN=example-app.klutch.sh
COZY_EMAIL=admin@example.com
COZY_PASSPHRASE=your_secure_passphrase_here

Security Secrets:

COZY_ADMIN_SECRET=your_random_admin_secret_32_chars
COZY_SESSION_SECRET=your_random_session_secret_32_chars
COZY_VAULT_KEY=your_random_vault_key_32_chars

CouchDB Configuration:

COUCHDB_PASSWORD=your_secure_couchdb_password
COUCHDB_HOST=127.0.0.1
COUCHDB_PORT=5984

Optional Environment Variables

Mail Configuration (for notifications and password resets):

MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=notifications@yourdomain.com
MAIL_PASSWORD=your_email_app_password
MAIL_FROM=noreply@yourdomain.com

Storage Configuration:

COZY_STORAGE_PATH=/data/cozy-storage
COZY_MAX_UPLOAD_SIZE=5368709120

Performance Tuning:

COZY_WORKERS=4
COZY_JOBS_WORKERS=2
COZY_MAX_CONNECTIONS=100

Logging:

COZY_LOG_LEVEL=info
COZY_LOG_FORMAT=json

Important Security Notes:

  • Always use strong, unique passphrases and passwords for production deployments
  • Generate random 32-character hexadecimal strings for secret keys using: openssl rand -hex 32
  • Never commit sensitive credentials to your Git repository
  • Use Klutch.sh’s environment variable management to securely store all secrets
  • Change default passwords immediately after first deployment
  • Enable two-factor authentication for admin access when possible

Persistent Storage Configuration

Cozy Cloud manages personal files, photos, application data, and database records that must persist across container restarts and deployments. You need to configure persistent volumes for critical directories.

Critical Directories for Persistence

  1. Cozy Storage (/data/cozy-storage) - User files, photos, documents, and application data
  2. CouchDB Data (/var/lib/couchdb) - Database files containing all Cozy data and configuration
  3. Cozy Configuration (/var/lib/cozy) - Application state and runtime configuration

When creating your Cozy Cloud app on Klutch.sh, attach persistent volumes with the following mount paths:

Primary Storage Volume:

  • Mount Path: /data/cozy-storage
  • Size: 50GB minimum (adjust based on expected usage)
  • Purpose: Store all user files, photos, documents, and application data

Database Volume:

  • Mount Path: /var/lib/couchdb
  • Size: 20GB minimum (grows with data)
  • Purpose: Store CouchDB database files and indexes

Configuration Volume:

  • Mount Path: /var/lib/cozy
  • Size: 5GB (for application state)
  • Purpose: Store Cozy Stack configuration and application state

Volume Size Recommendations

  • Personal Use (1 user, moderate files): 50GB storage, 20GB database, 5GB config
  • Family Use (2-5 users): 100GB storage, 30GB database, 5GB config
  • Power User (heavy file usage, many photos): 200GB+ storage, 50GB+ database, 10GB config
  • Small Team (5-10 users): 500GB+ storage, 100GB+ database, 10GB config

Storage requirements depend on how many files and photos you plan to store. Photos typically require the most space, so plan accordingly for your use case.

Deploying to Klutch.sh

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

Deployment Steps

    1. Log in to Klutch.sh

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

    2. Create a New Project

      From your dashboard, create a new project. Give it a meaningful name like “Personal Cloud” to organize your deployments.

    3. Create a New App

      Within your project, create a new app for your Cozy Cloud instance.

    4. Select Your Repository

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

    5. Configure Traffic Type

      • Traffic Type: Select HTTP (Cozy Cloud serves a web interface)
      • Internal Port: Set to 8080 (Cozy Stack’s default HTTP port)

    6. Set Environment Variables

      In the environment variables section, add all the Cozy configuration variables listed in the “Environment Variables Configuration” section above. Ensure sensitive values like passwords and secret keys are marked as secrets.

      Critical Variables (minimum required):

      • COZY_DOMAIN - Set to your app’s domain (will be example-app.klutch.sh)
      • COZY_EMAIL - Your admin email address
      • COZY_PASSPHRASE - A strong passphrase for your admin account
      • COZY_ADMIN_SECRET - Random 32-character hex string
      • COZY_SESSION_SECRET - Random 32-character hex string
      • COZY_VAULT_KEY - Random 32-character hex string
      • COUCHDB_PASSWORD - Secure password for CouchDB

    7. Attach Persistent Volumes

      This is critical for preserving your personal data. Add volumes for:

      Primary Storage Volume:

      • Mount Path: /data/cozy-storage
      • Size: 50GB (or larger based on your needs)

      Database Volume:

      • Mount Path: /var/lib/couchdb
      • Size: 20GB (or larger for extensive data)

      Configuration Volume:

      • Mount Path: /var/lib/cozy
      • Size: 5GB

    8. Configure Compute Resources

      Select appropriate compute resources based on your usage:

      • Personal Use: 1 CPU, 2GB RAM (sufficient for individual use)
      • Family Use: 2 CPU, 4GB RAM (recommended for multiple users)
      • Heavy Use: 4+ CPU, 8GB+ RAM (for many users or intensive file operations)

    9. Deploy Your Application

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

      • Automatically detect your Dockerfile in the repository root
      • Build the Docker image with your configuration
      • Attach the persistent volumes you specified
      • Deploy the container with your environment variables
      • Assign a URL for accessing your Cozy Cloud instance

    10. Access Your Cozy Cloud Instance

      Once deployment is complete, you’ll receive a URL like example-app.klutch.sh. Navigate to this URL in your browser to access your Cozy Cloud interface. On first access, you’ll be prompted to log in with the email and passphrase you configured.

    11. Initialize Your Instance

      After first login, complete the setup wizard:

      • Verify your email address
      • Configure your profile
      • Install default applications from the Cozy Store
      • Set up synchronization for your devices

Getting Started with Cozy Cloud

After deployment, follow these steps to start using your personal cloud.

Initial Setup and Configuration

  1. Access Your Cozy Cloud

    Navigate to your Klutch.sh app URL (e.g., https://example-app.klutch.sh) and log in with your configured credentials.

  2. Complete Profile Setup

    • Add your full name and profile picture
    • Configure locale and timezone preferences
    • Set up password recovery options
    • Enable two-factor authentication for enhanced security

  3. Install Applications

    From the Cozy Store, install essential applications:

    • Cozy Drive: File storage and synchronization
    • Cozy Photos: Photo backup and organization
    • Cozy Contacts: Contact management with CardDAV
    • Cozy Calendar: Calendar with CalDAV support
    • Cozy Notes: Note-taking and document editing
    • Cozy Banks: Financial tracking and analysis
    • Cozy Passwords: Secure password management

  4. Configure File Synchronization

    Install the Cozy Drive desktop client on your computers:

    • Download from cozy.io/download
    • Enter your Cozy URL: https://example-app.klutch.sh
    • Log in with your credentials
    • Choose folders to synchronize

File Management and Storage

Upload Files via Web Interface:

  1. Open Cozy Drive application
  2. Click “Upload” button
  3. Select files or drag and drop
  4. Files are immediately synced across all devices

Create Folders and Organize:

My Documents/
├── Work/
│   ├── Projects/
│   └── Reports/
├── Personal/
│   ├── Taxes/
│   └── Medical/
└── Photos/
    ├── 2024/
    └── 2025/

Share Files and Folders:

  1. Right-click on a file or folder
  2. Select “Share”
  3. Generate sharing link with optional password and expiration
  4. Send link to recipients

Photo Backup and Management

Enable Automatic Photo Backup:

  1. Install Cozy Drive mobile app on iOS or Android
  2. Open app settings
  3. Enable “Automatic photo backup”
  4. Choose backup quality (original or compressed)
  5. Photos automatically upload when connected to WiFi

Organize Photos:

  • Cozy automatically organizes photos by date
  • Create albums to group related photos
  • Add tags for easy searching
  • Face recognition for finding people (optional)

Contact and Calendar Synchronization

Sync Contacts with CardDAV:

Configure your phone or email client:

Server: https://example-app.klutch.sh
Username: your-email@example.com
Password: your-cozy-passphrase
CardDAV Path: /dav/contacts

Sync Calendar with CalDAV:

Server: https://example-app.klutch.sh
Username: your-email@example.com
Password: your-cozy-passphrase
CalDAV Path: /dav/calendars

Using Cozy with External Applications

WebDAV File Access:

Connect to Cozy files using WebDAV in file managers:

WebDAV URL: https://example-app.klutch.sh/files
Username: your-email@example.com
Password: your-cozy-passphrase

Integration with Mobile Apps:

Many mobile apps support WebDAV and can connect directly to Cozy:

  • Document editors (Microsoft Office, LibreOffice)
  • Photo management apps
  • Media players
  • Backup applications

API Access and Development

Accessing the Cozy API:

// JavaScript example - Fetch files from Cozy
const cozyClient = require('cozy-client');


const client = new cozyClient({
  uri: 'https://example-app.klutch.sh',
  token: 'your-api-token'
});


// List files
const files = await client.query({
  doctype: 'io.cozy.files',
  selector: { type: 'file' }
});


console.log('Files:', files.data);

Creating Custom Applications:

Build custom Cozy applications using the Cozy SDK:

// Initialize Cozy application
import CozyClient from 'cozy-client';


const client = new CozyClient({
  uri: 'https://example-app.klutch.sh',
  schema: {
    todos: {
      doctype: 'io.cozy.todos',
      attributes: {},
      relationships: {}
    }
  }
});


// Create a new document
await client.create('io.cozy.todos', {
  label: 'Buy groceries',
  done: false,
  createdAt: new Date()
});

Python Integration Example:

import requests
import json


class CozyClient:
    def __init__(self, url, token):
        self.url = url
        self.token = token
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }


    def list_files(self, dir_id='io.cozy.files.root-dir'):
        response = requests.get(
            f'{self.url}/files/{dir_id}/relationships/contents',
            headers=self.headers
        )
        return response.json()


    def upload_file(self, file_path, destination):
        with open(file_path, 'rb') as f:
            files = {'file': f}
            response = requests.post(
                f'{self.url}/files/{destination}',
                headers={'Authorization': f'Bearer {self.token}'},
                files=files
            )
        return response.json()


# Usage
client = CozyClient('https://example-app.klutch.sh', 'your-api-token')
files = client.list_files()
print(f"Found {len(files['data'])} files")

Production Best Practices

Security Recommendations

Account Security:

  • Use a strong, unique passphrase with at least 16 characters
  • Enable two-factor authentication (2FA) for admin access
  • Regularly review installed applications and their permissions
  • Use the password manager app to generate secure passwords
  • Set up account recovery options before you need them

Data Protection:

  • Enable encryption for sensitive documents
  • Regularly review sharing links and revoke unused ones
  • Use password protection for shared files
  • Set expiration dates on temporary shares
  • Monitor login history for suspicious activity

Network Security:

  • Always access Cozy over HTTPS (Klutch.sh provides this automatically)
  • Use a VPN when accessing from public networks
  • Configure firewall rules if exposing to the internet
  • Keep all desktop and mobile clients updated
  • Review OAuth application authorizations regularly

Backup Strategy:

# Example backup script for Cozy data
#!/bin/bash
BACKUP_DIR="/backup/cozy"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)


# Backup CouchDB
docker exec cozy-cloud couchdb-backup \
  --host 127.0.0.1 \
  --output /backup/couchdb-${TIMESTAMP}.tar.gz


# Backup file storage
tar -czf "${BACKUP_DIR}/storage-${TIMESTAMP}.tar.gz" \
  /data/cozy-storage


# Keep backups for 30 days
find "${BACKUP_DIR}" -name "*.tar.gz" -mtime +30 -delete

Performance Optimization

Storage Management:

  • Regularly review and clean up old files
  • Use selective sync to avoid downloading all files
  • Compress large files before uploading
  • Archive old photos to free up space
  • Monitor disk usage in Cozy Settings

Database Optimization:

  • CouchDB compaction happens automatically, but monitor database size
  • Review and remove unused applications
  • Clear browser cache if web interface becomes slow
  • Restart Cozy Stack periodically for optimal performance

Upload and Sync Performance:

  • Enable upload throttling to avoid bandwidth saturation
  • Schedule large uploads during off-peak hours
  • Use wired connections for initial sync of large libraries
  • Configure selective sync for large photo libraries
  • Batch file operations when possible

Client Configuration:

  • Limit concurrent sync connections (typically 3-5)
  • Configure bandwidth limits for desktop clients
  • Use mobile app settings to control cellular uploads
  • Enable smart sync to download only recently accessed files

Monitoring and Maintenance

Health Monitoring:

  • Check Cozy admin interface regularly for system status
  • Monitor disk space usage for storage volumes
  • Review application logs for errors or warnings
  • Track database growth and plan for expansion
  • Monitor memory and CPU usage through Klutch.sh dashboard

Regular Maintenance Tasks:

  • Weekly: Review shared links and permissions
  • Monthly: Check for Cozy Stack updates
  • Monthly: Verify backup integrity
  • Quarterly: Review and clean up old files
  • Quarterly: Audit installed applications and remove unused ones
  • Annually: Review and rotate security credentials

Update Strategy:

Keep your Cozy Cloud installation up to date:

  1. Check for updates in the Cozy admin interface
  2. Review release notes for breaking changes
  3. Test updates in a development environment first
  4. Schedule updates during low-usage periods
  5. Backup all data before major updates
  6. Monitor application logs after updates

Scaling Considerations

Single User to Family:

  • Start with 50GB storage, expand as needed
  • Monitor user activity and storage patterns
  • Add users gradually to assess performance impact
  • Consider creating separate instances for teams

Storage Expansion:

  • Klutch.sh allows expanding persistent volumes without downtime
  • Plan storage expansion before reaching 80% capacity
  • Archive old data to external storage if needed
  • Consider lifecycle policies for automatic data management

Performance Scaling:

  • Vertical scaling (more CPU/RAM) sufficient for most personal use
  • Monitor CouchDB performance metrics
  • Consider read replicas for high-availability setups
  • Optimize photo storage with compression settings

Troubleshooting

Common Issues and Solutions

Issue: Cannot Access Cozy Cloud Web Interface

  • Check: Verify the container is running in Klutch.sh dashboard
  • Check: Confirm internal port 8080 is correctly configured
  • Check: Ensure HTTP traffic type is selected (not TCP)
  • Check: Review container logs for startup errors
  • Solution: Restart the deployment if configuration was changed
  • Solution: Verify environment variables are set correctly

Issue: Cannot Log In with Credentials

  • Check: Verify COZY_EMAIL and COZY_PASSPHRASE environment variables
  • Check: Ensure passphrase doesn’t contain special characters that need escaping
  • Check: Check if instance was initialized correctly
  • Solution: Review logs for authentication errors
  • Solution: Use password recovery if available
  • Solution: Recreate instance with correct credentials

Issue: Files Not Syncing

  • Check: Verify desktop or mobile client is connected
  • Check: Confirm sufficient storage space in Cozy Cloud
  • Check: Check network connectivity and firewall rules
  • Check: Review sync client logs for errors
  • Solution: Restart sync clients
  • Solution: Verify COZY_DOMAIN matches your actual domain
  • Solution: Check persistent volume has available space

Issue: CouchDB Connection Errors

  • Cause: CouchDB not starting properly or wrong credentials
  • Check: Verify CouchDB is running inside container
  • Check: Confirm COUCHDB_PASSWORD matches configuration
  • Solution: Check CouchDB logs: docker logs <container> | grep couchdb
  • Solution: Restart container to reinitialize CouchDB
  • Solution: Verify database volume is properly mounted

Issue: Persistent Data Lost After Redeployment

  • Cause: Persistent volumes not properly attached
  • Check: Verify volume mount paths match exactly: /data/cozy-storage, /var/lib/couchdb, /var/lib/cozy
  • Check: Confirm volumes have sufficient available space
  • Solution: Re-attach volumes with correct mount paths before deploying
  • Solution: Restore from backups if data was lost

Issue: High Memory Usage

  • Cause: Large file uploads or many concurrent syncs
  • Solution: Increase container RAM allocation in Klutch.sh
  • Solution: Limit concurrent uploads in client settings
  • Solution: Reduce number of applications running simultaneously
  • Solution: Restart Cozy Stack to clear memory

Issue: Slow Photo Upload or Backup

  • Check: Verify network bandwidth is sufficient
  • Check: Confirm upload isn’t being throttled
  • Solution: Compress photos before uploading (mobile app setting)
  • Solution: Use WiFi instead of cellular for large uploads
  • Solution: Upload in smaller batches
  • Solution: Schedule uploads during off-peak hours

Issue: Applications Not Installing from Store

  • Check: Verify internet connectivity from container
  • Check: Check Cozy Stack logs for download errors
  • Solution: Clear application cache
  • Solution: Restart Cozy Stack
  • Solution: Manually install application from GitHub

Getting Help

If you encounter issues not covered here:

Advanced Configuration

Custom Domain Configuration

Use your own domain instead of the default Klutch.sh subdomain:

  1. Configure your custom domain in Klutch.sh (see custom domains guide)
  2. Update DNS records to point to your Klutch.sh app
  3. Update COZY_DOMAIN environment variable to your custom domain
  4. Redeploy the application
  5. Update all connected clients with new domain

Email Server Integration

Configure Cozy to send notifications and password reset emails:

MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-specific-password
MAIL_FROM=noreply@yourdomain.com
MAIL_TLS=true

For Gmail, create an app-specific password in your Google Account settings.

Multiple User Setup

Create additional user accounts for family members or team:

Terminal window
# Connect to running container
docker exec -it <container-id> bash


# Create additional instance
cozy-stack instances add user2.example-app.klutch.sh \
  --email user2@example.com \
  --passphrase user2_password


# Or create users within existing instance
cozy-stack instances add-user example-app.klutch.sh \
  --email newuser@example.com \
  --passphrase secure_password

Backup and Recovery Automation

Implement automated backup strategy:

#!/bin/bash
# backup-cozy.sh - Automated Cozy backup


BACKUP_DIR="/backup/cozy"
RETENTION_DAYS=30
TIMESTAMP=$(date +%Y%m%d_%H%M%S)


# Create backup directory
mkdir -p "${BACKUP_DIR}"


# Backup CouchDB
echo "Backing up CouchDB..."
docker exec cozy-cloud \
  couchdb-backup \
  --host 127.0.0.1 \
  --output /tmp/couchdb-backup.tar.gz


docker cp cozy-cloud:/tmp/couchdb-backup.tar.gz \
  "${BACKUP_DIR}/couchdb-${TIMESTAMP}.tar.gz"


# Backup file storage
echo "Backing up file storage..."
docker exec cozy-cloud \
  tar -czf /tmp/storage-backup.tar.gz /data/cozy-storage


docker cp cozy-cloud:/tmp/storage-backup.tar.gz \
  "${BACKUP_DIR}/storage-${TIMESTAMP}.tar.gz"


# Remove old backups
find "${BACKUP_DIR}" -name "*.tar.gz" -mtime +${RETENTION_DAYS} -delete


echo "Backup completed: ${TIMESTAMP}"

Schedule with cron:

Terminal window
# Run daily at 2 AM
0 2 * * * /path/to/backup-cozy.sh >> /var/log/cozy-backup.log 2>&1

OAuth Provider Configuration

Enable login with external providers (Google, GitHub, etc.):

Update cozy.yml with OAuth settings:

authentication:
  google:
    client_id: ${GOOGLE_CLIENT_ID}
    client_secret: ${GOOGLE_CLIENT_SECRET}
  github:
    client_id: ${GITHUB_CLIENT_ID}
    client_secret: ${GITHUB_CLIENT_SECRET}

Add environment variables in Klutch.sh dashboard.

Advanced File Versioning

Configure automatic file versioning:

fs:
  versioning:
    max_number_of_versions_to_keep: 10
    min_delay_between_two_versions: 1h

This keeps up to 10 versions of each file, creating new versions at most once per hour.

Additional Resources

Conclusion

Deploying Cozy Cloud on Klutch.sh gives you a powerful personal cloud platform where you maintain complete control over your data. With automated Docker detection, persistent storage for files and databases, secure environment variable management, and seamless synchronization across devices, Klutch.sh makes it easy to host your own private cloud infrastructure.

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

  • Create a production-ready Dockerfile for Cozy Cloud with CouchDB integration
  • Configure persistent volumes for files, photos, and database storage
  • Set up environment variables securely for authentication and mail services
  • Install and configure applications from the Cozy Store
  • Sync files, photos, contacts, and calendars across devices
  • Access your data via WebDAV, CalDAV, and CardDAV protocols
  • Integrate Cozy Cloud with external applications using the API
  • Implement security best practices and backup strategies
  • Monitor and maintain your personal cloud infrastructure
  • Troubleshoot common deployment and operational issues

Your Cozy Cloud instance is now ready to serve as your personal cloud, providing file storage, photo backup, contact management, calendar synchronization, and application hosting while keeping your data private and under your control. As your storage needs grow, you can easily scale your Klutch.sh deployment by expanding persistent volumes and allocating additional compute resources.