TURNKEYGNU / LINUX
English

Documentation

Appliance installation tutorial with VirtualBox

Note: this tutorial is quite dated. There is an updated version here. In essence it should still be generally relevant, however some of the VBox options may have changed and some of the TKL options and screenshots may not be quite the same as noted here. If you have any issues, please post in the Support section of the forums.

Getting Started

Installing to a VirtualBox VM (Virtual Machine) is one of the fastest and easiest ways to get up and running with TurnKey Linux. The open source edition of VirtualBox can be downloaded for free from the VirtualBox website.

As the following step by step tutorial shows, once you are familiar with the basics, deploying an appliance takes just a few minutes. The installation process is the same for all appliances. We'll be installing TurnKey Joomla as an example.

VirtualBox vs VMWare (and others)

VirtualBox is the most popular open source alternative to VMWare's proprietary virtualization products. VMWare is not open source but some of its products are also available for free download (e.g., VMWare Player and VMWare Server).

TurnKey Linux is designed to work well with both VMWare and VirtualBox (and other platforms). This tutorial focuses on VirtualBox, but the principles are the same regardless of what virtualization software you use.

Installation and basic usage video

Note: The following video shows installation of an older version of TurnKey Linux. The basics are the same but a few things have changed. For example, TurnKey is now available in a ready-to-run VM optimized build (in addition to the ISO). Also in TurnKey Linux v11+ passwords are set on first boot and not during installation.

First, install VirtualBox

If you haven't done so already, download and install VirtualBox, a free software virtualization program available for Windows, Mac OS X and Linux. It's preferable to use a recent version (2.X and up).

Second, choose a build type and download the image

Appliances are available in multiple build types which work well with VirtualBox:

  • VM optimized images
    1. Default build: it's a ZIP file containing a ready-to-run VMDK hard disk image which includes a virtualization optimized kernel and VMWare tools.
    2. OVF build: it's a ZIP file containing the default VM build converted to OVF format, which is easier to work with sometimes (e.g., high-end VMWare products).
  • Generic ISO image: Live CD image that can be installed anywhere, including bare metal and most types of virtual machine.

Confused which to choose? Just download default VM build and use that. It's the first download link on the appliance page.

After the download, follow the instructions in the appropriate third step below.

Third, deploy a VM optimized image (#1 alternative)

Create new VM

Exactly how you setup a VM image depends on whether you've downloaded the default VM build or the OVF version. Both work equally well with VirtualBox.

Using the default VM optimized build...

  1. Unzip the default VM build
  2. In VirtualBox, launch the VM creation wizard by clicking the New button:
    • OS Type: Select Linux / Ubuntu (Note: select 64bit if you are using the amd64 build) as your operating system
    • Memory: Give the new VM at least 256 MB of RAM.
    • Virtual Hard Disk: Select "use an existing hard disk", navigate to the directory where you extraced the ZIP, and select the VMDK hard disk image.

Using the OVF...

  1. Unzip the OVF build
  2. In VirtualBox, click File on the menu bar and select Import Appliance, then navigate to the directory where you extracted the ZIP and select the OVF file.
  3. Wait for VirtualBox to finish importing the OVF.

Basic VM configuration

After you've created the new VM, you'll need to tweak its configuration:

  1. Settings > System > Processor > Enable PAE/NX
    • PAE: This is required as the linux-virtual kernel in the VM optimized images uses PAE to allow addressing of more than 4GB of memory.
    • NX: refers to the CPU feature required by VirtualBox to support PAE. All new CPUs support NX but some older ones may not.
      • Troubleshooting: On old hardware if the VM refuses to boot, you may need to install from ISO instead.
  2. Settings > Network > Adapter 1 > Attach to: bridged
    Bridging your VM connects it to the local network your host machine is on. (There are other options that are explained here).

Now boot your virtual appliance for the first time.

Third, install the generic ISO image (#2 alternative)

Note: The following screenshots are for older versions of VirtualBox and TurnKey Linux. Some of the details have changed, though the essentials are the same.

Create a new Virtual Machine

Start VirtualBox and click the New button from the menu. This starts a VM (Virtual Machine) creation wizard.

Give your new VM a name (e.g., TurnKey Joomla) and select Linux Ubuntu (Note: make sure you select the '64bit' variety if you are using an amd64 ISO) as your operating system.

Follow through the VM wizard to completion, allocating at least 256MB RAM for the VM and creating a new Virtual Disk for it with the Virtual Disk Wizard.  Just accept the defaults and a few clicks on Next and you're done.

After exiting from the VM creation wizard, you'll see your new VM in the machine list on the main screen.

Configuring the Virtual Machine

Next you'll need to tweak a few configuration settings for the new VM (e.g., Network, CD image, Boot order). Click the Settings button to start.

Configure boot order

In the General section, click on the Advanced tab and change the boot order so that Hard Disk is before CD/DVD-ROM drive. This way after we install the appliance from the appliance CD image it will boot straight from the virtual Hard Disk.

Note for users with AMD CPUs: if you have an AMD Phenom or Barcelona-level Opteron CPU you may need to enable IO APIC here to work around a Linux kernel bug.

Configure network

In the Network section, attach your VM to a Bridged Adapter (in older VirtualBox versions this is called Host Interface). This bridges your VM to the local network your host machine is connected to.  If you have multiple network interface cards on the host, select which of them you want your VM to attach to. If unsure, experiment. You can always change this later.

Configure CDROM boot media

TurnKey appliances are packaged as an installable Live CD image (a bootable ISO).

In the CD/DVD-ROM section, check Mount CD/DVD Drive and the select ISO Image File. Clicking on the right-side folder icon starts the Virtual Media Manager, which allows you to select the TurnKey Joomla ISO image you previously downloaded.

Installation

Back in the VirtualBox main menu, select the TurnKey Joomla Virtual Machine and click on the "Start" button.

Once the VM starts, you will see the boot loader menu. Select the "Install to hard disk" option with the keyboard and press Enter.

This boots TurnKey Joomla straight into the appliance's installer.  Select the default "Guided" partitioning method, which figures out how to partition the virtual hard disk automatically. If unsure, just confirm the defaults.

Confirm the re-partitioning of the virtual hard disk.

The installer will now quickly install the appliance to the virtual hard disk. Usually this takes about a minute. When installation is complete, restart the appliance.

The system will now reboot from the virtual Hard Disk.

The first time the system boots, you'll be taken to various configuration screens (e.g., set passwords, install latest security updates). After that the first boot will finish and you'll reach the Configuration Console's Usage screen.

You can now use a browser to log into your newly installed TurnKey Joomla appliance. Enjoy!