Colanode on Ubuntu 24.04 on Azure User Guide

Overview

This guide covers the deployment and configuration of Colanode on Ubuntu 24.04 on Azure using cloudimg Azure Marketplace images. Colanode is an open source, local first collaboration workspace that combines real time chat channels, collaborative pages and documents, flexible 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 VM 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 VM 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 persistent 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 VM 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
• Ubuntu 24.04 LTS base with latest security patches applied at build time
• Azure Linux Agent for seamless cloud integration and SSH key injection
• 24/7 cloudimg support with guaranteed 24 hour response SLA

Prerequisites

• Active Azure subscription, SSH public key, VNet + subnet in target region
• Subscription to the Colanode listing on Azure Marketplace

Recommended virtual machine size: Standard_B2s (2 vCPU, 4 GB RAM) is a sensible starting point for a small team. For larger teams or heavier use choose Standard_D2s_v5 or larger. NSG inbound: allow 22/tcp from your management network, and 443/tcp (and 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 in Step 15.

Step 1: Deploy from the Azure Portal

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Colanode by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTPS (443). Then Review + create and Create.

Step 2: Deploy from the Azure CLI

RG="colanode-prod"; LOCATION="eastus"; VM_NAME="colanode-01"
GALLERY_IMAGE_ID="/subscriptions/<sub-id>/resourceGroups/azure-cloudimg/providers/Microsoft.Compute/galleries/cloudimgGallery/images/colanode-ubuntu-24-04/versions/<version>"
SSH_KEY="$(cat ~/.ssh/id_rsa.pub)"
az group create --name "$RG" --location "$LOCATION"
az network vnet create -g "$RG" --name cola-vnet --address-prefix 10.100.0.0/16 --subnet-name cola-subnet --subnet-prefix 10.100.1.0/24
az network nsg create -g "$RG" --name cola-nsg
az network nsg rule create -g "$RG" --nsg-name cola-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp
az network nsg rule create -g "$RG" --nsg-name cola-nsg --name allow-https --priority 110 \
  --destination-port-ranges 443 --access Allow --protocol Tcp
az network nsg rule create -g "$RG" --nsg-name cola-nsg --name allow-http-redirect --priority 120 \
  --destination-port-ranges 80 --access Allow --protocol Tcp
az vm create -g "$RG" --name "$VM_NAME" --image "$GALLERY_IMAGE_ID" \
  --size Standard_B2s --storage-sku StandardSSD_LRS \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name cola-vnet --subnet cola-subnet --nsg cola-nsg --public-ip-sku Standard

Step 3: Connect to your VM

ssh azureuser@<vm-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 VM first reaching the running state.

Step 4: Confirm the services are running

All four 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 -tlnp | grep -E ':443 |:80 |:3000 |:4000 |:5432 |:6379 '

Expected output:

active
active
active
active
active
colanode-web-1        Up (healthy)
colanode-server-1     Up
colanode-postgres-1   Up (healthy)
colanode-valkey-1     Up (healthy)
LISTEN 0 511   0.0.0.0:80    0.0.0.0:*
LISTEN 0 511   0.0.0.0:443   0.0.0.0:*
LISTEN 0 4096  127.0.0.1:3000 0.0.0.0:*
LISTEN 0 4096  127.0.0.1:4000 0.0.0.0:*

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 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 VM):

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

Step 6: Verify the security model

Public signup is closed by default (verificationType=manual), so a fresh instance is not world joinable. The API rejects an unauthenticated request to create a workspace, and the seeded per instance account authenticates end to end:

grep verificationType /etc/colanode/config.json
curl -ks -o /dev/null -w 'unauthenticated POST -> HTTP %{http_code}\n' \
  -X POST -H 'Content-Type: application/json' -d '{"name":"x"}' \
  https://127.0.0.1/client/v1/workspaces
sudo /usr/local/sbin/colanode-roundtrip.sh

Expected output:

  "account": { "verificationType": "manual", "otpTimeout": 600 },
unauthenticated POST -> HTTP 401
OK round-trip: web=https://<vm-ip>/ server=https://<vm-ip> admin=admin@colanode.local (per-VM account gates the API; unauth/wrong-token create rejected 401/403; workspace create+readback 200; web UI + server /config live)

Step 7: Open the web client and add your server

In a desktop browser, open your instance:

https://<vm-ip>/

Because the certificate is self signed, your browser shows a one time warning; choose Advanced then Proceed (or attach your own domain and certificate, Step 15). Colanode opens on the Add a server screen. Click Add a new server and enter your server's config URL exactly:

https://<vm-ip>/config

