Foswiki 2.1

Prerequisites

Before you deploy, make sure you have:

• An active Azure subscription
• An SSH key pair
• A VNet and subnet in the target region
• NSG inbound rules that allow 22/tcp from your management network and 80/tcp from wherever your readers are

Standard_B2s (2 vCPU / 4 GiB RAM) is the recommended starting size. 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 SecureAnyCloud, 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 select Review + create and Create.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:foswiki:default:latest
az vm create \
  --resource-group <your-rg> \
  --name foswiki \
  --image sac1647283583153:foswiki:default:latest \
  --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 are active, port 80 is open to the world, port 9000 is bound to 127.0.0.1 only, and the data disk is 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 that 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>/. The browser redirects you 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 you are signed in, the left-hand sidebar shows your name and the toolbox. 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. Self-registration is disabled in this image, so following the link 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 experiment) and choose Create New Topic. Give it a WikiWord name such as SacWelcome, 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 and save. Tick Force new revision if you want a separate entry rather than an amendment to your own recent 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 and creates a topic. It checks that 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 nobody who finds a public VM can join it. Add people deliberately instead.

Create the account's password with the helper the image ships. The helper 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. This lets the name resolve, so the person can be mentioned and granted access. To make somebody an administrator, edit Main.AdminGroup and add their WikiName to the GROUP setting.

To 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. nginx refuses an unauthenticated request 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 prompts for the HTTP Basic credential first. Use FOSWIKI_CONFIGURE_USER and FOSWIKI_CONFIGURE_PASSWORD from Step 5. Foswiki then requires you to be signed in as the wiki administrator behind it.

Restart the wiki after you save 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 that 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

• /opt/foswiki: the Foswiki application (Perl code, templates, locales, tools), read-only to the service account
• /var/lib/foswiki/data: every topic, its revision history (<Topic>,pfv/), and the .htpasswd password file
• /var/lib/foswiki/pub: attachments and the shipped System web assets, served directly by nginx
• /var/lib/foswiki/working: sessions and temporary files
• /var/lib/foswiki/logs: Foswiki's own event and error logs
• /opt/foswiki/lib/LocalSite.cfg: the whole configuration
• /root/foswiki-credentials.txt: this VM's generated credentials, root-only

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 component's own license lives.

head -12 /opt/foswiki/LICENSE sed -n '1,20p' /opt/foswiki/NOTICE-sac.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, and 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, and both survive an application upgrade.

Support

SecureAnyCloud backs this image with 24/7 support. Contact sales@secureanycloud.com with your VM's region, size and the output of sudo /usr/local/sbin/foswiki-selftest.sh.

Deploy on Azure

Launch Foswiki 2.1 on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com