Colanode

Comprehensive Overview of Colanode: An Open-Source, Local-First Collaboration Workspace

Introduction to Colanode

Colanode represents a groundbreaking innovation in collaborative workspace software by offering an open-source alternative to traditional cloud-based project management and communication tools. Positioned as a local-first platform, it prioritizes user data privacy, security, and control—ensuring that teams can manage their work without relying on external servers or third-party services. Unlike conventional collaboration tools that centralize data in remote databases, Colanode empowers users to self-host its infrastructure, allowing them to run the entire system independently while retaining full ownership of their information.

The platform is designed for both individuals and teams, providing a seamless experience whether working alone on personal projects or collaborating across large organizations. Its architecture supports real-time communication, document editing, database management, and file storage—all within a unified interface that adapts to diverse workflow needs. With its self-hosted model, Colanode eliminates concerns about data breaches, compliance issues, or vendor lock-in, making it an ideal choice for privacy-conscious users and organizations prioritizing autonomy.

Core Features of Colanode

1. Real-Time Chat

One of the foundational elements of Colanode is its real-time chat functionality, enabling instant messaging within teams and across projects. This feature allows users to engage in live discussions, share updates, and coordinate tasks without delays. The platform supports both one-on-one conversations and group chats, making it versatile for small teams or large-scale collaboration.

The chat system is designed to be intuitive, ensuring minimal disruption to workflows while maintaining seamless connectivity. Users can send messages, attach files, and even embed links directly within conversations, fostering efficient communication regardless of location. Colanode’s real-time capabilities ensure that updates are synchronized instantly across all connected devices, reducing the need for manual message forwarding or delayed responses.

2. Rich Text Pages

A defining aspect of Colanode is its rich text editing interface, reminiscent of popular tools like Notion but with a focus on local-first functionality. Users can create documents, wikis, and notes using an intuitive editor that supports formatting options such as headings, bullet points, code blocks, and embedded media.

The platform’s rich text pages allow for collaborative editing, enabling multiple users to work simultaneously on the same document. This feature is particularly useful for teams that rely on shared knowledge bases or project documentation. The editor also integrates with Markdown syntax, providing flexibility for users who prefer a lightweight markup language over traditional WYSIWYG (What You See Is What You Get) interfaces.

Additionally, Colanode’s rich text pages support version history and rollback functionality, ensuring that changes can be tracked and reverted if necessary. This feature is crucial for maintaining document integrity, especially in collaborative environments where multiple contributors may introduce edits over time.

3. Customizable Databases

Colanode offers a highly customizable database system that allows users to organize information in structured formats. Unlike traditional relational databases, Colanode’s solution leverages dynamic views, enabling users to display data in tables, kanban boards, or calendar formats—depending on their workflow requirements.

The platform supports custom fields and dynamic queries, allowing teams to tailor database schemas to specific project needs. For example:

A kanban board can be used for task management, where tasks are organized into columns (e.g., "To Do," "In Progress," "Done").
A calendar view can track deadlines, meetings, or project milestones.
A table format allows for structured data entry, such as tracking inventory, client information, or financial records.

This flexibility ensures that users can adapt the database system to their unique workflows without relying on external tools. The ability to create and manage databases locally means that sensitive information remains within the user’s control, further enhancing privacy.

4. File Management

File management is a critical component of Colanode, providing users with a secure and efficient way to store, share, and collaborate on documents, images, videos, and other media files. The platform supports:

Local storage for immediate access without internet dependency.
Cloud-based backups (when self-hosting) for redundancy and disaster recovery.
File sharing permissions, allowing users to grant or restrict access based on role within a workspace.

Files can be uploaded directly from the user’s device, attached to messages, or embedded into rich text pages. Colanode also supports version control for files, ensuring that changes are tracked and recoverable if needed. This feature is particularly valuable in collaborative environments where multiple users may edit the same file simultaneously.

For self-hosted deployments, Colanode integrates with various storage backends, including:

Local filesystem (default option).
S3-compatible services (e.g., MinIO for local testing or AWS S3 for cloud deployment).
Google Cloud Storage and Azure Blob Storage, enabling users to leverage existing cloud infrastructure.

This flexibility ensures that Colanode can be deployed in environments where traditional file storage solutions may not meet requirements, such as high-performance computing clusters or distributed networks.

Technical Architecture and Workflow

Self-Hosted Server Model

Colanode’s architecture is built around a self-hosted server model, allowing users to deploy the platform independently. The system consists of two primary components:

Client Applications (Web & Desktop)
Server Backend

