Frappe Wiki on Ubuntu 24.04 on Azure User Guide

Overview

Frappe Wiki is an open-source wiki and knowledge-base application built on the Frappe framework. It is well suited to dynamic, text-heavy content such as product documentation, internal handbooks, runbooks and company policies. Authors get a rich block editor, a drag-and-drop page tree, wiki spaces, full revision history and a change-request approval workflow; readers get a fast published site with full-text search. The cloudimg image installs Wiki v3.0.0 on Frappe framework version-16 as a full production deployment - MariaDB, Redis, a Python gunicorn web tier plus a node realtime process, background workers and a scheduler managed by supervisor, and nginx on port 80 - runs the entire headless install at build time so there is no command-line bootstrap on first use, and rotates the Frappe Administrator password, the site database password and the Frappe encryption key on the first boot of every VM. Backed by 24/7 cloudimg support.

What is included:

• Frappe Wiki v3.0.0 on Frappe framework version-16, served on port 80 by nginx in front of a gunicorn web worker
• Python 3.14 and Node.js 24, which Frappe version-16 and Wiki v3 both require
• MariaDB on loopback (Barracuda / utf8mb4 / large packets per Frappe), tuned for a small VM
• Redis for cache, queue and socketio; supervisor managing the Frappe web, worker, schedule and socketio processes
• A unique Administrator password, site database password and Frappe encryption key generated on first boot, with no default login
• nginx.service, supervisor.service, mariadb.service and redis-server.service as systemd units, enabled and active
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is the supported minimum; choose a larger size such as Standard_B2ms or Standard_D2s_v3 for larger teams or heavier editing traffic. NSG inbound: allow 22/tcp from your management network and 80/tcp for the wiki web interface (front with TLS for public exposure - see Enabling HTTPS).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Frappe Wiki 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 HTTP (80). Then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name frappe-wiki \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name frappe-wiki --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the wiki stack is running

On first boot the image rotates the Frappe encryption key, the site database password and the Administrator password, points the site at this VM's public IP, and starts the production stack. Confirm all four systemd services are active:

systemctl is-active mariadb redis-server supervisor nginx

All four services report active, and supervisor runs the Frappe web, socketio, worker and schedule processes.

Confirm the Frappe web tier answers its health endpoint:

curl -s http://127.0.0.1/api/method/ping

Frappe returns {"message":"pong"}. The wiki editor app is served at /wiki-app:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/wiki-app

That returns 200 - the application shell loads for anyone, and the wiki then requires a sign-in before it will show you any content. You can see the exact installed apps and versions, and confirm MariaDB and Redis are bound to loopback only:

sudo -u frappe -H bash -lc 'cd /opt/frappe/frappe-bench && bench --site wiki.localhost list-apps'

Step 5 - Retrieve the Administrator password

The per-VM Administrator password is generated on first boot and written to a root-only credentials file, along with the wiki URLs and login name:

sudo cat /root/frappe-wiki-credentials.txt

Because these secrets are generated on first boot, no two deployments share the same password, and the vendor default login is rejected:

You can prove that round-trip yourself - the per-VM password authenticates and common defaults do not:

PASS=$(sudo grep '^wiki.admin.pass=' /root/frappe-wiki-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'per-VM password: %{http_code}\n' http://127.0.0.1/api/method/login \
  --data-urlencode 'usr=Administrator' --data-urlencode "pwd=$PASS"
curl -s -o /dev/null -w 'default "admin":  %{http_code}\n' http://127.0.0.1/api/method/login \
  --data-urlencode 'usr=Administrator' --data-urlencode 'pwd=admin'

The per-VM password returns 200 and the default returns 401.

Step 6 - Sign in to Frappe Wiki

Browse to http://<vm-public-ip>/wiki-app and sign in as Administrator with the password from Step 5.

After signing in, the wiki app lists your wiki spaces. A space is a self-contained documentation site with its own route, page tree and permissions; the image ships one space named Wiki published at the route docs. Use New Space to add more - for example one space for public product documentation and another for an internal handbook.

Step 7 - Write and publish pages

Open a space to get the authoring view: the page tree on the left, the block editor in the middle, and the page's route and publish state at the top. The toolbar gives you headings, bold and italic, inline and block code, bullet, numbered and task lists, quotes, dividers, tables, links, images and video embeds. Drag pages in the tree to re-order or nest them. Every save is versioned, and Save publishes your change to the reader site.

Readers see the published page at the space route, with the page tree, a full-text search box and an automatic "On this page" table of contents:

Every page is also available as plain markdown, which is useful for scripts and AI agents. Because the space is private, sign in first and reuse that session:

PASS=$(sudo grep '^wiki.admin.pass=' /root/frappe-wiki-credentials.txt | cut -d= -f2-)
J=$(mktemp)
curl -s -o /dev/null -c "$J" http://127.0.0.1/api/method/login \
  --data-urlencode 'usr=Administrator' --data-urlencode "pwd=$PASS"
curl -s -b "$J" -H 'Accept: text/markdown' http://127.0.0.1/docs/welcome-to-frappe-wiki | head -5
rm -f "$J"

The response starts with a small metadata block giving the page title, its space, its public URL and the date it was last updated.

Step 8 - Choose who can read your wiki

Frappe Wiki ships private by default: a wiki space is readable only by signed-in users with access to that space, so an anonymous visitor gets a 404 instead of your content. That is the right default for an internal knowledge base, and you can confirm it:

curl -s -o /dev/null -w 'anonymous: %{http_code}\n' http://127.0.0.1/docs/welcome-to-frappe-wiki

To publish a space to the public internet instead, open the space in the wiki app, go to its settings (the gear icon in the space header), and add the Guest role to the space's role list. Anonymous visitors can then read every published page in that space, while editing still requires a sign-in. Grant access to named teams the same way, by adding the roles that should be able to read or contribute.

Add editors as normal Frappe users - in the desk at http://<vm-public-ip>/app/user, create the user, then give them the roles your space requires.

Step 9 - Enabling HTTPS

For anything reachable from the internet, terminate TLS in front of the wiki. With a DNS record already pointing at the VM:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d wiki.your-domain.com --agree-tos -m you@your-domain.com --redirect

Then tell Frappe its public URL so generated links are correct:

sudo -u frappe -H bash -lc 'cd /opt/frappe/frappe-bench && bench --site wiki.localhost set-config host_name https://wiki.your-domain.com'
sudo systemctl restart supervisor

Certbot installs a systemd timer that renews the certificate automatically.

Step 10 - Maintenance

Check the wiki's own processes and logs:

sudo supervisorctl status

Back up the site - this writes a database dump plus the public and private files into the site's private/backups directory:

sudo -u frappe -H bash -lc 'cd /opt/frappe/frappe-bench && bench --site wiki.localhost backup'

Keep the operating system patched. The image ships with unattended-upgrades enabled, and you can apply everything pending at any time:

sudo apt-get update && sudo apt-get -y dist-upgrade

Troubleshooting

A page returns 401 when you are not signed in. That is the shipped default - wiki spaces are private. Add the Guest role to the space (Step 8) to make it publicly readable.

The wiki does not respond after a reboot. Confirm the four services are up with systemctl is-active mariadb redis-server supervisor nginx, then check the Frappe processes with sudo supervisorctl status. sudo systemctl restart supervisor restarts the web, worker, scheduler and socketio processes.

Links point at the wrong host. The first boot writes the VM's public IP into the site's host_name. If you later put the wiki behind a DNS name or a load balancer, update it as shown in Step 9 and restart supervisor.

You need the Administrator password again. It is only ever written to /root/frappe-wiki-credentials.txt on that VM. If it has been changed and lost, reset it with sudo -u frappe -H bash -lc 'cd /opt/frappe/frappe-bench && bench --site wiki.localhost set-admin-password <new-password>'.

Support

cloudimg provides 24/7 technical support for this image by email (support@cloudimg.co.uk) and live chat, covering deployment, wiki space and permission configuration, upgrades, performance tuning and MariaDB administration.

Frappe and Frappe Wiki are trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.