new repository

1 files changed, 83 insertions, 0 deletions

diff --git a/devdocs/vagrant/provisioning%2Fbasic_usage.html b/devdocs/vagrant/provisioning%2Fbasic_usage.html
new file mode 100644
index 00000000..08a830b0
--- /dev/null
+++ b/devdocs/vagrant/provisioning%2Fbasic_usage.html
@@ -0,0 +1,83 @@
+<h1 id="basic-usage-of-provisioners">  Basic Usage of Provisioners </h1> <p>While Vagrant offers multiple options for how you are able to provision your machine, there is a standard usage pattern as well as some important points common to all provisioners that are important to know.</p> <h2 id="configuration">  Configuration </h2> <p>First, every provisioner is configured within your <a href="../vagrantfile/index">Vagrantfile</a> using the <code>config.vm.provision</code> method call. For example, the Vagrantfile below enables shell provisioning:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config|
+  # ... other configuration
+
+  config.vm.provision "shell", inline: "echo hello"
+end
+</pre></div>
+<p>Every provisioner has a type, such as <code>"shell"</code>, used as the first parameter to the provisioning configuration. Following that is basic key/value for configuring that specific provisioner. Instead of basic key/value, you can also use a Ruby block for a syntax that is more like variable assignment. The following is effectively the same as the prior example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config|
+  # ... other configuration
+
+  config.vm.provision "shell" do |s|
+    s.inline = "echo hello"
+  end
+end
+</pre></div>
+<p>The benefit of the block-based syntax is that with more than a couple options it can greatly improve readability. Additionally, some provisioners, like the Chef provisioner, have special methods that can be called within that block to ease configuration that cannot be done with the key/value approach, or you can use this syntax to pass arguments to a shell script.</p> <p>The attributes that can be set in a single-line are the attributes that are set with the <code>=</code> style, such as <code>inline = "echo hello"</code> above. If the style is instead more of a function call, such as <code>add_recipe "foo"</code>, then this cannot be specified in a single line.</p> <p>Provisioners can also be named (since 1.7.0). These names are used cosmetically for output as well as overriding provisioner settings (covered further below). An example of naming provisioners is shown below:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config|
+  # ... other configuration
+
+  config.vm.provision "bootstrap", type: "shell" do |s|
+    s.inline = "echo hello"
+  end
+end
+</pre></div>
+<p>Naming provisioners is simple. The first argument to <code>config.vm.provision</code> becomes the name, and then a <code>type</code> option is used to specify the provisioner type, such as <code>type: "shell"</code> above.</p> <h2 id="running-provisioners">  Running Provisioners </h2> <p>Provisioners are run in three cases: the initial <code>vagrant up</code>, <code>vagrant
+provision</code>, and <code>vagrant reload --provision</code>.</p> <p>A <code>--no-provision</code> flag can be passed to <code>up</code> and <code>reload</code> if you do not want to run provisioners. Likewise, you can pass <code>--provision</code> to force provisioning.</p> <p>The <code>--provision-with</code> flag can be used if you only want to run a specific provisioner if you have multiple provisioners specified. For example, if you have a shell and Puppet provisioner and only want to run the shell one, you can do <code>vagrant provision --provision-with shell</code>. The arguments to <code>--provision-with</code> can be the provisioner type (such as "shell") or the provisioner name (such as "bootstrap" from above).</p> <h2 id="run-once-always-or-never">  Run Once, Always or Never </h2> <p>By default, provisioners are only run once, during the first <code>vagrant up</code> since the last <code>vagrant destroy</code>, unless the <code>--provision</code> flag is set, as noted above.</p> <p>Optionally, you can configure provisioners to run on every <code>up</code> or <code>reload</code>. They will only be not run if the <code>--no-provision</code> flag is explicitly specified. To do this set the <code>run</code> option to "always", as shown below:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config|
+  config.vm.provision "shell", inline: "echo hello",
+    run: "always"
+end
+</pre></div>
+<p>You can also set <code>run:</code> to <code>"never"</code> if you have an optional provisioner that you want to mention to the user in a "post up message" or that requires some other configuration before it is possible, then call this with <code>vagrant provision --provision-with bootstrap</code>.</p> <p>If you are using the block format, you must specify it outside of the block, as shown below:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config|
+  config.vm.provision "bootstrap", type: "shell", run: "never" do |s|
+    s.inline = "echo hello"
+  end
+end
+</pre></div>
+<h2 id="multiple-provisioners">  Multiple Provisioners </h2> <p>Multiple <code>config.vm.provision</code> methods can be used to define multiple provisioners. These provisioners will be run in the order they're defined. This is useful for a variety of reasons, but most commonly it is used so that a shell script can bootstrap some of the system so that another provisioner can take over later.</p> <p>If you define provisioners at multiple "scope" levels (such as globally in the configuration block, then in a <a href="../multi-machine/index">multi-machine</a> definition, then maybe in a <a href="../providers/configuration">provider-specific override</a>), then the outer scopes will always run <em>before</em> any inner scopes. For example, in the Vagrantfile below:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config|
+  config.vm.provision "shell", inline: "echo foo"
+
+  config.vm.define "web" do |web|
+    web.vm.provision "shell", inline: "echo bar"
+  end
+
+  config.vm.provision "shell", inline: "echo baz"
+end
+</pre></div>
+<p>The ordering of the provisioners will be to echo "foo", "baz", then "bar" (note the second one might not be what you expect!). Remember: ordering is <em>outside in</em>.</p> <p>With multiple provisioners, use the <code>--provision-with</code> setting along with names to get more fine grained control over what is run and when.</p> <h2 id="overriding-provisioner-settings">  Overriding Provisioner Settings </h2> <blockquote class="alert alert-warning"> <p><strong>Warning: Advanced Topic!</strong> Provisioner overriding is an advanced topic that really only becomes useful if you are already using multi-machine and/or provider overrides. If you are just getting started with Vagrant, you can safely skip this.</p> </blockquote>
+<p>When using features such as <a href="../multi-machine/index">multi-machine</a> or <a href="../providers/configuration">provider-specific overrides</a>, you may want to define common provisioners in the global configuration scope of a Vagrantfile, but override certain aspects of them internally. Vagrant allows you to do this, but has some details to consider.</p> <p>To override settings, you must assign a name to your provisioner.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config|
+  config.vm.provision "foo", type: "shell",
+    inline: "echo foo"
+
+  config.vm.define "web" do |web|
+    web.vm.provision "foo", type: "shell",
+      inline: "echo bar"
+  end
+end
+</pre></div>
+<p>In the above, only "bar" will be echoed, because the inline setting overloaded the outer provisioner. This overload is only effective within that scope: the "web" VM. If there were another VM defined, it would still echo "foo" unless it itself also overloaded the provisioner.</p> <p><strong>Be careful with ordering.</strong> When overriding a provisioner in a sub-scope, the provisioner will run at <em>that point</em>. In the example below, the output would be "foo" then "bar":</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config|
+  config.vm.provision "foo", type: "shell",
+    inline: "echo ORIGINAL!"
+
+  config.vm.define "web" do |web|
+    web.vm.provision "shell",
+      inline: "echo foo"
+    web.vm.provision "foo", type: "shell",
+      inline: "echo bar"
+  end
+end
+</pre></div>
+<p>If you want to preserve the original ordering, you can specify the <code>preserve_order: true</code> flag:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config|
+  config.vm.provision "do-this",
+    type: "shell",
+    preserve_order: true,
+    inline: "echo FIRST!"
+  config.vm.provision "then-this",
+    type: "shell",
+    preserve_order: true,
+    inline: "echo SECOND!"
+end
+</pre></div><div class="_attribution">
+  <p class="_attribution-p">
+    &copy; 2010&ndash;2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br>
+    <a href="https://www.vagrantup.com/docs/provisioning/basic_usage.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/basic_usage.html</a>
+  </p>
+</div>