Then click Create.

Step 8: Sign in

Select the server you just added, then sign in with the seeded administrator account from Step 5 (admin@colanode.local and the random ADMIN_PASSWORD). New self registrations are held inactive by default, so use this seeded account first; Step 11 shows how to open signup or activate additional users.

Step 9: Write pages and documents

Inside your workspace, the left rail lists your spaces; each space holds pages, channels and databases. Open the Welcome page to see the block editor: click anywhere and start typing, or press / to insert headings, to dos, blockquotes, subpages and databases. Everything you write syncs to your server and to any other device signed in to the same account.

Step 10: Chat in a channel

Open the Discussions channel to chat with your team in real time. Type a message in the composer at the bottom and press Enter; messages appear instantly and sync to every member of the workspace.

Step 11: Manage signup and users

By default, account.verificationType is manual, so anyone can submit the registration form but new accounts stay inactive until you approve them. You have three options:

Open self signup (anyone can register and use the server immediately) by editing the server config and restarting:

sudo sed -i 's/"verificationType": "manual"/"verificationType": "automatic"/' /etc/colanode/config.json
sudo systemctl restart colanode

Activate a specific user who has registered, keeping signup otherwise closed:

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>';"

Require email verification instead, by setting verificationType to email and configuring SMTP under the email block of /etc/colanode/config.json (set email.enabled to true), then restarting the service.

Step 12: Explore the server API

The server exposes a public configuration endpoint and a client API under /client/v1. Confirm the server, its version and file storage:

curl -ks https://127.0.0.1/config | jq -c '{name,version,sha}'
grep -o '"provider": {[^}]*}' /etc/colanode/config.json

Expected output:

{"name":"Colanode","version":"0.4.7","sha":"d649523637f0f059c936418488165d4a689da27c"}
"provider": { "type": "file", "path": "/var/lib/colanode/storage", "directory": "/var/lib/colanode/storage" }

Step 13: Server components

• Colanode server (ghcr.io/colanode/server) - the Node API and sync engine, published to 127.0.0.1:3000 and reached through nginx at /config and /client/
• Colanode web client (ghcr.io/colanode/web) - the static browser workspace, published to 127.0.0.1:4000 and served at /
• PostgreSQL 17 with pgvector (pgvector/pgvector:pg17) - the primary datastore, on the internal container network only
• Valkey 8.1 (valkey/valkey:8.1) - the Redis compatible cache and sync channel, on the internal container network only
• nginx - the host reverse proxy, terminating TLS on 443 and redirecting 80 to 443
• Configuration lives in /etc/colanode/config.json and per VM secrets in /etc/colanode/colanode.env; uploads persist in the server_storage volume

Step 14: Managing the service

sudo systemctl restart colanode
sudo docker compose --env-file /etc/colanode/colanode.env -f /etc/colanode/compose.yaml ps
sudo docker compose --env-file /etc/colanode/colanode.env -f /etc/colanode/compose.yaml logs --tail 50 server

Step 15: Use your own domain and HTTPS (production)

The image ships a per instance self signed certificate so the browser client works out of the box. For a warning free certificate, point a DNS name at the VM, then replace the certificate. The simplest path is Certbot with the nginx plugin:

sudo snap install --classic certbot
sudo ln -sf /snap/bin/certbot /usr/bin/certbot
sudo certbot --nginx -d <your-domain> -m <your-email> --agree-tos --redirect

After issuing the certificate, edit /etc/colanode/config.json and set web.domain to your domain and cors.origin to https://<your-domain>, then run sudo systemctl restart colanode. When you add the server in the web client, enter https://<your-domain>/config.

Step 16: Security recommendations

• Restrict 22/tcp to your management network in the NSG; expose 443/tcp only to the networks that need the workspace
• Keep public signup closed (verificationType=manual) unless you intend an open server; activate users deliberately
• Replace the self signed certificate with a trusted one for production (Step 15)
• Keep the per instance credentials file (/root/colanode-credentials.txt) private and rotate the administrator password after first sign in
• Apply operating system updates regularly with sudo apt update && sudo apt upgrade

Step 17: Support and Licensing

Colanode is free and open source software distributed under the Apache-2.0 license. This image bundles the unmodified upstream server and web client with PostgreSQL, pgvector and Valkey, configured securely for Azure. cloudimg provides 24/7 support with a guaranteed 24 hour response SLA for image and deployment issues. For questions about Colanode features, consult the upstream project documentation.

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.

Deploy on Azure

Search the Azure Marketplace for Colanode on Ubuntu 24.04 LTS by cloudimg to deploy this image.