Colanode Collaboration Workspace on AWS User Guide

Overview

This guide covers the deployment and configuration of Colanode on AWS using cloudimg AWS Marketplace AMIs. Colanode is an open source, local-first collaboration workspace that combines real-time chat channels, collaborative pages and documents, flexible structured databases and file sharing in one place, a self-hosted alternative to tools like Slack and Notion. It is local-first: the desktop and web clients keep a full local copy of your workspaces, so the app stays fast and keeps working offline, then syncs your changes back to the server when you reconnect.

The cloudimg image ships the free and open source, Apache-2.0 licensed Colanode server and web client, run the officially supported way as the upstream containers, alongside PostgreSQL with the pgvector extension and Valkey (a Redis-compatible cache), all captured into the AMI so your instance starts in seconds. Because the upstream project ships with open registration, nothing here ships with a known secret: unique PostgreSQL and Valkey passwords, a per-instance TLS certificate and a per-instance administrator account with a random password are generated for each instance on first boot, before the app is reachable, and public signup is closed by default so a fresh instance is never world-joinable. Backed by 24/7 cloudimg support.

Colanode is a trademark of its respective owner. This image is produced by cloudimg and is not affiliated with, endorsed by, or sponsored by Colanode. It ships the free and open source Apache-2.0 licensed self-hosted software, unmodified.

What is included:

• Colanode server v0.4.7 (the Apache-2.0 licensed Node server and sync engine), pinned by image digest
• Colanode web client v0.4.7 (the Apache-2.0 licensed browser workspace), pinned by image digest
• PostgreSQL 17 with the pgvector extension, and Valkey 8.1, both bound to the internal container network only and never exposed to any host port
• Built-in file storage for uploads on a dedicated data volume, so no external object store is required
• Docker Engine with the server and web client published to the loopback interface only, fronted by nginx on port 443 (with 80 redirecting to 443)
• colanode.service, colanode-firstboot.service, colanode-postboot.service and nginx.service as systemd units, enabled and active on boot
• Unique PostgreSQL and Valkey passwords, a per-instance self-signed TLS certificate and a per-instance administrator account with a random password, all generated per instance on first boot and never baked into the image
• Public signup closed by default (verificationType=manual), no default login and empty datastores on first boot
• A dedicated EBS data volume mounted at /var/lib/docker holding the database, cache, uploads and images, independently resizable and separate from the OS root
• Ubuntu 24.04 LTS base with latest security patches applied at build time
• 24/7 cloudimg support with guaranteed 24 hour response SLA

Prerequisites

• An active AWS account and an EC2 key pair in your target region
• A subscription to the Colanode listing on AWS Marketplace
• A VPC with a public subnet, and a security group as described below

Recommended instance type: m5.large (2 vCPU, 8 GB RAM) is a sensible starting point for a small team. For larger teams or heavier use choose a larger instance. Security group inbound: allow 22/tcp from your management network, and 443/tcp (plus 80/tcp for the automatic redirect to HTTPS) for the web client from the networks that use it.

The web client is a browser application that requires a secure context, so it is served over HTTPS. The image generates a per-instance self-signed certificate, which your browser will warn about on first visit; you click through once, or attach your own domain and a trusted certificate as shown near the end of this guide.

Connecting to your instance

SSH in as the default login user for the AMI variant you launched, using the private key of the EC2 key pair you selected at launch:

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

The first boot generates the per-instance secrets, brings up the stack and seeds your administrator account. This usually completes within a minute or two of the instance first reaching the running state.

Step 1: Launch from the AWS Marketplace

Open the product page in AWS Marketplace, choose Continue to Subscribe, accept the terms, then Continue to Configuration and Continue to Launch. Pick your region, the m5.large instance type, your VPC and public subnet, your key pair, and a security group that allows inbound 22, 80 and 443 as above. Launch the instance.

Step 2: Launch from the AWS CLI

aws ec2 run-instances \
  --image-id <ami-id-from-the-listing> \
  --instance-type m5.large \
  --key-name your-key \
  --security-group-ids sg-xxxxxxxx \
  --subnet-id subnet-xxxxxxxx \
  --associate-public-ip-address \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=colanode-01}]'

Step 3: Confirm the services are running

All five systemd units should be active, the four containers should be up, and only 80/443 should be public while the server and web client bind to loopback and PostgreSQL and Valkey are on no host port at all:

systemctl is-active docker colanode-firstboot colanode colanode-postboot nginx
sudo docker ps --format '{{.Names}}\t{{.Status}}'
sudo ss -tlnH | awk '{print $4}' | grep -E ':(80|443|3000|4000|5432|6379)$' | sort -u

