<commit_before>.. _section-installation-makahiki-vagrant-configuration-vagrant:

Configuring Vagrant Settings
============================

This section contains instructions for changing Vagrant settings related to 
the virtual machine used by Makahiki. 

See the `Vagrant 1.2 documentation`_ for more information.

.. _Vagrant 1.2 documentation: http://docs.vagrantup.com/v2/

Throughout this guide, a ``>`` indicates that a command is performed on the 
host OS. A ``%`` indicates that a command is performed on the virtual machine, 
and that the working directory in which the command is run does not matter.

Vagrant Commands
----------------

Some basic Vagrant commands are listed below:

  * ``vagrant up``: Start the virtual machine. If the virtual machine defined in the Vagrantfile does not exist, it will be created and the provisioning script will be run.
    * ``vagrant up --provision``: Start the virtual machine and force it to run the provisioning script.
  * ``vagrant reload``: Restart the virtual machine. Equivalent to ``vagrant halt`` followed by ``vagrant up``.
    * ``vagrant reload --provision``: Restart the virtual machine and force it to run the provisioning script.
  * ``vagrant suspend``: Freeze the current state of the virtual machine.
  * ``vagrant resume``: Reactivate a machine that has been suspended.
  * ``vagrant halt``: Attempt to shut down the virtual machine gracefully.
    * ``vagrant halt --force``: Force a shutdown. This is equivalent to pulling the plug.
  * ``vagrant status``: Show the status of the virtual machine.
  * ``vagrant destroy``: Deletes a virtual machine. The Vagrantfile is not deleted.

.. note: The behavior of the ``vagrant up`` and ``vagrant reload`` commands has changed since Vagrant 1.3.0. 
   On older versions of Vagrant, the behavior of the commands was as follows:
   * ``vagrant up``: Start the virtual machine and run the provisioning script. If the virtual machine defined in the Vagrantfile does not exist, it will be created. 
     * ``vagrant up --no-provision``: Start the machine without provisioning it.
   * ``vagrant reload``: Restart the virtual machine and run the provisioning script. Equivalent to ``vagrant halt`` followed by ``vagrant up``.
     * ``vagrant reload --no-provision``: Restart the virtual machine without provisioning it.

You can only run commands for a given Vagrant virtual machine if your working 
directory is the directory that has the virtual machine's Vagrantfile.

Vagrant virtual machines are linked to the directory which contains their Vagrantfile. 
If the same Vagrantfile is copied into another directory, the ``vagrant up`` command 
will create a new virtual machine.

Re-Provisioning Vagrant
-----------------------

When the Vagrant virtual machine was created, a provisioning script was run.

.. warning:: Running the provisioning script **erases all databases** in the 
   PostgreSQL installation on the system, including the Makahiki database.

If you want to run the provisioning script again, you can do this in two ways.

Re-provision the Virtual Machine at Startup
*******************************************

In the makahiki/vagrant directory, start the virtual machine with "vagrant up --provision."
This will run the provisioning script designated in the Vagrantfile::

  > vagrant up --provision 

.. note: In Vagrant versions prior to 1.3.0, use this command instead::

   > vagrant up

The error ``dpkg-preconfigure: unable to re-open stdin: No such file or directory`` 
may occur during provisioning. This error does not affect the provisioning script 
and can be ignored.

Re-provision a Virtual Machine That is Already Running
******************************************************

Use the ``vagrant provision`` command in the host machine::

  > vagrant provision

Configure the RAM of the Virtual Machine
----------------------------------------

The default settings in the Vagrantfile for Makahiki allow the virtual machine 
to use up to 1536 MB (1.5 GB) of RAM. To change this, you will need to edit the 
Vagrantfile while the virtual machine is shut down.

In the virtual machine, if the web server is running, stop it by pressing 
Control-C in the SSH terminal. Then shut down the virtual machine to end the 
SSH session::

  % sudo shutdown -h now

To change the RAM allocated to the Virtualbox VM, edit the ``vb.customize`` 
line in the Vagrantfile by changing the number after the ``--memory`` flag::<commit_msg>installation-makahiki-vagrant-configuration-vagrant.rst: Changed note to warning for emphasis in "Vagrant Commands" section.<commit_after>.. _section-installation-makahiki-vagrant-configuration-vagrant:

