Deploying Colanode

Introduction

Colanode is a privacy-first, open-source collaboration platform that combines real-time document editing, task management, team communication, and knowledge sharing into a unified workspace. Built with modern web technologies, Colanode provides teams with a powerful alternative to proprietary collaboration tools like Notion, Confluence, and Asana, while maintaining complete control over their data.

Colanode is designed to be:

Privacy-Focused: Self-hosted solution with complete data ownership and control
Real-Time Collaboration: Live document editing with multiple users simultaneously
Feature-Rich: Integrated documents, tasks, wikis, and team communication in one platform
User-Friendly: Intuitive interface with drag-and-drop functionality and rich formatting
Extensible: Plugin architecture for custom integrations and workflows
Performance-Optimized: Fast loading times and responsive interface even with large datasets

Key features include:

Rich Document Editor: WYSIWYG editor with Markdown support, embedded media, code blocks, and tables
Task Management: Kanban boards, to-do lists, task assignments, and deadline tracking
Team Workspaces: Organize teams, projects, and departments with custom permissions
Real-Time Updates: See changes instantly as team members collaborate
Version History: Track document changes and restore previous versions
Search and Organization: Full-text search, tags, and hierarchical organization
File Attachments: Upload and share files directly within documents
Comments and Mentions: Inline comments and @mentions for team communication
Access Control: Granular permissions for users, teams, and resources
API Access: RESTful API for integrations and automation

This comprehensive guide walks you through deploying Colanode on Klutch.sh using Docker, including detailed installation steps, persistent storage configuration, database setup, environment variables, security best practices, and production-ready optimization techniques.

Prerequisites

Before you begin deploying Colanode to Klutch.sh, ensure you have the following:

A Klutch.sh account with access to the dashboard
A GitHub account with a repository for your Colanode project
Docker installed locally for testing (optional but recommended)
Basic understanding of Docker, Node.js, and PostgreSQL databases
A PostgreSQL database instance (can be external or deployed separately on Klutch.sh)
SMTP server credentials for email notifications (optional but recommended for production)
Basic knowledge of environment variables and web server configuration

Understanding Colanode Architecture

Technology Stack

Backend:

Node.js with Express framework for API server
PostgreSQL database for data persistence
Redis for session management and real-time features
WebSocket support for live collaboration
JWT-based authentication system

Frontend:

Modern JavaScript framework (React/Vue) for UI
Real-time editor with collaborative editing support
Responsive design for desktop and mobile
Progressive Web App (PWA) capabilities

Storage:

PostgreSQL for structured data (users, documents, tasks, permissions)
File system or S3-compatible storage for attachments
Redis for caching and real-time synchronization

Key Features Explained

Real-Time Collaboration:

Multiple users can edit documents simultaneously
Changes are synchronized instantly via WebSockets
Cursor position and selections are visible to collaborators
Conflict resolution for concurrent edits

Document Management:

Rich text editor with formatting options
Nested pages and hierarchical organization
Templates for common document types
Version control with restore functionality
Export options (Markdown, HTML, PDF)

Task Management:

Create tasks with descriptions, assignees, and deadlines
Kanban boards for visual workflow management
Task dependencies and subtasks
Priority levels and status tracking
Calendar views for deadline visualization

Team Collaboration:

Workspace organization by teams or projects
Role-based access control (Owner, Admin, Member, Guest)
Activity feeds for tracking changes
Notifications for mentions and assignments
Integration with external tools via API

Installation and Setup

Step 1: Create Your Project Directory

First, create a new directory for your Colanode deployment project:

mkdir colanode-deployment
cd colanode-deployment
git init

Step 2: Create Directory Structure

Create necessary directories for configuration and data:

mkdir -p config data uploads

Your project structure should look like this:

colanode-deployment/
├── Dockerfile
├── docker-entrypoint.sh
├── .dockerignore
├── .gitignore
├── config/
│   └── (configuration files)
├── data/
│   └── (database data - not committed)
└── uploads/
    └── (user uploads - not committed)

Step 3: Create the Dockerfile

Create a Dockerfile in your project root directory:

# Use Node.js LTS as base image
FROM node:20-alpine

# Set working directory
WORKDIR /app

# Install system dependencies
RUN apk add --no-cache \
    postgresql-client \
    curl \
    git \
    bash \
    tini

# Install Colanode
# Note: Replace with actual Colanode repository or npm package
RUN git clone https://github.com/colanode/colanode.git /tmp/colanode && \
    cd /tmp/colanode && \
    npm install --production && \
    npm run build && \
    mv /tmp/colanode/* /app/ && \
    rm -rf /tmp/colanode

# Create directories for persistent data
RUN mkdir -p /app/uploads /app/data /app/config && \
    chown -R node:node /app

# Copy entrypoint script
COPY docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.sh

# Expose application port
EXPOSE 3000

# Switch to non-root user
USER node

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

# Use tini as entrypoint for proper signal handling
ENTRYPOINT ["/sbin/tini", "--", "docker-entrypoint.sh"]

# Start the application
CMD ["node", "server.js"]

Step 4: Create Entrypoint Script

Create a docker-entrypoint.sh file for initialization:

#!/bin/bash
set -e

echo "Starting Colanode initialization..."

# Wait for PostgreSQL to be ready
if [ -n "$DATABASE_URL" ] || [ -n "$POSTGRES_HOST" ]; then
    echo "Waiting for PostgreSQL to be ready..."

    # Extract host from DATABASE_URL or use POSTGRES_HOST
    if [ -n "$DATABASE_URL" ]; then
        DB_HOST=$(echo $DATABASE_URL | sed -n 's/.*@\([^:]*\):.*/\1/p')
        DB_PORT=$(echo $DATABASE_URL | sed -n 's/.*:\([0-9]*\)\/.*/\1/p')
    else
        DB_HOST=${POSTGRES_HOST:-localhost}
        DB_PORT=${POSTGRES_PORT:-5432}
    fi

    until pg_isready -h "$DB_HOST" -p "$DB_PORT" -U postgres > /dev/null 2>&1; do
        echo "PostgreSQL is unavailable - sleeping"
        sleep 2
    done

    echo "PostgreSQL is ready!"
