AppFlowy on Ubuntu 24.04 on Azure User Guide

Overview

This image runs AppFlowy, the open source alternative to Notion for notes, documents, wikis, tasks and lightweight project boards, on Ubuntu 24.04 LTS. It ships the fully self-hosted AppFlowy-Cloud backend together with the AppFlowy web application, so your whole workspace - every page, database and uploaded file - lives inside your own Azure subscription rather than a hosted service.

AppFlowy self-hosts as a small set of services, orchestrated by Docker Compose and managed by systemd:

• appflowy_web - the Notion-like web application (served at /)
• appflowy_cloud - the Rust API and realtime collaboration server (/api, /ws)
• appflowy_worker - a background worker for imports and housekeeping
• gotrue - the authentication service (email/password sign-up and sign-in, at /gotrue)
• admin_frontend - an administration console for managing users (at /console)
• postgres (PostgreSQL 16 with pgvector) - the workspace, document and user catalogue
• redis - collaboration state and cache
• minio - an S3-compatible object store for uploaded files and attachments

nginx on port 80 fronts everything on a single origin: it serves the web app at /, proxies the API at /api, the auth service at /gotrue, the admin console at /console, the object store at /minio-api, and answers an unauthenticated /healthz for load-balancer probes. Because every service is reached through nginx on the one public address, there is only one port (80) to open.

What is included:

• The full AppFlowy-Cloud self-host stack (web, cloud, worker, gotrue, admin console, PostgreSQL, Redis, MinIO) run under Docker Compose via an appflowy.service systemd unit, from images pinned by digest
• The web app, API, auth service, admin console and object store all on port 80 behind nginx, same-origin (no CORS, no extra ports)
• Every secret generated fresh per-VM on first boot - the PostgreSQL password, the GoTrue JWT signing secret, the admin console password, and the MinIO access and secret keys - so no upstream default (hello456, password, minioadmin) survives into the image
• The workspace, document and file store on a dedicated Azure data disk at /var/lib/appflowy, captured into the image
• An unauthenticated /healthz endpoint for Azure Load Balancer health probes
• Unattended security upgrades enabled on the base OS

Free self-hosted tier: seat limit

The self-hosted AppFlowy free tier allows one Member/Owner user plus up to three guests per server. This is an AppFlowy licensing characteristic, not a cloudimg limitation: the first account you create becomes the workspace owner, and additional full members require an AppFlowy subscription/licence. The appliance is ideal for a personal or single-owner knowledge base out of the box, and you can invite guests to collaborate. To run a larger team, apply an AppFlowy licence after deployment.

Prerequisites

• An Azure subscription and the Azure CLI (az) signed in, or access to the Azure Portal
• An SSH key pair for the admin (azureuser) account
• A Network Security Group that allows inbound TCP 22 (SSH, your admin IP only) and TCP 80 (the web app)
• The recommended size is Standard_D2s_v3 (2 vCPU / 8 GB). The stack runs comfortably there; smaller sizes are not recommended for the full multi-service stack.

Step 1 - Launch the VM

Option A - Azure Portal

1. From the cloudimg AppFlowy on Ubuntu 24.04 LTS offer, choose Create.
2. Pick your resource group and region, and set the VM size to Standard_D2s_v3.
3. Set the admin username to azureuser and upload your SSH public key.
4. Under Networking, allow inbound SSH (22) from your admin IP and HTTP (80) from the clients that need the web app.
5. Review and create.

Option B - Azure CLI

az vm create \
  --resource-group <your-resource-group> \
  --name appflowy \
  --image <cloudimg-appflowy-image-urn> \
  --size Standard_D2s_v3 \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

Open port 80 to the clients that need the web app (SSH is opened for your admin IP separately):

az network nsg rule create \
  --resource-group <your-resource-group> \
  --nsg-name <your-nsg> \
  --name allow-http --priority 1001 \
  --destination-port-ranges 80 --access Allow --protocol Tcp

Step 2 - First boot and the per-VM credentials