Configuring Vagrant Settings
============================

This section contains instructions for changing Vagrant settings related to 
the virtual machine used by Makahiki. 

See the `Vagrant 1.2 documentation`_ for more information.

.. _Vagrant 1.2 documentation: http://docs.vagrantup.com/v2/

Throughout this guide, a ``>`` indicates that a command is performed on the 
host OS. A ``%`` indicates that a command is performed on the virtual machine, 
and that the working directory in which the command is run does not matter.

Vagrant Commands
----------------

Some basic Vagrant commands are listed below:

  * ``vagrant up``: Start the virtual machine. If the virtual machine defined in the Vagrantfile does not exist, it will be created and the provisioning script will be run.
    * ``vagrant up --provision``: Start the virtual machine and force it to run the provisioning script.
  * ``vagrant reload``: Restart the virtual machine. Equivalent to ``vagrant halt`` followed by ``vagrant up``.
    * ``vagrant reload --provision``: Restart the virtual machine and force it to run the provisioning script.
  * ``vagrant suspend``: Freeze the current state of the virtual machine.
  * ``vagrant resume``: Reactivate a machine that has been suspended.
  * ``vagrant halt``: Attempt to shut down the virtual machine gracefully.
    * ``vagrant halt --force``: Force a shutdown. This is equivalent to pulling the plug.
  * ``vagrant status``: Show the status of the virtual machine.
  * ``vagrant destroy``: Deletes a virtual machine. The Vagrantfile is not deleted.

.. warning: The descriptions above apply only to Vagrant 1.3.0 and later.
   On Vagrant versions before 1.3.0, the ``vagrant up`` and ``vagrant reload`` commands worked as follows:
   * ``vagrant up``: Start the virtual machine and run the provisioning script. If the virtual machine defined in the Vagrantfile does not exist, it will be created. 
     * ``vagrant up --no-provision``: Start the machine without provisioning it.
   * ``vagrant reload``: Restart the virtual machine and run the provisioning script. Equivalent to ``vagrant halt`` followed by ``vagrant up``.
     * ``vagrant reload --no-provision``: Restart the virtual machine without provisioning it.

You can only run commands for a given Vagrant virtual machine if your working 
directory is the directory that has the virtual machine's Vagrantfile.

Vagrant virtual machines are linked to the directory which contains their Vagrantfile. 
If the same Vagrantfile is copied into another directory, the ``vagrant up`` command 
will create a new virtual machine.

Re-Provisioning Vagrant
-----------------------

When the Vagrant virtual machine was created, a provisioning script was run.

.. warning:: Running the provisioning script **erases all databases** in the 
   PostgreSQL installation on the system, including the Makahiki database.

If you want to run the provisioning script again, you can do this in two ways.

Re-provision the Virtual Machine at Startup
*******************************************

In the makahiki/vagrant directory, start the virtual machine with "vagrant up --provision."
This will run the provisioning script designated in the Vagrantfile::

  > vagrant up --provision 

.. note: In Vagrant versions before 1.3.0, run this command instead::

   > vagrant up

The error ``dpkg-preconfigure: unable to re-open stdin: No such file or directory`` 
may occur during provisioning. This error does not affect the provisioning script 
and can be ignored.

Re-provision a Virtual Machine That is Already Running
******************************************************

Use the ``vagrant provision`` command in the host machine::

  > vagrant provision

Configure the RAM of the Virtual Machine
----------------------------------------

The default settings in the Vagrantfile for Makahiki allow the virtual machine 
to use up to 1536 MB (1.5 GB) of RAM. To change this, you will need to edit the 
Vagrantfile while the virtual machine is shut down.

In the virtual machine, if the web server is running, stop it by pressing 
Control-C in the SSH terminal. Then shut down the virtual machine to end the 
SSH session::

  % sudo shutdown -h now

To change the RAM allocated to the Virtualbox VM, edit the ``vb.customize`` 
line in the Vagrantfile by changing the number after the ``--memory`` flag::
{'fraction_non_alphanumeric': 0.10930232558139535, 'fraction_numerical': 0.004097452934662237, 'mean_word_length': 3.9188453159041394, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6645096', 'n_tokens_mistral': 2414, 'n_tokens_neox': 2336, 'n_words': 1219}