Foswiki 2.1 on Ubuntu 24.04 on Azure User Guide

Overview

Foswiki is an open-source structured wiki: a collaboration platform where every page is a topic written in wiki markup, kept in a full revision history, and extendable with forms, queries and macros. It is used for engineering documentation, knowledge bases, requirement registers and internal intranets.

The cloudimg image installs Foswiki 2.1.11 (GPL-2.0-or-later) from the upstream release tarball, runs it as a persistent FastCGI daemon behind nginx, stores every topic and attachment on a dedicated Azure data disk, and generates a unique administrator account on the first boot of every VM. There is no installation wizard to work through and no shared password anywhere in the image. Backed by 24/7 cloudimg support.

What is included:

• Foswiki 2.1.11 in /opt/foswiki, running on the distribution Perl 5.38 from Ubuntu's own archive
• The Foswiki FastCGI daemon (bin/foswiki.fcgi, from the distribution's FastCGIEngineContrib) as foswiki.service, bound to loopback 127.0.0.1:9000
• nginx on :80 as the single public listener, proxying /bin/ to the FastCGI daemon and serving /pub/ attachments directly
• Foswiki's native flat-file store (Foswiki::Store::PlainFile) - no external database to run or patch
• A dedicated Azure data disk at /var/lib/foswiki holding every topic, its revision history, all attachments, sessions and logs
• A per-VM wiki administrator and a separate per-VM credential guarding the configure console, both generated on first boot into a root-only file
• 24/7 cloudimg support

Secure by default. Foswiki's stock configuration is not appropriate for an internet-facing appliance, so this image closes it:

• The administrative configure console is protected twice - by an nginx HTTP Basic credential unique to your VM, and behind that by Foswiki's own admin-only restriction. An unauthenticated request never reaches the Perl.
• LocalSite.cfg is written in full at build time. Foswiki only falls back to its unauthenticated configure bootstrap console when that file is missing, so its presence is itself a security control.
• Self-registration is disabled, so the first visitor cannot create themselves an account.
• The shared "internal admin" password is left empty, which disables that shared login entirely.
• Passwords are hashed with bcrypt rather than the upstream apache-md5 default.
• Anonymous visitors can read the wiki but cannot create, edit, attach to, or rename anything.

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is the recommended starting size. NSG inbound: allow 22/tcp from your management network and 80/tcp from wherever your readers are. Foswiki serves plain HTTP on port 80; for production put your own TLS termination in front of it (see Step 11).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Foswiki 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). Review the dedicated data disk on the Disks tab, then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name foswiki \
  --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 foswiki --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services and the data disk

Three units make up the appliance. foswiki-firstboot.service runs once, on the very first boot, to generate this VM's credentials. foswiki.service is the FastCGI daemon that runs the wiki, bound to loopback only. nginx.service is the single public listener on port 80.

systemctl is-active foswiki-firstboot.service foswiki.service nginx.service
ss -tln | awk 'NR==1 || /:80 |:9000 /{print $1, $4}'
findmnt -no SOURCE,TARGET,FSTYPE,SIZE /var/lib/foswiki

Expected output - all three units active, port 80 open to the world, port 9000 bound to 127.0.0.1 only, and the data disk mounted:

active
active
active
State  Local
LISTEN 0.0.0.0:80
LISTEN 127.0.0.1:9000
/dev/sdc /var/lib/foswiki ext4 31.2G

Step 5 - Retrieve your administrator password

Every VM generates its own wiki administrator password and its own configure console credential on first boot, and writes them to a root-only file. No password is baked into the image.

sudo cat /root/foswiki-credentials.txt

Expected output - your own values will differ:

FOSWIKI_URL=http://<vm-public-ip>/bin/view/Main/WebHome
FOSWIKI_ADMIN_USER=WikiAdmin
FOSWIKI_ADMIN_PASSWORD=<a 24-character password unique to this VM>

FOSWIKI_CONFIGURE_URL=http://<vm-public-ip>/bin/configure
FOSWIKI_CONFIGURE_USER=configure
FOSWIKI_CONFIGURE_PASSWORD=<a 24-character password unique to this VM>

Confirm the file is readable only by root, and that exactly one account exists in the wiki:

stat -c '%n mode=%a owner=%U:%G' /root/foswiki-credentials.txt
sudo grep -c ':' /var/lib/foswiki/data/.htpasswd

Step 6 - Sign in to the wiki

Browse to http://<vm-public-ip>/. You will be redirected to the wiki home page, which anyone can read. Choose Log In (or go straight to http://<vm-public-ip>/bin/logon/Main/WebHome) and sign in with FOSWIKI_ADMIN_USER and FOSWIKI_ADMIN_PASSWORD from Step 5.

Once signed in, the left-hand sidebar shows your name and the toolbox, and the wiki's webs (Main, Sandbox, System, Trash) are listed underneath.

The Create account link on the sign-in page is part of Foswiki's stock template. Because self-registration is disabled in this image, following it shows "New user registration is disabled on this site." Step 9 covers adding users deliberately.

Step 7 - Create and edit a topic

Everything in Foswiki is a topic. Navigate to a web (start with Sandbox while you are experimenting), choose Create New Topic, give it a WikiWord name such as CloudimgWelcome, and write wiki markup in the editor.