fi

# Wait for Redis to be ready (optional)
if [ -n "$REDIS_URL" ] || [ -n "$REDIS_HOST" ]; then
    echo "Waiting for Redis to be ready..."
    REDIS_HOST_CONN=${REDIS_HOST:-localhost}
    REDIS_PORT_CONN=${REDIS_PORT:-6379}

    until timeout 1 bash -c "cat < /dev/null > /dev/tcp/$REDIS_HOST_CONN/$REDIS_PORT_CONN" 2>/dev/null; do
        echo "Redis is unavailable - sleeping"
        sleep 2
    done

    echo "Redis is ready!"
fi

# Run database migrations
echo "Running database migrations..."
npm run migrate || echo "Migration failed or not needed"

# Create default admin user if configured
if [ -n "$ADMIN_EMAIL" ] && [ -n "$ADMIN_PASSWORD" ]; then
    echo "Checking for admin user..."
    npm run create-admin || echo "Admin user already exists or creation failed"
fi

# Start the application
echo "Starting Colanode application..."
exec "$@"

Make the script executable:

chmod +x docker-entrypoint.sh

Step 5: Create .dockerignore File

Create a .dockerignore file to exclude unnecessary files from your Docker build:

.git
.github
.gitignore
.env
.env.local
*.log
node_modules
npm-debug.log
.DS_Store
.vscode
.idea
data/
uploads/
*.md
README.md
docs/
tests/

Step 6: Create .gitignore File

Create a .gitignore file to exclude sensitive and generated files:

# Dependencies
node_modules/
npm-debug.log
yarn-error.log

# Environment variables
.env
.env.local
.env.production

# Data directories
data/
uploads/

# Logs
*.log
logs/

# OS files
.DS_Store
Thumbs.db

# IDE
.vscode/
.idea/
*.swp
*.swo

# Build outputs
dist/
build/

Step 7: Test Locally (Optional)

Before deploying to Klutch.sh, you can test your Colanode setup locally using Docker:

# Build the Docker image
docker build -t colanode:latest .

# Create a network for services
docker network create colanode-network

# Run PostgreSQL (for testing)
docker run -d \
  --name colanode-postgres \
  --network colanode-network \
  -e POSTGRES_DB=colanode \
  -e POSTGRES_USER=colanode \
  -e POSTGRES_PASSWORD=secure_password \
  postgres:15-alpine

# Run Redis (for testing)
docker run -d \
  --name colanode-redis \
  --network colanode-network \
  redis:7-alpine

# Run Colanode
docker run -d \
  --name colanode-app \
  --network colanode-network \
  -p 3000:3000 \
  -e DATABASE_URL="postgresql://colanode:secure_password@colanode-postgres:5432/colanode" \
  -e REDIS_URL="redis://colanode-redis:6379" \
  -e JWT_SECRET="your-jwt-secret-key" \
  -e APP_URL="http://localhost:3000" \
  -e ADMIN_EMAIL="admin@example.com" \
  -e ADMIN_PASSWORD="admin123" \
  -v $(pwd)/uploads:/app/uploads \
  colanode:latest

# Wait for the application to start
sleep 30

# Check if Colanode is running
curl http://localhost:3000/health

# Access the application
# Open http://localhost:3000 in your browser

# View logs
docker logs -f colanode-app

# Cleanup when done
docker stop colanode-app colanode-postgres colanode-redis
docker rm colanode-app colanode-postgres colanode-redis
docker network rm colanode-network

Step 8: Push to GitHub

Commit your configuration to your GitHub repository:

git add Dockerfile docker-entrypoint.sh .dockerignore .gitignore
git commit -m "Add Colanode Docker configuration for Klutch.sh deployment"
git remote add origin https://github.com/yourusername/colanode-deployment.git
git push -u origin main

Deploying to Klutch.sh

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

Deployment Steps

Log in to Klutch.sh Dashboard
Navigate to klutch.sh/app and sign in with your GitHub account.
Create a New Project
Go to the Projects section and click “Create Project”. Give your project a meaningful name such as “Colanode Collaboration Platform” or “Team Workspace”.
Create a New App
Navigate to the Apps section within your project and click “Create App” to start configuring your Colanode deployment.
Select Your Repository
- Choose GitHub as your Git source
- Select the repository containing your Dockerfile and configuration files
- Choose the branch you want to deploy (typically main or master)
Klutch.sh will automatically detect the Dockerfile in your repository root.
Configure Traffic Type
- Traffic Type: Select HTTP (Colanode serves web traffic)
- Internal Port: Set to 3000 (the default port where Colanode listens inside the container)

Set Environment Variables

Configure the following environment variables for your Colanode instance. These are critical for proper operation:

Database Configuration:

# PostgreSQL Database Connection
DATABASE_URL=postgresql://username:password@your-db-host:5432/colanode
# Or use individual variables:
POSTGRES_HOST=your-db-host.example.com
POSTGRES_PORT=5432
POSTGRES_DB=colanode
POSTGRES_USER=colanode_user
POSTGRES_PASSWORD=secure_database_password

Redis Configuration (for sessions and real-time features):

REDIS_URL=redis://your-redis-host:6379
# Or use individual variables:
REDIS_HOST=your-redis-host.example.com
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password

Application Configuration:

# Application URL (your Klutch.sh app URL)
APP_URL=https://example-app.klutch.sh
NODE_ENV=production

# Security - JWT Secret (generate with: openssl rand -base64 32)
JWT_SECRET=your-long-random-jwt-secret-key-here
SESSION_SECRET=your-long-random-session-secret-key-here

# Admin User (for initial setup)
ADMIN_EMAIL=admin@yourdomain.com
ADMIN_PASSWORD=change-this-secure-password
ADMIN_NAME=Administrator