Users can connect multiple servers from a single client, each containing one or more workspaces—isolated environments for different teams or projects. This modular approach ensures that data remains segmented and secure, preventing cross-contamination between workspaces.

Local-First Workflow

Colanode’s local-first design prioritizes offline functionality, ensuring that users can continue working even when connectivity is unavailable. The platform operates using the following workflow:

Local SQLite Database: All changes are initially saved to a local database before synchronization with the server.
Background Sync Process: A daemon runs in the background, handling real-time synchronization between the local device and the remote server. This ensures that users can edit documents or update databases without losing progress if their connection drops.
Immediate Local Access: Data is read locally by default, providing instant access to content even when offline. Once connectivity resumes, changes are synced automatically.

This approach minimizes latency and ensures a smooth user experience, regardless of network conditions.

Conflict-Free Replicated Data Types (CRDTs)

Colanode employs Conflict-free Replicated Data Types (CRDTs), a cutting-edge synchronization mechanism developed by the Yjs library. CRDTs enable real-time collaboration on shared documents and databases without requiring manual conflict resolution.

When multiple users edit the same page or database record simultaneously, Colanode’s system automatically merges their changes, ensuring consistency across all connected devices. This eliminates issues like lost edits or conflicting updates that often arise in collaborative environments.

For non-collaborative elements such as messages and file operations, Colanode uses simpler database tables to maintain order. These transactions are tracked but do not support concurrent editing, preventing conflicts in less dynamic workflows.

Getting Started with Colanode

Accessing the Web App

The easiest way to begin using Colanode is through its web-based interface, accessible via app.colanode.com. Users can log in immediately without any installation, though it’s important to note that this version is currently in early preview and may contain bugs or compatibility issues. For a more stable experience, the platform recommends installing its desktop application, available on the downloads page.

The web app allows users to connect to one of Colanode’s free beta cloud servers:

Colanode Cloud (EU) – Hosted in Europe.
Colanode Cloud (US) – Hosted in the United States.

Both options are currently available for free testing, though pricing details will be announced in future updates.

Self-Hosting Colanode

For users who prefer full control over their data, Colanode provides self-hosting capabilities. The platform supports deployment via:

Docker Compose (for local development).
Kubernetes Helm Charts (for scalable cloud deployments).

To run Colanode locally, users must follow these steps:

Clone the Repository:

   git clone https://github.com/colanode/colanode.git
   cd colanode

Install Dependencies:

   npm install

Start the Server:

Copy and customize .env.example to create a .env file with required configurations.
Run the server in development mode: bash cd apps/server cp .env.example .env npm run dev

Set Up Supporting Services (Postgres, Redis, etc.): Colanode requires the following dependencies:

PostgreSQL with the pgvector extension for vector search capabilities.
Redis (or a compatible service like Valkey).
A storage backend (default: local filesystem; optional alternatives include S3-compatible, Google Cloud Storage, or Azure Blob Storage).

Users can spin up these services using Docker Compose:

   docker compose -f hosting/docker/docker-compose.yaml up -d

To enable an S3-compatible backend locally (e.g., MinIO), use the s3 profile:

   docker compose -f hosting/docker/docker-compose.yaml --profile s3 up -d

Configure the Server: Colanode’s server configuration is managed via a config.json file, which serves as the single source of truth for all settings. Users can customize this file to adjust database schemas, storage backends, and other parameters.

Example configurations include:

Mounting or binding the config.json file when using Docker Compose.
Enabling Helm-based configuration via environment variables (e.g., --set-file colanode.configFile.data=./config.json).

Running Locally in Development Mode

For quick testing, users can run Colanode’s components separately:

Server:

  cd apps/server
  npm run dev

Web App:

  cd apps/web
  npm run dev

Desktop Application (if available):

  cd apps/desktop
  npm run dev

Testing Colanode

Colanode includes comprehensive test suites for both the server and web components:

Server Tests:

  cd apps/server
  npm run test

These tests use Testcontainers to spin up Postgres and Redis instances, ensuring compatibility with Docker.

Web Tests:

  cd apps/web
  npm run test

Deployment Options

Cloud Servers

For users who prefer not to self-host, Colanode offers free beta cloud servers in:

Europe (EU)
United States (US)

These servers provide a seamless way to access Colanode’s features without the complexity of local deployment. Users can connect via the web or desktop app and start collaborating immediately.

Self-Hosted Deployments

For organizations requiring full control over their data, Colanode supports self-hosting through:

Docker Compose (for local development).
Kubernetes Helm Charts (for cloud-native deployments).

The platform provides detailed documentation for both deployment methods, including required configurations and environment variables.

Required Dependencies

To run Colanode locally or in a production environment, users must ensure the following dependencies are installed:

PostgreSQL with pgvector extension: Enables advanced search and vector-based queries.
Redis (or Redis-compatible service): Used for caching and real-time synchronization.
Storage Backend:

Default: Local filesystem.
Optional alternatives: S3-compatible, Google Cloud Storage, or Azure Blob Storage.

Colanode’s configuration system allows users to switch between storage backends by setting the STORAGE_TYPE environment variable.

Configuration and Customization

Configuring the Server

Colanode’s server configuration is managed through a config.json file, which acts as the primary source of settings. Users can customize this file in three ways:

Editing config.json Directly:

Copy the default template (apps/server/config.json).
Modify fields to suit specific requirements.
Mount or bind the file when using Docker Compose.

Using Helm Charts (Kubernetes):

Enable colanode.configFile.enabled.
Pass the configuration via --set-file colanode.configFile.data=./config.json.

Environment Variables: Colanode supports environment variables for sensitive data, such as database URLs and API keys. These are resolved dynamically at runtime using syntax like env://VAR_NAME or file://path/to/secret.pem.

Required Secrets

While most settings can be configured via config.json, certain sensitive values must be provided through environment variables:

POSTGRES_URL: The connection string for the PostgreSQL database.
REDIS_URL: The connection string for Redis (or a compatible service).

Other optional secrets include:

Database passwords or encryption keys.
API tokens for third-party integrations.

Users should avoid hardcoding sensitive information in config.json and instead rely on environment variables to maintain security.

Running Colanode Locally

Step-by-Step Guide

Clone the Repository:

   git clone https://github.com/colanode/colanode.git
   cd colanode

Install Dependencies:

   npm install

Set Up Environment Variables:

Copy .env.example to .env.
Configure required settings (e.g., database URLs, storage backends).

Start Supporting Services: Use Docker Compose to launch PostgreSQL, Redis, and any additional dependencies:

   docker compose -f hosting/docker/docker-compose.yaml up -d

For an S3-compatible backend (e.g., MinIO), use the s3 profile:

   docker compose -f hosting/docker/docker-compose.yaml --profile s3 up -d

Run the Server:

   cd apps/server
   cp .env.example .env
   npm run dev

This starts the Colanode API in development mode.

Access the Web or Desktop App:

For the web app: bash cd apps/web npm run dev
For the desktop application (if available): bash cd apps/desktop npm run dev

Stopping Services

To stop Colanode locally, users can terminate the running containers using Docker:

docker compose down

Testing and Debugging

Colanode includes automated test suites for both server and web components. Users can execute tests as follows:

Server Tests

cd apps/server
npm run test

These tests use Testcontainers to spin up isolated PostgreSQL and Redis instances, ensuring compatibility with Docker.

Web Tests

cd apps/web
npm run test

For debugging issues during development, Colanode provides detailed error logs and console outputs. Users can also inspect the server’s API endpoints for further troubleshooting.

License and Community Support

Colanode is released under the Apache 2.0 License, ensuring open-source compatibility while providing legal protections for contributors. The project maintains an active community through:

Discord Server: Join the Colanode Discord to engage with developers, ask questions, and share feedback.
Twitter: Follow @colanode for updates and announcements.

The platform encourages contributions from the open-source community, making it easier for users to extend or modify Colanode’s functionality based on their specific needs.

Conclusion: Why Choose Colanode?

Colanode stands out as a revolutionary collaboration workspace that combines the flexibility of modern tools with the privacy and control of self-hosted solutions. Its local-first design ensures that users never rely on third-party servers, reducing risks associated with data breaches or compliance violations.

Key advantages of Colanode include:

Real-time collaboration via CRDTs for seamless multi-user editing.
Customizable databases and file management systems tailored to diverse workflows.
Offline functionality with automatic synchronization when connectivity resumes.
Self-hosting capabilities, allowing users to deploy the platform independently.

Whether used by individuals managing personal projects or teams collaborating across large organizations, Colanode offers a robust alternative to traditional cloud-based collaboration tools. Its open-source nature invites customization and innovation, ensuring that it continues to evolve in response to user needs.

For those prioritizing data privacy, security, and autonomy, Colanode represents a compelling choice—a future-proof platform for collaborative work in the digital age.

Colanode: Open-Source Local-First Collaboration Platform