Virtual machine image / software appliance

Introduction

A software appliance in the form of a VMware image is available to allow novices to easily set up a Foswiki installation without knowing anything about it or the operating system it runs on. The virtual machine image is preconfigured and ready to run. It can be accessed with your browser. This VM dynamically acquires an IP address. Please follow the instructions at the end of the boot screen. Point your browser to the address shown there.

Installation

Summary of installation steps:

1. Install a virtual machine "player" to run the VMs
2. Download a virtual machine image
3. Boot the virtual machine
4. Success!

1) Virtual machine software

You need one of these virtual machine applications to run the VMware image. All of them are free; you must register to use the VMware applications.:

• VMware player running on Windows / Linux
• VirtualBox running on Windows / Linux / OSX ( installation instructions)
• kvm-qemu on Linux installation instructions

2) Virtual Machine Images

Virtual machine image is listed in the Download section of the current Foswiki release (and older releases) when available.

3) Using the virtual machine image: Ready, Steady, Go!

Now just fire up your VirtualMachine and use it!

Configuration notes

The current virtual machine image contains the required Avahi service/definitions which facilitate service discovery on a local network. Using a bridged configuration (see below), you should be able to access http://foswiki.local out-of-the-box on both Linux and Apple OS X (which brands this "Bonjour" and sometimes "Zeroconf" functionality). On Windows, you'd usually need to install a third party driver (see, e.g., here).

VMWare Network configuration:

VMWare supports two common configurations, bridged and NAT.

• With NAT configuration, vmware will assign the guest system (foswiki) a private IP address. It is only accessible from the host server running the vm.
• With Bridged configuration, the guest ethernt interface will be bridged - become part of the same subnet as the host system. An IP address will be requested using DHCP from the attached network. If DHCP is not available, the guest will need to be configured with a static IP address.

If you used the VM settings file shipped with the Foswiki image, your network is configured for NAT. This ensures that your host OS provides a DHCP server. If you want to access your Foswiki from others hosts, please change to the bridged mode provided by your virtual machine player. In that case, you are responsible for setting up a DHCP server (or for reconfiguring your VM operating system with a static IP address).

Server IP Configuration:

If you want to configure a static IP, edit /etc/network/interfaces and change it following the below examples. The vi editor is available for expert users, and nano is a good editor to use if you are unfamiliar with linux.

This example configures the vm to use a static IP, and uses the Google public DNS servers. The IP address must be on the same subnet as the host machine. Enter sudo nano /etc/network/interfaces

auto eth0
iface eth0 inet static
address 192.168.1.4
gateway 192.168.1.1
netmask 255.255.255.0
dns-nameservers 8.8.8.8 8.8.4.4

Foswiki hostname configuration

For 100% correct operation, foswiki will require some additional configuration. Without this, you may see occasional 404 not-found or redirect errors following some Foswiki links. This is because the foswiki configuration is not aware of your hostname or IP address used for accessing Foswiki. In order to correctly generate links and redirects, the hostname(s) must be configured.

1. Visit the foswiki configuration. Direct your browser to http://<your-server-ip>/bin/configure
2. Click the General path settings tab, and edit the field {DefaultUrlHost}. It should be set to either a dns hostname or ip address of your server, without any trailing slash!
   • For example: http://192.168.23.45 or http://yourhost.com
3. If your host has more than one dns name, or you intend to use both an IP address and dns name on occasion, put any alternate names into the next field: {PermittedRedirectHostUrls}, separate multiple names with a comma.

   {DefaultUrlHost}   http://yourhost.com
   {PermittedRedirectHostUrls}  http://www.yourhost.com,http:./192.168.23.45

Further foswiki configuration

See InstallationGuide#Step_6:_Configure_email for details on how to set up email. You'll need this for user registration to work.

Accessing Foswiki Installation (userid's and passwords)

The following Foswiki users have been preconfigured:

(Note: Webmin has been removed as of the Foswiki 2.1.2 VM Image)

user role	User	Password
configure-save-password	(none)	foswiki	n/a on Foswiki 2.0
admin user for Foswiki	admin	foswiki
user for webmin	foswiki	foswiki	https://<virtual-machine-ip>:10000

Accessing the virtual machine's OS

You can login at the virtual machines login prompt, or access it using SSH.

User	Password
foswiki	foswiki

Root access

A root password is not configured for direct login. For root access, login with the foswiki user, and then use sudo. The sudo password is the login password for the user.

Getting the IP of the virtual machine OS

To find out the IP address, start your virtual machine, and when prompted for a username and password, enter foswiki and the password listed in the section " Accessing the virtual machine's OS". The latest image (Foswiki 1.1.9) will tell you the IP address in your login banner. Older versions: to show your current IP, type:

/usr/sbin/foswiki-ip

Localization of keyboard and character set

If you are using the installation in a non-English environment, the OS needs to be told about the localization needs.

To switch the character set, you need to install/select the character sets by this shell command and follow the dialog:

sudo dpkg-reconfigure console-data

To switch the keyboard layout (for easier use of non-qwerty keyboards in the shell), you need to install/select the keymap for the console by this shell command and follow the dialog.

System updates

As with any server installation, it's good practise to keep up with system updates. For routine OS updates:

• sudo su - Obtain root authorization.
• apt-get update Pull down the most recent package information
• apt-get upgrade Apply the updates, paying careful attention to any notices about package changes.

The latest Foswiki virtual machine is currently running Ubuntu 16.04.2 LTS, which will have updates through April 2021.

If you choose to upgrade the Foswiki 1.1.9 VM to the latest LTS, please note the following:

• It includes Apache 2.4.x, which makes a major change in configuration file syntax. It will not see the virtual host configuration /etc/apache2/sites-available/000-foswiki. You must rename any 000-foswiki and any other locally created configuration files to end in the .conf suffix for Apache to see them.