doc/vagrant.md

   1 # Using oi-userland with Vagrant
   2
   3 oi-userland includes Vagrantfile, which allows contributing from non-OpenIndiana
   4 platforms such as Mac OS X, Linux or Windows. Currently, only the VirtualBox
   5 provider is supported. Vagrant is suitable for cases when you don't have access to OpenIndiana host and want to develop/contribute to oi-userland.
   6
   7 ## Quickstart
   8
   9 * Download Vagrant from the official [download site](https://www.vagrantup.com/downloads.html). Select a version for your platform. We recommend to use the latest version.
  10 * Download VirtualBox from the official [download site](https://www.virtualbox.org/wiki/Downloads). We recommend to  always use the latest VirtualBox.
  11 * Run the following commands:
  12
  13   ```
  14   git clone https://github.com/OpenIndiana/oi-userland.git && \
  15   cd oi-userland && \
  16   vagrant up
  17   ```
  18
  19 ## Getting started
  20
  21 * Download Vagrant from the official [download site](https://www.vagrantup.com/downloads.html). Select a version for your platform. We recommend to use the latest version.
  22 * Download VirtualBox from the official [download site](https://www.virtualbox.org/wiki/Downloads). We recommend to use always the latest VirtualBox.
  23 * Fork the [oi-userland repository](https://github.com/OpenIndiana/oi-userland.git) on GitHub.
  24 * Clone your oi-userland repository somewhere:
  25
  26   ```
  27   git clone https://github.com/<username>/oi-userland.git oi-userland
  28   ```
  29
  30 * Configure remote repository, so you can fetch updates easily:
  31
  32   ```
  33   git remote add upstream https://github.com/OpenIndiana/oi-userland.git
  34   ```
  35
  36   Updates are fetched with the following commands:
  37
  38   ```
  39   git pull --rebase upstream oi/hipster
  40   ```
  41
  42 * On Windows make sure, that `rsync` and `ssh` commands are available, and that Hyper-V (if actually installed) is disabled:
  43
  44   ```
  45   dism.exe /Online /Disable-Feature:Microsoft-Hyper-V-All
  46   ```
  47
  48   And restart.
  49
  50 * If your VirtualBox home directory, usually `~username/VirtualBox VMs/`, is on SSD disk, enable `--nonrotational` configuration option in `Vagrantfile` in `oi-userland/` directory by uncommenting the respective line:
  51
  52   ```
  53   v.customize ["storageattach", :id, "--storagectl", "SATA Controller", "--port", 0, "--nonrotational", "on"]
  54   ```
  55
  56 * Start the VM by running:
  57
  58   ```
  59   vagrant up
  60   ```
  61
  62   This might take a while as development utilities will be downloaded and oi-userland configured.
  63
  64 * Once the VM is online, enter it:
  65
  66   ```
  67   vagrant ssh
  68   ```
  69
  70 * When finished, exit the machine and halt down the machine:
  71
  72   ```
  73   vagrant halt
  74   ```
  75
  76 * To destroy the machine, run:
  77
  78   ```
  79   vagrant destroy
  80   ```
  81
  82 ## Vagrant box updates
  83
  84 Vagrant box is configured to check for updates and if a new update is available,
  85 Vagrant will display a notice.
  86
  87 ## Getting help
  88
  89 If not sure, ask on IRC, mailing list, etc.