On the first boot, appflowy-firstboot.service generates a fresh set of secrets unique to this VM, sets the public address, brings the stack up, and writes the secrets to a root-only file. Give it a minute or two on the first boot, then SSH in:

ssh azureuser@<vm-ip>

Read your per-VM credentials (the secret values are unique to your VM; they are masked below):

sudo cat /root/appflowy-credentials.txt

The file records the URLs, the admin console login (admin@appflowy.local plus a per-VM password), and the MinIO object-store keys. Store them somewhere safe.

Step 3 - Verify the stack

Confirm all nine services are running:

sudo docker compose -f /opt/appflowy/docker-compose.yml ps

Step 4 - Health check

Check the web app, the API and the auth service through nginx. The API correctly returns 401 when called without a token, which confirms authentication is enforced:

curl -s -o /dev/null -w "healthz:        %{http_code}\n" http://127.0.0.1/healthz
curl -s -o /dev/null -w "gotrue health:  %{http_code}\n" http://127.0.0.1/gotrue/health
curl -s -o /dev/null -w "api (no token): %{http_code}\n" http://127.0.0.1/api/workspace

Step 5 - Create your account

Open http://<vm-ip>/ in your browser. AppFlowy greets you with a welcome page; choose Sign up here to create your account with an email and a password.

Sign-ups are auto-confirmed on this appliance (no email server is configured by default), so you can sign in immediately after creating your account. Remember the free-tier seat limit: the first account becomes the workspace owner.

Step 6 - Your workspace

After signing in you land in your workspace, with the sidebar on the left and a Getting started document already open. From here you organise pages into spaces, share them, and collaborate.

Step 7 - Create and edit a document

Click New page, choose a space, and start writing. AppFlowy's block editor supports rich text, headings, checklists, tables and more - type / to insert a block.

The admin console

The admin console at http://<vm-ip>/console lets an operator manage the users on the server. Log in with the APPFLOWY_ADMIN_EMAIL (admin@appflowy.local) and APPFLOWY_ADMIN_PASSWORD from your credentials file.

Optional - enable email (SMTP)

By default no email server is configured, so sign-ups are auto-confirmed and password-reset / invitation emails are not sent. To enable email, add your SMTP settings to /opt/appflowy/.env (GOTRUE_SMTP_HOST, GOTRUE_SMTP_PORT, GOTRUE_SMTP_USER, GOTRUE_SMTP_PASS, GOTRUE_SMTP_ADMIN_EMAIL), set GOTRUE_MAILER_AUTOCONFIRM=false, and recreate the stack:

cd /opt/appflowy && sudo docker compose up -d

Optional - enable AI features

AppFlowy's AI writing and chat features are off by default. To enable them, provide an OpenAI API key and add the ai service. Set AI_OPENAI_API_KEY in /opt/appflowy/.env and follow the upstream AppFlowy-Cloud AI documentation, then recreate the stack.

Data and backups

The PostgreSQL catalogue and the MinIO object store live in Docker volumes on the dedicated data disk at /var/lib/appflowy, which is captured into the image and re-provisioned on every VM. To back up, snapshot the data disk from Azure, or use docker compose to dump the postgres database and mirror the minio bucket. Assign a static public IP so the object-store and auth URLs remain stable.

Troubleshooting

• The web app does not load. Confirm port 80 is open in your NSG and that sudo docker compose -f /opt/appflowy/docker-compose.yml ps shows all services up. Check curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1/healthz returns 200.
• "Seat limit reached" on sign-up. The free self-hosted tier allows one Member/Owner. Sign in as the existing owner, invite guests, or apply an AppFlowy licence for more members.
• Sign-in issues after changing the address. The public address is baked in at first boot. If you change the VM's public IP, edit FQDN in /opt/appflowy/.env to the new address and run cd /opt/appflowy && sudo docker compose up -d.
• Inspect logs. cd /opt/appflowy && sudo docker compose logs --tail 100 appflowy_cloud gotrue.

Support

This image is maintained by cloudimg and backed by 24/7 support. For help with deployment or configuration, contact the cloudimg team via the Azure Marketplace listing.