# Application Settings
PORT=3000
MAX_FILE_SIZE=10485760
# 10MB in bytes (adjust as needed)
ALLOWED_FILE_TYPES=image/*,application/pdf,text/*,application/msword,application/vnd.openxmlformats-officedocument.*

Email Configuration (SMTP for notifications):

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
# Use 'true' for port 465
SMTP_USER=your-smtp-username
SMTP_PASSWORD=your-smtp-password
SMTP_FROM_EMAIL=noreply@yourdomain.com
SMTP_FROM_NAME=Colanode

Optional Features:

# Enable/disable features
ENABLE_REGISTRATION=true
# Allow new user signups
ENABLE_EMAIL_VERIFICATION=true
ENABLE_API=true
ENABLE_WEBHOOKS=true

# Rate limiting
RATE_LIMIT_WINDOW=15
# minutes
RATE_LIMIT_MAX_REQUESTS=100

# Logging
LOG_LEVEL=info
# Options: error, warn, info, debug

# Storage (if using S3-compatible storage)
STORAGE_TYPE=local
# Options: local, s3
S3_ENDPOINT=https://s3.amazonaws.com
S3_BUCKET=your-bucket-name
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_REGION=us-east-1

Security Note: Never commit sensitive credentials like database passwords, JWT secrets, or SMTP passwords to your repository. Always set them as environment variables in the Klutch.sh dashboard.

Configure Persistent Storage
Colanode requires persistent volumes for user uploads, database data, and application state. Configure the following volumes:

Volume 1 - User Uploads:
- Mount Path: /app/uploads
- Size: 10-50 GB (depending on expected file storage needs)
Volume 2 - Application Data:
- Mount Path: /app/data
- Size: 5-10 GB (for logs, cache, and temporary files)
Important Notes:
- These volumes are essential for data persistence across container restarts
- Choose volume sizes based on your team size and expected usage
- You can expand volumes later if needed through the Klutch.sh dashboard
- Without persistent volumes, all user data and uploads will be lost on container restart
Configure Compute Resources
Select appropriate resources based on your team size and usage:
- Small Team (1-10 users):
  - CPU: 1 core
  - RAM: 2 GB
  - Suitable for: Testing, small teams, light usage
- Medium Team (10-50 users):
  - CPU: 2 cores
  - RAM: 4 GB
  - Suitable for: Growing teams, regular usage
- Large Team (50-200 users):
  - CPU: 4 cores
  - RAM: 8 GB
  - Suitable for: Large organizations, heavy usage
- Enterprise (200+ users):
  - CPU: 8+ cores
  - RAM: 16+ GB
  - Suitable for: Very large deployments, high-traffic scenarios
You can always scale resources up or down based on actual usage patterns.
Deploy Your Application
Click “Create” to start the deployment. Klutch.sh will:
1. Clone your repository from GitHub
2. Detect the Dockerfile in the repository root
3. Build the Docker image with all dependencies
4. Attach the persistent volumes to the specified mount paths
5. Set all environment variables in the container
6. Start your Colanode container on port 3000
7. Assign a public URL (e.g., example-app.klutch.sh)
8. Configure automatic HTTPS with SSL/TLS certificates
The deployment process typically takes 3-5 minutes depending on the size of your application and dependencies.
Monitor Deployment Progress
You can monitor the deployment in real-time:
- Go to the Deployments tab in your app
- View build logs to track progress
- Check for any errors during the build or startup process
- Wait for the deployment status to show “Running”
Complete Initial Setup
Once deployment is complete:
1. Navigate to your app URL: https://example-app.klutch.sh
2. Log in with the admin credentials you set in environment variables (ADMIN_EMAIL and ADMIN_PASSWORD)
3. Immediately change the default admin password for security
4. Configure your workspace settings:
  - Set up your organization name and branding
  - Configure email templates
  - Set up user roles and permissions
  - Configure integrations if needed
5. Create your first workspace or project
6. Invite team members via email or share registration link
7. Test document creation and collaboration features
8. Verify file uploads are working correctly
9. Test real-time collaboration with another user
10. Review security and privacy settings
Verify Functionality
Test all critical features to ensure proper deployment:

Basic Functionality:
- User registration and login
- Password reset via email
- Dashboard access and navigation
Document Features:
- Create and edit documents
- Rich text formatting
- Save and auto-save functionality
- Version history
Collaboration Features:
- Real-time editing with multiple users
- Comments and mentions
- Activity feed updates
- Notifications
File Management:
- Upload files and attachments
- Download files
- Delete files
- Storage quota tracking
Task Management (if enabled):
- Create tasks and to-do lists
- Assign tasks to users
- Set deadlines and priorities
- Kanban board view
Permissions:
- User role assignments
- Access control for documents
- Team-based permissions
- Guest access
Check the application logs in Klutch.sh dashboard for any errors or warnings during testing.

Database Setup

Colanode requires a PostgreSQL database for storing all application data. You have several options for database hosting:

Option 1: External PostgreSQL Service

Use a managed PostgreSQL service for ease of maintenance:

Recommended Providers:

Setup Steps:

Create a PostgreSQL database instance
Create a database named colanode
Create a user with full permissions on the database
Note the connection details (host, port, username, password)
Configure SSL/TLS if available (recommended for production)
Add the database URL to your Klutch.sh environment variables

Connection String Format:

postgresql://username:password@host:port/database?sslmode=require

Option 2: Self-Hosted PostgreSQL on Klutch.sh

Deploy PostgreSQL separately on Klutch.sh:

Create a new app in your Klutch.sh project
Use the official PostgreSQL Docker image
Configure persistent storage for PostgreSQL data
Set appropriate environment variables
Use TCP traffic type on port 8000
Connect your Colanode app to the PostgreSQL internal URL

Database Configuration

Create Database and User (if using manual setup):

-- Connect to PostgreSQL as admin user
CREATE DATABASE colanode;
CREATE USER colanode_user WITH ENCRYPTED PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE colanode TO colanode_user;

-- Grant schema permissions
\c colanode
GRANT ALL ON SCHEMA public TO colanode_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO colanode_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO colanode_user;

Database Requirements:

PostgreSQL version 12 or higher (15+ recommended)
At least 1 GB of storage for small teams (scale based on usage)
SSL/TLS encryption enabled for production
Regular backups configured
Connection pooling for high-traffic scenarios

Database Migrations

Colanode automatically runs database migrations on startup via the entrypoint script. The migrations create necessary tables for:

Users and authentication
Documents and pages
Tasks and to-do items
Comments and activity logs
Files and attachments
Teams and workspaces
Permissions and access control

Manual Migration (if needed):

# Connect to your Colanode container
docker exec -it colanode-container bash

# Run migrations manually
npm run migrate

# Check migration status
npm run migrate:status

Redis Configuration (Optional but Recommended)

Redis is used for session management, caching, and real-time features. While optional, it significantly improves performance and enables real-time collaboration.

Option 1: External Redis Service

Recommended Providers:

Option 2: Self-Hosted Redis on Klutch.sh

Deploy Redis separately on Klutch.sh:

Create a new app using Redis Docker image
Configure persistent storage for Redis data
Use TCP traffic type on port 8000
Set appropriate memory limits
Configure Redis password for security
Connect Colanode to Redis via internal URL

Redis Connection String:

redis://:password@host:port

Redis Benefits

Session Management: Store user sessions for faster authentication
Caching: Cache frequently accessed data for improved performance
Real-Time: Enable WebSocket-based real-time collaboration
Task Queue: Background job processing for emails and notifications
Rate Limiting: Implement efficient rate limiting for API endpoints

Getting Started with Colanode

After deploying Colanode, here’s how to get started with your collaboration platform.

Access Your Instance

Navigate to your Colanode URL: https://example-app.klutch.sh
Admin Login

Use the admin credentials you set during deployment:
- Email: Your ADMIN_EMAIL
- Password: Your ADMIN_PASSWORD
Change Password

Immediately change your password:
- Go to User Settings → Security
- Click “Change Password”
- Set a strong, unique password
Configure Profile
- Upload a profile picture
- Set your display name
- Configure notification preferences

Creating Your First Workspace

Create Workspace
- Click “New Workspace” or ”+” button
- Enter workspace name (e.g., “Product Team”, “Marketing”)
- Add description (optional)
- Set workspace icon and color
Invite Team Members
- Go to Workspace Settings → Members
- Click “Invite Members”
- Enter email addresses (comma-separated for multiple)
- Select role: Owner, Admin, Member, or Guest
- Send invitations
Set Up Workspace Structure
- Create folders for different projects or categories
- Set up templates for recurring document types
- Configure workspace permissions and visibility

Creating Documents

Basic Document Creation:

Click “New Document” or press Ctrl+N (Windows) or Cmd+N (Mac)
Enter document title
Start typing content
Use formatting toolbar for rich text editing
Save automatically (or manually with Ctrl+S)

Rich Content Features:

# Heading 1
## Heading 2
### Heading 3

**Bold text** and *italic text*

- Bulleted list item 1
- Bulleted list item 2

1. Numbered list item 1
2. Numbered list item 2

[Link text](https://example.com)

`inline code`

```javascript
// Code block with syntax highlighting
function greet(name) {
  console.log(`Hello, ${name}!`);
}

Blockquote for emphasis

Column 1	Column 2	Column 3
Data 1	Data 2	Data 3

Task list item 1
Completed task
Task list item 2

**Embedded Content**:
- Images: Drag and drop or paste images directly
- Files: Attach PDFs, documents, spreadsheets
- Videos: Embed YouTube, Vimeo links
- Code snippets: Use fenced code blocks with syntax highlighting

### Real-Time Collaboration

**Collaborative Editing**:

1. Share document with team members
2. Multiple users can edit simultaneously
3. See real-time cursors and selections
4. Changes sync instantly across all clients
5. No manual refresh needed

**Comments and Mentions**:

- **Add Comment**: Select text → Click comment icon or press `Ctrl+Shift+M`
- **Mention User**: Type `@` followed by username
- **Resolve Comments**: Mark comments as resolved when addressed
- **Reply to Comments**: Have threaded discussions

**Activity Tracking**:
- See who viewed, edited, or commented on documents
- View revision history and restore previous versions
- Track document changes in activity feed

### Task Management

**Creating Tasks**:

1. Go to Tasks section or press `Ctrl+Shift+T`
2. Click "New Task"
3. Enter task title and description
4. Set assignee(s)
5. Add due date and priority
6. Add tags or labels
7. Save task

**Kanban Board View**:

┌──────────────┬──────────────┬──────────────┬──────────────┐ │ To Do │ In Progress │ Review │ Done │ ├──────────────┼──────────────┼──────────────┼──────────────┤ │ Task 1 │ Task 3 │ Task 5 │ Task 7 │ │ Task 2 │ Task 4 │ Task 6 │ Task 8 │ │ │ │ │ │ └──────────────┴──────────────┴──────────────┴──────────────┘

Drag and drop tasks between columns to update status.

**Task Features**:
- Subtasks and checklists
- Task dependencies
- Time tracking
- Recurring tasks
- Task templates
- Filters and sorting
- Calendar view

### File Management

**Uploading Files**:

1. Click "Upload" button or drag files into document
2. Select files from your computer
3. Files are automatically attached to current document
4. Supported formats: Images, PDFs, documents, spreadsheets, archives

**File Operations**:
- **Download**: Click file name or download icon
- **Preview**: Click file to preview (supported formats)
- **Delete**: Select file → Click delete icon
- **Rename**: Right-click file → Rename
- **Move**: Drag file to different document or folder

**Storage Management**:
- Monitor storage usage in Settings
- Set storage quotas per user or workspace
- Configure file retention policies
- Enable automatic file compression

### Search and Organization

**Search Features**:

Search operators:

title:“Project Plan” → Search in document titles
author:john → Search by document author
tag:important → Search by tag
created:>2024-01-01 → Search by creation date
modified:<7d → Modified in last 7 days

**Organization Tools**:
- **Folders**: Hierarchical organization structure
- **Tags**: Add multiple tags to documents
- **Favorites**: Star important documents for quick access
- **Recent**: Access recently viewed or edited documents
- **Archives**: Archive old documents to declutter

### Permissions and Security

**Permission Levels**:

| Role   | View | Edit | Comment | Share | Delete | Manage Members |
|--------|------|------|---------|-------|--------|----------------|
| Owner  | ✓    | ✓    | ✓       | ✓     | ✓      | ✓              |
| Admin  | ✓    | ✓    | ✓       | ✓     | ✓      | ✓              |
| Member | ✓    | ✓    | ✓       | ✓     | ✗      | ✗              |
| Guest  | ✓    | ✗    | ✓       | ✗     | ✗      | ✗              |

**Sharing Documents**:

1. Open document
2. Click "Share" button
3. Add users or generate share link
4. Set permissions (view, edit, comment)
5. Set expiration date (optional)
6. Send invitation or copy link

**Security Settings**:
- Enable two-factor authentication (2FA)
- Set password policies
- Configure session timeout
- Enable audit logging
- IP whitelist (if needed)
- SSO integration (if available)

---

## Advanced Features

### API Access

Colanode provides a RESTful API for programmatic access and integrations.

**Authentication**:

Generate an API token in User Settings → API Tokens.

**Example API Requests**:

```bash
# Get user profile
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://example-app.klutch.sh/api/v1/user/me

# List workspaces
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://example-app.klutch.sh/api/v1/workspaces

# Create a document
curl -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"New Document","content":"Hello World"}' \
  https://example-app.klutch.sh/api/v1/documents

# Get document by ID
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://example-app.klutch.sh/api/v1/documents/document-id

# Update document
curl -X PUT \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Updated content"}' \
  https://example-app.klutch.sh/api/v1/documents/document-id

# Delete document
curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://example-app.klutch.sh/api/v1/documents/document-id

API Documentation: Access interactive API documentation at: https://example-app.klutch.sh/api/docs

Webhooks

Configure webhooks to notify external services of events:

Supported Events:

Document created, updated, or deleted
User joined or left workspace
Comment added or resolved
Task created, updated, or completed
File uploaded or deleted

Webhook Configuration:

Go to Workspace Settings → Webhooks
Click “Add Webhook”
Enter webhook URL
Select events to monitor
Set secret for signature verification
Save webhook

Example Webhook Payload:

{
  "event": "document.created",
  "timestamp": "2024-12-05T10:30:00Z",
  "workspace_id": "workspace-123",
  "data": {
    "document_id": "doc-456",
    "title": "New Document",
    "author": "user-789",
    "created_at": "2024-12-05T10:30:00Z"
  },
  "signature": "sha256=..."
}

Integrations

Available Integrations:

Slack: Receive notifications in Slack channels
GitHub: Link issues and pull requests in documents
Jira: Sync tasks with Jira issues
Google Drive: Import/export documents
Zapier: Connect to 5000+ apps
Custom Webhooks: Build custom integrations

Setting Up Integrations:

Go to Settings → Integrations
Click on desired integration
Follow authentication flow
Configure integration settings
Test connection
Enable integration

Templates

Create reusable templates for common document types:

Template Types:

Meeting notes
Project proposals
Weekly reports
Product specifications
Bug reports
Team retrospectives
Onboarding checklists

Creating Templates:

Create a document with desired structure
Click document menu → “Save as Template”
Enter template name and description
Set template category
Make template available to workspace or organization

Using Templates:

Click “New from Template”
Select template
Document is created with pre-filled structure
Customize content as needed

Export and Backup

Export Options:

Markdown: Export documents as .md files
HTML: Export with formatting preserved
PDF: Print-friendly PDF export
JSON: Raw data export for backup
Bulk Export: Export entire workspace

Automated Backups:

# Example backup script (run via cron)
#!/bin/bash

# Set variables
API_TOKEN="your-api-token"
BACKUP_DIR="/backups/colanode"
DATE=$(date +%Y%m%d)

# Create backup directory
mkdir -p "$BACKUP_DIR/$DATE"

# Export all workspaces
curl -H "Authorization: Bearer $API_TOKEN" \
  https://example-app.klutch.sh/api/v1/export/workspaces \
  -o "$BACKUP_DIR/$DATE/workspaces.json"

# Export database (if you have access)
pg_dump -h your-db-host -U colanode_user colanode | \
  gzip > "$BACKUP_DIR/$DATE/database.sql.gz"

# Compress uploads directory
tar -czf "$BACKUP_DIR/$DATE/uploads.tar.gz" /app/uploads/

echo "Backup completed: $BACKUP_DIR/$DATE"

Production Best Practices

Security Recommendations

Authentication and Authorization:

Strong Passwords: Enforce minimum password length and complexity
Two-Factor Authentication (2FA): Enable for all admin accounts
Session Management: Set appropriate session timeouts (e.g., 24 hours)
API Security: Rotate API tokens regularly, use short-lived tokens
OAuth Integration: Use SSO with Google, Microsoft, or SAML providers
Rate Limiting: Prevent brute-force attacks with rate limits

Data Security:

Database Encryption: Enable encryption at rest for PostgreSQL
SSL/TLS: Use HTTPS only, disable HTTP in production
Secrets Management: Never commit secrets to Git, use environment variables
File Scanning: Implement antivirus scanning for uploaded files
Backup Encryption: Encrypt all backup files
GDPR Compliance: Implement data export and deletion features

Network Security:

Firewall Rules: Restrict database access to application server only
DDoS Protection: Use Cloudflare or similar for DDoS mitigation
IP Whitelisting: Restrict admin access to known IP ranges (optional)
Security Headers: Implement CSP, HSTS, X-Frame-Options headers

Monitoring and Auditing:

Audit Logs: Enable comprehensive audit logging for all user actions
Security Alerts: Set up alerts for suspicious activities
Regular Reviews: Periodically review user access and permissions
Vulnerability Scanning: Regularly scan for security vulnerabilities
Dependency Updates: Keep all dependencies up to date

Performance Optimization

Application Level:

Caching: Implement Redis caching for frequently accessed data
Database Indexing: Create indexes on frequently queried columns
Query Optimization: Optimize slow database queries
Lazy Loading: Load content on-demand rather than all at once
Image Optimization: Compress and resize images automatically
CDN: Use CDN for static assets and uploads (e.g., Cloudflare)

Database Optimization:

-- Create indexes for common queries
CREATE INDEX idx_documents_user_id ON documents(user_id);
CREATE INDEX idx_documents_workspace_id ON documents(workspace_id);
CREATE INDEX idx_documents_created_at ON documents(created_at DESC);
CREATE INDEX idx_tasks_assignee_id ON tasks(assignee_id);
CREATE INDEX idx_tasks_due_date ON tasks(due_date);

-- Analyze and vacuum database regularly
ANALYZE;
VACUUM;

-- Monitor slow queries
SELECT
  query,
  calls,
  total_time,
  mean_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

Redis Configuration:

# Optimize Redis for performance
REDIS_MAXMEMORY=2gb
REDIS_MAXMEMORY_POLICY=allkeys-lru
REDIS_SAVE=""  # Disable persistence if using only as cache

Server Resources:

Monitor CPU, memory, and disk I/O usage
Scale vertically (more CPU/RAM) for single-instance deployments
Consider horizontal scaling for very large deployments
Use connection pooling for database connections (e.g., pgBouncer)

File Storage:

Use S3-compatible storage for files instead of local filesystem
Implement CDN for file downloads
Enable gzip compression for text files
Set appropriate caching headers

Backup and Recovery

Backup Strategy:

Database Backups:

# Daily automated database backup
0 2 * * * pg_dump -h $DB_HOST -U $DB_USER $DB_NAME | \
  gzip > /backups/colanode-$(date +\%Y\%m\%d).sql.gz

# Retention: Keep 7 daily, 4 weekly, 6 monthly backups

File Backups:

# Backup uploads directory
0 3 * * * tar -czf /backups/uploads-$(date +\%Y\%m\%d).tar.gz /app/uploads/

# Sync to remote storage (S3, Backblaze, etc.)
0 4 * * * aws s3 sync /backups/ s3://your-backup-bucket/colanode/

Recovery Testing:

Test backup restoration quarterly
Document recovery procedures
Measure and document Recovery Time Objective (RTO) and Recovery Point Objective (RPO)
Practice disaster recovery scenarios

High Availability:

Set up database replication (primary/replica)
Use managed database services with automatic failover
Implement application-level health checks
Consider multi-region deployment for critical deployments

Monitoring and Logging

Application Monitoring:

Health Check Endpoint:

// Monitor this endpoint regularly
GET https://example-app.klutch.sh/health

Response:
{
  "status": "healthy",
  "database": "connected",
  "redis": "connected",
  "uptime": 86400,
  "version": "1.0.0"
}

Key Metrics to Monitor:

Application Metrics:
- Response time (p50, p95, p99)
- Request rate (requests per second)
- Error rate (5xx errors)
- Active user sessions
- WebSocket connections
- Database query time
- Cache hit rate

System Metrics:
- CPU usage
- Memory usage
- Disk I/O
- Network bandwidth
- Disk space available
- Database connections

Business Metrics:
- Active users (daily, weekly, monthly)
- Documents created
- Tasks completed
- Storage usage
- Collaboration sessions
- API requests

Logging Best Practices:

// Structured logging example
{
  "timestamp": "2024-12-05T10:30:00Z",
  "level": "info",
  "message": "User logged in",
  "user_id": "user-123",
  "ip_address": "192.168.1.1",
  "user_agent": "Mozilla/5.0...",
  "session_id": "session-456"
}

Log Aggregation:

Use centralized logging (e.g., ELK stack, Grafana Loki)
Set up alerts for critical errors
Retain logs for compliance requirements
Implement log rotation to manage disk space

Monitoring Tools:

Prometheus for metrics collection
Grafana for visualization
Datadog for full-stack monitoring
Sentry for error tracking
UptimeRobot for uptime monitoring

Scaling Strategies

Vertical Scaling (Increasing Resources):

Upgrade to larger Klutch.sh instance
Increase CPU and RAM allocation
Expand persistent volume sizes
Upgrade database instance size

Horizontal Scaling (Multiple Instances):

Deploy multiple Colanode instances behind a load balancer
Use shared PostgreSQL and Redis instances
Implement session affinity or shared session storage
Use S3-compatible storage for files (not local filesystem)

Database Scaling:

Implement read replicas for read-heavy workloads
Use connection pooling (pgBouncer)
Partition large tables by date or workspace
Consider sharding for very large deployments

Caching Strategy:

Cache frequently accessed documents in Redis
Implement edge caching with CDN
Use browser caching for static assets
Implement query result caching

Maintenance

Regular Maintenance Tasks:

Weekly:

Review application logs for errors
Check disk space on persistent volumes
Monitor active users and resource usage
Review failed authentication attempts

Monthly:

Update Docker image to latest stable version
Review and optimize slow database queries
Clean up old audit logs
Review and revoke unused API tokens
Test backup restoration

Quarterly:

Security audit and vulnerability scan
Performance review and optimization
Update dependencies and libraries
Review and update documentation
Disaster recovery drill

Annually:

Comprehensive security assessment
Infrastructure review and capacity planning
User access audit
Compliance review (if applicable)

Update Procedure:

# 1. Backup current deployment
# 2. Test new version in staging environment
# 3. Schedule maintenance window
# 4. Update Docker image in Dockerfile
# 5. Push to GitHub
# 6. Deploy new version via Klutch.sh
# 7. Monitor logs and metrics
# 8. Rollback if issues detected

Custom Domains

To use a custom domain with your Colanode instance:

Step 1: Add Domain in Klutch.sh

Go to your app settings in the Klutch.sh dashboard
Navigate to the Domains section
Click “Add Custom Domain”
Enter your domain (e.g., colanode.yourdomain.com or team.yourdomain.com)
Save the configuration

Step 2: Update DNS Configuration

Update your DNS provider with a CNAME record:

Type: CNAME
Name: colanode (or your subdomain)
Value: example-app.klutch.sh
TTL: 3600 (or auto)

Example DNS Records:

colanode.yourdomain.com.    CNAME    example-app.klutch.sh.
team.yourdomain.com.        CNAME    example-app.klutch.sh.

Step 3: Update Environment Variables

Update the APP_URL environment variable in Klutch.sh:

APP_URL=https://colanode.yourdomain.com

Redeploy the application for changes to take effect.

Step 4: Verify Configuration

Wait for DNS propagation (5-60 minutes)

Check DNS resolution:

nslookup colanode.yourdomain.com
# or
dig colanode.yourdomain.com CNAME

Access your Colanode instance at the custom domain
Verify HTTPS certificate is automatically provisioned by Klutch.sh
Test login and functionality

Troubleshooting:

DNS not resolving: Wait longer for propagation or check CNAME record
SSL certificate error: Wait for Klutch.sh to provision certificate (5-10 minutes)
Redirect issues: Verify APP_URL matches your custom domain exactly

Troubleshooting

Issue 1: Application Won’t Start

Symptoms: Container exits immediately or shows “Unhealthy” status

Solutions:

Check Environment Variables:
- Verify all required environment variables are set correctly
- Ensure DATABASE_URL or individual database variables are correct
- Check that JWT_SECRET and SESSION_SECRET are set
- Verify APP_URL matches your actual URL
Review Logs:
- Go to Klutch.sh dashboard → Your app → Logs
- Look for error messages during startup
- Common errors: database connection failed, missing environment variables
Database Connection:
- Test database connectivity from another tool
- Verify database credentials are correct
- Check that database host is accessible
- Ensure database and user exist
Check Port Configuration:
- Verify internal port is set to 3000
- Ensure traffic type is set to HTTP
Review Docker Build:
- Check build logs for any errors during image build
- Ensure all dependencies are installed correctly
- Verify Dockerfile syntax

Issue 2: Cannot Access Web Interface

Symptoms: 502 Bad Gateway, 503 Service Unavailable, or connection timeout

Solutions:

Verify Deployment Status:
- Check that app status shows “Running” in Klutch.sh dashboard
- Ensure no errors in recent deployment logs
Check Health Endpoint:
- Access the health endpoint: https://example-app.klutch.sh/health
- Should return JSON with status information
Review DNS:
- If using custom domain, verify DNS is configured correctly
- Test with original Klutch.sh URL first
Check Firewall/Security:
- Ensure your network allows HTTPS traffic
- Try accessing from different network or device
Container Restart:
- Restart the application from Klutch.sh dashboard
- Monitor logs during restart

Issue 3: Database Connection Errors

Symptoms: “Cannot connect to database”, “Connection refused”, “Authentication failed”

Solutions:

Verify Database Credentials:

# Test connection manually
psql "postgresql://username:password@host:port/database"

Check Database Status:
- Ensure PostgreSQL service is running
- Verify database exists: \l in psql
- Check user permissions: \du in psql
SSL/TLS Configuration:
- If database requires SSL, add ?sslmode=require to connection string
- For self-signed certificates, use ?sslmode=disable (not recommended for production)
Network Connectivity:
- Verify database host is accessible from Klutch.sh
- Check firewall rules allow connections from application
- Test with telnet db-host 5432
Connection Pool:
- Check if connection pool is exhausted
- Review active connections: SELECT count(*) FROM pg_stat_activity;
- Increase max connections in PostgreSQL config if needed

Issue 4: File Upload Failures

Symptoms: “Upload failed”, “File too large”, “Permission denied”

Solutions:

Check Volume Configuration:
- Verify persistent volume is mounted at /app/uploads
- Check volume has sufficient free space
- Review volume mount permissions
File Size Limits:
- Check MAX_FILE_SIZE environment variable
- Default is 10MB, increase if needed
- Verify web server/proxy limits (Klutch.sh handles this automatically)
File Type Restrictions:
- Check ALLOWED_FILE_TYPES environment variable
- Ensure file type is in allowed list
- Review MIME type detection
Storage Space:
- Monitor storage usage in Klutch.sh dashboard
- Expand volume if approaching capacity
- Clean up old/unused files
Permissions:
- Verify uploads directory has correct permissions
- Check container runs as correct user (node:node)

Issue 5: Real-Time Collaboration Not Working

Symptoms: Changes don’t sync, no live cursors, document conflicts

Solutions:

Check Redis Connection:
- Verify Redis is running and accessible
- Test Redis connection: redis-cli -h host -p port PING
- Check REDIS_URL environment variable
WebSocket Connection:
- Verify WebSocket connections are allowed
- Check browser console for WebSocket errors
- Ensure no proxy/firewall blocking WebSockets
Server Resources:
- Monitor CPU and memory usage
- High load can cause sync delays
- Scale up resources if needed
Browser Compatibility:
- Ensure browser supports WebSockets
- Try different browser
- Clear browser cache and cookies
Multiple Instances:
- If running multiple app instances, ensure shared Redis
- Verify session affinity or use sticky sessions

Issue 6: Email Notifications Not Sending

Symptoms: Users not receiving emails, email verification failing

Solutions:

SMTP Configuration:
- Verify all SMTP environment variables are set correctly
- Test SMTP credentials with email client
- Check SMTP host and port are correct
Authentication:
- Verify SMTP username and password
- Some providers require app-specific passwords
- Check if 2FA is enabled on email account
Port and Security:
- Port 587: Use SMTP_SECURE=false (STARTTLS)
- Port 465: Use SMTP_SECURE=true (SSL/TLS)
- Port 25: Usually blocked by cloud providers
Email Provider Limits:
- Check if hitting rate limits
- Verify account is in good standing
- Review provider’s sending limits
Application Logs:
- Check logs for SMTP errors
- Look for authentication failures
- Verify email queue is processing
Spam Filters:
- Check recipient’s spam/junk folder
- Configure SPF, DKIM, DMARC records for your domain
- Use reputable SMTP provider

Issue 7: High Memory Usage

Symptoms: Container using excessive memory, out of memory errors

Solutions:

Monitor Resource Usage:
- Check memory usage in Klutch.sh dashboard
- Identify memory leaks in logs
- Review active connections and sessions
Database Connection Pool:
- Limit database connection pool size
- Close unused connections
- Use connection pooling (pgBouncer)
Redis Memory:
- Configure Redis max memory limit
- Set appropriate eviction policy
- Monitor Redis memory usage
Cache Strategy:
- Review caching configuration
- Implement cache expiration
- Clear old cache entries
Scale Resources:
- Upgrade to larger instance with more RAM
- Add monitoring to track memory trends
- Optimize queries and data structures

Issue 8: Slow Performance

Symptoms: Slow page loads, laggy editor, delayed responses

Solutions:

Database Performance:

-- Find slow queries
SELECT query, mean_time, calls
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

-- Add indexes to frequently queried columns
CREATE INDEX idx_documents_user_workspace
ON documents(user_id, workspace_id);

Enable Caching:
- Verify Redis is connected and working
- Implement query result caching
- Use CDN for static assets

Optimize Database:

-- Vacuum and analyze
VACUUM ANALYZE;

-- Check table bloat
SELECT schemaname, tablename,
  pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename))
FROM pg_tables
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;

Resource Scaling:
- Increase CPU allocation
- Add more memory
- Upgrade database instance
Code Optimization:
- Review N+1 query problems
- Implement pagination for large datasets
- Optimize image loading and compression

Issue 9: Data Not Persisting

Symptoms: Data lost after container restart, uploads disappear

Solutions:

Verify Volumes:
- Check persistent volumes are attached in Klutch.sh
- Verify mount paths: /app/uploads, /app/data
- Ensure volumes have sufficient space
Check Mount Points:
- Logs should show volume mount points on startup
- Verify paths match between Dockerfile and Klutch.sh configuration
Permissions:
- Ensure application has write permissions to mounted volumes
- Check file ownership (should be node:node)
Database Persistence:
- Use external PostgreSQL service (not container-local)
- Verify database is not in-memory mode
- Check database connection is persistent

Issue 10: Authentication Issues

Symptoms: Cannot log in, session expires immediately, “Invalid token”

Solutions:

JWT Configuration:
- Verify JWT_SECRET is set and consistent
- Check secret hasn’t changed between deployments
- Ensure secret is long and random (32+ characters)
Session Configuration:
- Verify SESSION_SECRET is set
- Check Redis connection for session storage
- Review session timeout settings
Cookie Issues:
- Ensure APP_URL matches actual domain (including https://)
- Check browser allows cookies
- Clear browser cookies and try again
Database Issues:
- Verify user exists in database
- Check password hash is correct
- Reset password if needed
Time Synchronization:
- Ensure server time is correct
- JWT tokens are time-sensitive
- Check system clock on server

Additional Resources

Conclusion

Deploying Colanode to Klutch.sh provides your team with a powerful, privacy-first collaboration platform with complete control over your data. By following this comprehensive guide, you’ve learned how to:

Create a production-ready Dockerfile with proper initialization and health checks
Configure persistent storage for user uploads and application data
Set up PostgreSQL database connectivity for data persistence
Configure Redis for caching and real-time collaboration features
Deploy and manage Colanode on Klutch.sh’s infrastructure
Implement security best practices for authentication and data protection
Optimize performance for team collaboration at scale
Configure custom domains for branded access
Monitor system health and troubleshoot common issues
Implement backup and recovery strategies for business continuity

Your Colanode instance is now running on Klutch.sh’s global infrastructure with automatic HTTPS, scalable resources, and reliable hosting. The platform is ready to power your team’s collaboration with real-time document editing, task management, knowledge sharing, and seamless communication—all while maintaining complete data ownership and privacy.

For additional help, questions, or advanced configuration needs, consult the Colanode documentation, explore the API for custom integrations, join the community forums, or contact Klutch.sh support for infrastructure-related questions.

Deploying Colanode

Introduction

Prerequisites

Understanding Colanode Architecture

Technology Stack

Key Features Explained

Installation and Setup

Step 1: Create Your Project Directory

Step 2: Create Directory Structure

Step 3: Create the Dockerfile

Step 4: Create Entrypoint Script

Step 5: Create .dockerignore File

Step 6: Create .gitignore File

Step 7: Test Locally (Optional)

Step 8: Push to GitHub

Deploying to Klutch.sh

Deployment Steps

Database Setup

Option 1: External PostgreSQL Service

Option 2: Self-Hosted PostgreSQL on Klutch.sh

Database Configuration

Database Migrations

Redis Configuration (Optional but Recommended)

Option 1: External Redis Service

Option 2: Self-Hosted Redis on Klutch.sh

Redis Benefits

Getting Started with Colanode

First-Time Login

Creating Your First Workspace

Creating Documents

Webhooks

Integrations

Templates

Export and Backup

Production Best Practices

Security Recommendations

Performance Optimization

Backup and Recovery

Monitoring and Logging

Scaling Strategies

Maintenance

Custom Domains

Step 1: Add Domain in Klutch.sh

Step 2: Update DNS Configuration

Step 3: Update Environment Variables

Step 4: Verify Configuration

Troubleshooting

Issue 1: Application Won’t Start

Issue 2: Cannot Access Web Interface

Issue 3: Database Connection Errors

Issue 4: File Upload Failures

Issue 5: Real-Time Collaboration Not Working

Issue 6: Email Notifications Not Sending

Issue 7: High Memory Usage

Issue 8: Slow Performance

Issue 9: Data Not Persisting

Issue 10: Authentication Issues

Additional Resources

Conclusion