Fixes #12630: Add a \"first steps\" guide for new users

rudder-by-example/.gitignore → guides/.gitignore

@@ -1,3 +1,4 @@
 _book
-/target
+target
 node_modules
+.idea

guides/get-started/Makefile

@@ -0,0 +1,4 @@
+include ../gitbook.mk
+
+NAME = get-started
+

guides/get-started/book.json

@@ -0,0 +1,10 @@
+{
+    "root": "./src",
+    "plugins": [ "-sharing", "edit-link", "theme-official", "asciidoc-admonition-icons" ],
+    "pluginsConfig": {
+        "edit-link": {
+            "base": "https://github.com/Normation/rudder-doc/edit/master/guides/get-started/src",
+            "label": "Edit"
+        }
+    }
+}

guides/get-started/src/README.adoc

@@ -0,0 +1,5 @@
+= Getting started with Rudder
+
+This document will guide you through the installation of a test Rudder platform
+and the configuration of a real configuration use-case.
+

guides/get-started/src/SUMMARY.adoc

@@ -0,0 +1,16 @@
+= Summary
+
+. link:introduction/README.adoc[Introduction]
+.. link:introduction/demo.adoc[Test environment]
+. link:configuration-policies/README.adoc[Configuration policies]
+.. link:configuration-policies/technique.adoc[Create a technique]
+.. link:configuration-policies/directive.adoc[Create a directive]
+.. link:configuration-policies/agent.adoc[Apply a first policy]
+.. link:configuration-policies/policy-mode.adoc[Audit vs. Enforce]
+. link:node-management/README.adoc[Node management]
+.. link:node-management/node.adoc[Add a new node]
+.. link:node-management/group.adoc[Group nodes]
+. Configuration policy management
+.. Create a rule
+.. Compliance
+.. Traceability

guides/get-started/src/introduction/README.adoc

@@ -0,0 +1,44 @@
+= Introduction
+
+Rudder is a an *automation* and *compliance* solution dedicated to production constraints.
+This guide is designed to help you discover Rudder workflow, and will make you able to:
+
+* Setup Rudder agent
+* Manage Nodes with Rudder
+* Create configuration polices using built-in components
+* Create your own configuration policies
+* Apply and control the enforcement of these policies
+
+It requires no prior knowledge about configuration management,
+only very basic Unix command-line skills.
+
+[NOTE]
+
+====
+
+This guide is targeted for the lastest major release of Rudder, but
+applies to all Rudder versions.
+
+====
+
+== Goal
+
+In this guide, we will guide you through the setup of a test platform including:
+
+* A base security configuration for our nodes, deploying a user and an SSH configuration
+* A static website built from a static site generator on a node
+
+== Rudder concepts
+
+Rudder allows managing the configuration of machines
+
+But what is configuration:
+
+* Package httpd installed in version 2.4.12
+* Service ntpd is currently running
+* SSH connection using passwords are disabled
+
+Configuration is managed through the definition of an expected state.
+
+This state is applied by Rudder, and the information about its application
+is continuously updated on the server.

guides/get-started/src/introduction/demo.adoc

@@ -0,0 +1,52 @@
+== Setup a test environment
+
+This section will help you setup a test environment. The rest of the tutorial assumes you are
+using this `rudder-vagrant` environment (you can also setup your own,
+you will only have to substitute hostnames/IP addresses when necessary).
+
+This installation method is cross-platform, and you can use it on Linux, Microsoft Windows, Mac OS X
+and more.
+
+You will need:
+
+* VirtualBox, tu run the demo virtual machines (https://www.virtualbox.org/wiki/Downloads[Download])
+* Vagrant, to handle the virtual machines configuration and provisionning (https://www.vagrantup.com/downloads.html[Download])
+
+On Debian/Ubuntu systems, just run `sudo apt-get install -y virtualbox vagrant`, and on RHEL/Fedora systems,
+run `sudo yum install -y VirtualBox vagrant`.
+
+Once they are installed, run:
+
+----
+git clone https://github.com/Normation/rudder-vagrant.git
+cd rudder-vagrant
+----
+
+You can also directly download the rudder-vagrant content with this https://github.com/Normation/rudder-vagrant/archive/master.zip[link].
+
+And then, to create the environement:
+
+----
+vagrant up
+----
+
+This will download the virtual machine image if needed, and will setup a Rudder environment using two virtual machines.
+This will likely take some time, so feel free to grab a coffee before we dive into Rudder.
+
+[TIP]
+
+.Vagrant commands
+
+====
+
+Here are the basic vagrant commands useful to manage your environment:
+
+* `vagrant up` to bring the environment up, wether the VM need to created or only started
+* `vagrant halt` to stop the virtual machines (but keep them for later use)
+* `vagrant destroy` to totally remove virtual machines
+* `vagrant ssh server|agent` to connect to one of your nodes using SSH
+
+====
+
+Once the command returns, you are ready to get started! You now have two virtual machines,
+`server` and `agent`.

rudder-by-example/Makefile → guides/gitbook.mk

@@ -1,5 +1,3 @@
-NAME = rudder-by-example
-
 all: html pdf epub
 
 depends:

guides/rudder-by-example/Makefile

@@ -0,0 +1,4 @@
+include ../gitbook.mk
+
+NAME = rudder-by-example
+

rudder-by-example/book.json → guides/rudder-by-example/book.json

@@ -3,7 +3,7 @@
     "plugins": [ "-sharing", "edit-link" ],
     "pluginsConfig": {
         "edit-link": {
-            "base": "https://github.com/Normation/rudder-doc/edit/master/rudder-by-example/src",
+            "base": "https://github.com/Normation/rudder-doc/edit/master/guides/rudder-by-example/src",
             "label": "Edit"
         }
     }