---+ Welcome to your Foswiki

   * Foswiki stores every topic as a plain file, with full revision history
   * No external database is required

*Bold text*, _italic text_ and =monospaced text= all render from wiki markup.

| *Setting* | *Value* |
| Store | PlainFile |
| Web server | nginx to FastCGI |

Choose Save. Foswiki renders the markup: ---+ becomes a heading, the indented * lines become a bulleted list, *bold* becomes bold, and the pipe-delimited rows become a real table.

Step 8 - Revision history

Every save is kept. Edit the topic again, tick Force new revision if you want a separate entry rather than an amendment to your own recent save, and save. The footer then shows r2, and History compares any two revisions.

On disk, Foswiki keeps the current topic next to a per-topic history directory, both on the data disk:

ls /var/lib/foswiki/data/Sandbox/ | head -20

You can also verify the whole wiki end to end at any time. The image ships a self-test that signs in with this VM's administrator password, creates a topic, checks the markup rendered, saves a second revision, checks the history, and confirms the security posture. It cleans up after itself.

sudo /usr/local/sbin/foswiki-selftest.sh

Expected output:

SELFTEST_OK

Step 9 - Add more users

Self-registration is disabled so that a public VM cannot be joined by anyone who finds it. Add people deliberately instead.

Create the account's password with the helper the image ships, which writes the hash in the encoding Foswiki is configured for:

sudo /usr/local/sbin/foswiki-set-password.pl JaneSmith '<a strong password>' jane@example.com

Then, signed in as the administrator, create the matching user topic Main.JaneSmith in the browser so the name resolves and the person can be mentioned and granted access. To make somebody an administrator, edit Main.AdminGroup and add their WikiName to the GROUP setting.

If you would rather turn self-registration back on for a private network, set {Register}{EnableNewUserRegistration} in the configure console (Step 10) and restart the wiki.

Step 10 - The configure console

configure is Foswiki's administrative settings console. It can install extensions and change how the server runs, so this image puts two independent gates in front of it.

Confirm the first gate from the VM - an unauthenticated request is refused by nginx before it reaches Foswiki:

curl -s -o /dev/null -w 'no credential  -> HTTP %{http_code}\n' -m 15 http://127.0.0.1/bin/configure
curl -s -o /dev/null -w 'wrong password -> HTTP %{http_code}\n' -m 15 -u configure:wrong-password http://127.0.0.1/bin/configure

Expected output:

no credential  -> HTTP 401
wrong password -> HTTP 401

To use the console, browse to http://<vm-public-ip>/bin/configure. Your browser will prompt for the HTTP Basic credential first - use FOSWIKI_CONFIGURE_USER and FOSWIKI_CONFIGURE_PASSWORD from Step 5 - and Foswiki then requires you to be signed in as the wiki administrator behind it. Restart the wiki after saving changes:

sudo systemctl restart foswiki.service

To change the console credential later:

sudo htpasswd -B /etc/nginx/foswiki-configure.htpasswd configure

Step 11 - Put TLS in front of the wiki

The image serves plain HTTP on port 80. For production, terminate TLS with your own certificate and domain. After you have a name pointing at the VM, tell Foswiki about it so the links it generates match, then restart:

sudo sed -i "s|^\$Foswiki::cfg{DefaultUrlHost}.*|\$Foswiki::cfg{DefaultUrlHost} = 'https://wiki.example.com';|" \
  /opt/foswiki/lib/LocalSite.cfg
sudo systemctl restart foswiki.service

Foswiki builds absolute URLs from the host your reader actually requested, so it already works correctly behind a proxy or on a non-standard port; DefaultUrlHost is the fallback used for notifications and command-line runs.

Step 12 - Where data lives

Everything under /var/lib/foswiki is on the dedicated Azure data disk, so you can snapshot or resize wiki content independently of the OS disk.

df -h /var/lib/foswiki | tail -1
sudo du -sh /var/lib/foswiki/data /var/lib/foswiki/pub

To back up the wiki, snapshot the data disk, or archive the directory:

sudo tar -czf /var/tmp/foswiki-backup.tgz -C /var/lib/foswiki data pub

Step 13 - Licensing and third-party components

Foswiki is licensed under the GNU General Public License, "either version 2 of the License, or (at your option) any later version". The full text ships with the image, along with a summary of every third-party component the distribution bundles and where each one's own licence lives.

head -12 /opt/foswiki/LICENSE
sed -n '1,20p' /opt/foswiki/NOTICE-cloudimg.txt

Maintenance

Ubuntu security updates are applied automatically by unattended-upgrades. Restart the wiki after an update that touches Perl or nginx:

sudo systemctl restart foswiki.service nginx.service

Foswiki's own logs are under /var/lib/foswiki/logs; the service's stdout goes to the journal:

sudo journalctl -u foswiki.service --no-pager -n 20

To upgrade Foswiki itself, follow the upstream upgrade guide at foswiki.org - your content and configuration are on the data disk and in LocalSite.cfg, both of which survive an application upgrade.

Support

cloudimg images are backed by 24/7 support. Contact support@cloudimg.co.uk with your VM's region, size and the output of sudo /usr/local/sbin/foswiki-selftest.sh.