Expected output:

active
active
active
active
active
colanode-web-1  Up 9 minutes
colanode-server-1   Up 9 minutes
colanode-postgres-1 Up 9 minutes (healthy)
colanode-valkey-1   Up 9 minutes (healthy)
0.0.0.0:443
0.0.0.0:80
127.0.0.1:3000
127.0.0.1:4000

Note there are no listeners on 5432 or 6379: PostgreSQL and Valkey are reachable only on the private container network, never from the host or the internet.

Step 4: Confirm the workspace answers over HTTPS

Both the web client and the server answer through nginx on port 443 (self-signed, so -k here skips the certificate check locally):

curl -ks -o /dev/null -w 'web /       -> %{http_code}\n' https://127.0.0.1/
curl -ks -o /dev/null -w 'server /config -> %{http_code}\n' https://127.0.0.1/config

Expected output:

web /       -> 200
server /config -> 200

Step 5: Read the per-instance credentials

Your administrator account and its random password are written to a root-only file on first boot:

sudo cat /root/colanode-credentials.txt

Expected output (the password value is unique to your instance):

WEB_URL=https://<instance-public-ip>/
SERVER_URL=https://<instance-public-ip>
ADMIN_EMAIL=admin@colanode.local
ADMIN_PASSWORD=********
WORKSPACE=General

Keep this file secret. There is no default or shared login anywhere in the image; the account above is the only bootstrap account and its password is unique to this instance.

Step 6: Open the web client and add your server

Open https://<instance-public-ip>/ in a desktop browser. Because the certificate is self-signed, your browser shows a one-time warning; click through (Proceed). The client opens on the Add a server screen.

Choose Add a new server and enter your server's config URL exactly:

https://<instance-public-ip>/config

Click Create. The server is added and you are taken to the sign-in screen.

Step 7: Sign in with your administrator account

Enter the ADMIN_EMAIL and ADMIN_PASSWORD from the credentials file and choose Login.

Step 8: Explore your workspace

After signing in you land in your workspace, with the Spaces sidebar showing your Home space, pages and channels.

Open the Welcome page to see Colanode's rich, block-based editor - headings, checklists, callouts and structured content, the self-hosted Notion-style document experience. Type / anywhere to insert new content, and add subpages, subfolders or databases from the same menu.

Open the Discussions channel to chat in real time alongside your pages and databases. Everything - chat, docs and structured data - lives in the same workspace on infrastructure you control.

Step 9: Add teammates

Public signup is closed by default (account.verificationType=manual), so a fresh instance is never world-joinable. You have two options for adding people:

• Open self-registration. Edit /etc/colanode/config.json and set "account": { "verificationType": "automatic" }, then restart the app:

bash sudo systemctl restart colanode

• Keep signup closed and activate individuals. Have each person register in the app, then activate their account:

bash sudo docker compose --env-file /etc/colanode/colanode.env -f /etc/colanode/compose.yaml \ exec -T postgres psql -U colanode_user -d colanode_db \ -c "UPDATE accounts SET status=1 WHERE email='<their-email>';"

Step 10: Attach a real domain and a trusted certificate

The image ships with a self-signed certificate so the client works immediately on the instance's own address. For a warning-free certificate, point a DNS record at the instance, then either:

• Terminate TLS on an AWS Application Load Balancer with an ACM certificate for your domain, forwarding to the instance on 443 (or 80), and set your domain as web.domain and cors.origin in /etc/colanode/config.json; or
• Install your own certificate into /etc/nginx/ssl/colanode.crt and /etc/nginx/ssl/colanode.key (for example via Let's Encrypt / certbot), update web.domain and cors.origin in /etc/colanode/config.json to your domain, then run sudo systemctl restart colanode nginx.

For data at rest, enable EBS encryption on the dedicated data volume mounted at /var/lib/docker.

Security model

• No baked credentials. Unique PostgreSQL and Valkey passwords, a per-instance TLS certificate and a per-instance administrator password are generated on first boot and never shipped in the image. The captured image contains empty datastores.
• Not world-joinable. Public signup is closed by default; new registrations stay inert until an administrator activates them.
• Least exposure. The server and web client bind to loopback and are reachable only through nginx; PostgreSQL and Valkey are on the internal container network with no host port. Only 80 and 443 are public, and 80 redirects to 443.
• Data ownership. Workspaces, messages, documents and uploads all live on your instance and its dedicated data volume, never on a third-party service.

Support

This image is backed by 24/7 cloudimg support with a guaranteed 24 hour response SLA. For help with deployment, configuration or scaling, contact cloudimg support.