Ubuntu Desktop in Vagrant

Provision reproducible and consistent Ubuntu desktop virtual machines using Vagrant and VirtualBox.

https://gitlab.com/brlin/ubuntu-desktop-vagrant

Features

In order to improve the out-of-the-box user experience, this product introduces changes including but not limited to:

• Disable features that are not useful in the virtual machine use case (suspend, user authentications, and lock screens).
• Workaround known bugs in the VirtualBox guest drivers.
• Reduced boot time by optimizing VM configurations.
• Improved default console size and aspect ratio.
• Suppress unnecessary input-capturing warning user interfaces.
• Include common Vagrantfile template configuration for further customizations.
• Support configuring localization and default input method for the following locales:
  • Chinese(China)
  • Chinese(Taiwan)
  • Japanese(Japan)

Prerequisites

The following prerequisites must be satisfied in order to use this solution:

• The host system must have the following software installed and has its commands available in the command search PATHs:
  • OPTIONAL - (Your preferred archive extraction application/utility)
    For extracting the downloaded product release archive.
  • OPTIONAL - (Your preferred HTTPS client/Web browser)
    For downloading the product release archive.
  • Vagrant
    For provisioning the virtual machine that runs the Ubuntu desktop environment.
  • Oracle VirtualBox(must be in a version that your Vagrant installation supports, as of 2024/10/25 it is 7.0.*)
• The host system must have access to the Internet in order to retrieve the virtual machine image and other guest packages.

Usage

Follow the following instructions to use this solution:

1. Download the product release archive from the Releases page.

2. Extract the product release archive.

3. Launch a text terminal.

4. Change the working directory to the extracted product release directory by running the following command:

   cd /path/to/ubuntu-desktop-vagrant-X.Y.Z

5. Review and, when necessary, edit the Vagrantfile to satisfy your requirements. Refer to the Environment variables that can change the behavior of the provision program section for settings that can customize some of the VM provisioning details.

6. Run the following command to provision the Ubuntu desktop virtual machine:

   vagrant up

   A VM console window should popup, allowing you to operate the desktop environment.

   You can also run the following command to gain access to a text shell:

   vagrant ssh

7. OPTIONAL: Run the following command to destroy the virtual machine:

   vagrant destroy

   All data will be lost after the operation.

Environment variables that can change the behavior of the provision program

The following are the environment variables that can change the behavior of the provision program, which can be set in the config.vm.provision :shell, path: "vagrant-assets/provision.sh" call in the Vagrantfile:

ENABLE_KMSCON

Whether to install KMSCON and configure it to be the default virtual console implementation.

Setting this to true allows display of non-ASCII characters in the virtual console. Note that CJKV text input is still unsupported at the moment.

Supported values:

• true
• false

Default value: false

ENABLE_VBOXADD_INSTALLATION

Whether to re-install the VirtualBox Guest Additions, which should fix some problems of the guest support drivers from the distribution installation.

Setting the value of this environment variable to false can reduce the time required for re-provisioning the system.

Supported values:

• true
• false

Default value: true

INSTALL_LANGUAGE_SUPPORT

Specify whether to install language support packages, and if it should be installed, which locale should be used.

Supported values:

• null: Don't install language support packages
• Values supported by the -l option of the check-langauge-support command:
  • ll
  • lll
  • ll_CC
  • lll_CC
  • ll@variant
  • lll@variant
  • ll_CC@variant
  • lll_CC@variant
  • zh-hans
  • zh-hant

Default value: null

Credits

We would like to express our gratitude to Yoshimasa Niwa, who implemented and published the original implementation.

References

The following material are referenced during the development of this project:

• A simple Vagrantfile to setup Ubuntu desktop environment with Google Chrome and Japanese input
  The inspiration of this project.
• Shell Scripts - Provisioning | Vagrant | HashiCorp Developer
  Explains how to run external provision shell scripts in a Vagrantfile.
• Redirections (Bash Reference Manual)
  Explains how to use the Here Documents feature of the Bash shell scripting language.
• Bug #1933248 “please drop virtualbox-guest-dkms virtualbox-guest...” : Bugs : virtualbox package : Ubuntu
  Explains the reason why the virtualbox-guest-dkms package is no longer available in recent Ubuntu releases.
• Bug #2076520 “Ubuntu 24.04 LTS VBox VM does not boot anymore [...” : Bugs : linux package : Ubuntu
  Bug report regarding the problem where guest support no longer works when upgrading the Ubuntu kernel on a Ubuntu 24.04 system.
• How to "insert" guest additions image in VirtualBox from command line, while VM is running? - Unix & Linux Stack Exchange
  Explains how to programmically attach the VirtualBox Guest Additions installation ODD image to the virtual machine.
• VBoxManage | Oracle VirtualBox: User Guide
  Explains how to use the storagectl and storageattach VboxManage sub-commands.
• jeffskinnerbox/ubuntu-desktop: Vagrant Base Box for Ubuntu Desktop
  Project with a similar goal and different customizations.
• dotless-de/vagrant-vbguest: A Vagrant plugin to keep your VirtualBox Guest Additions up to date
  A Vagrant plugin that provides way to install/update the VirtualBox Guest Additions in the guest VM. It is obsoleted, though...
• vagrant-proxyconf - Proxy Configuration Plugin for Vagrant
  A Vagrant plugin that configures the guest VM to use user-specified proxy settings.
• tmatilai/vagrant-timezone: Vagrant plugin that configures the time zone of a virtual machine
  A Vagrant plugin that configures the guest VM to use user-specified timezone settings.
• Creating a Base Box | Vagrant | HashiCorp Developer
  Explains how to create a base box for other Vagrant users to initialize from.
• Guest Additions | Oracle VirtualBox: User Guide
  Explains the Drag and Drop support of VirtualBox.
• Virtual Machine Name - Configuration - VirtualBox Provider | Vagrant | HashiCorp Developer
  Explains how to customize the VM name that appears in the VirtualBox GUI.
• config.vm.hostname - config.vm - Vagrantfile | Vagrant | HashiCorp Developer
  Explains how to customize the guest VM hostname.
• Configure automatic login
  Explains how to configure automatic login in GDM.
• sudo - How do I prevent PolicyKit from asking for a password? - Ask Ubuntu
  Explains how to implement password prompt override in Polkit.
• pklocalauthority
  Explains basic information and configuration paths of the Local Authority Polkit authority implementation.
• linux - Possible values for uname -m - Stack Overflow
  Explains the possible values of the uanme -m command's output, and where do they came from.
• ArchitectureSpecificsMemo - Debian Wiki
  Enumerates the mapping of the uname -m output and the debian architecture names.
• KMSCON - ArchWiki
  Explains how to configure KMSCON to replace the default virtual console implementation.

Licensing

Unless otherwise noted(individual file's header/REUSE.toml), this product is licensed under the MIT license.

This work complies to the REUSE Specification, refer the REUSE - Make licensing easy for everyone website for info regarding the licensing of this product.