Merge branch 'quick_start' into 'master'

Quick start

See merge request !4

README.md

@@ -11,6 +11,7 @@ SOCTools aims at being easy to install and that all components should be fully i
 
 ## Documentation
 
+* [Quick Start](doc/quickstart.md)
 * [Architecture](doc/architecture.md)
 * [Installation](doc/install.md)
 * [Data ingestion](doc/dataingestion.md)

doc/install.md

@@ -10,6 +10,7 @@ The current version of SOCTools only runs on a single server. A fully distribute
 ## Prerequisites
 
 * Minimal installation of CentOS7
+* Set hostname for your Virtual Machine and create corresponding DNS record (will be needed later)
 * Install Ansible
   * `sudo yum -y install epel-release`  
   * `sudo yum -y install ansible git`
@@ -59,23 +60,21 @@ Build SOCTools CA needed for service and user certificates:
 * `ansible-playbook -i inventories buildca.yml`  
 This playbook will generate some errors but this is normal as long as the playbook ignores them and finish without stopping. 
 
-Start SOCTools:
+Start SOCTools for the first time and initialize:
 * `ansible-playbook -i inventories soctools.yml -t start-docker-containers`
 * `ansible-playbook -i inventories soctools.yml -t init`
 
-
-## Stopping and Restarting SOCTools
-In case you need to restart whole server, the proper procedure to this is following:
-
-Stop SOCTools:
+Stop SOCTools without destroying containers:
 * `ansible-playbook -i inventories soctools.yml -t stop-docker-containers`
 
-Shutdown or restart the server/host.
+Restart SOCTools after it has been stopped with `stop-docker-containers` tag:
+* `ansible-playbook -i inventories soctools.yml -t start-docker-containers`
 
-Start the server/host.
+Destroy SOCTools containers:
+* `ansible-playbook -i inventories soctools.yml -t destroy-docker-containers`
 
-Start SOCTools:
-* `ansible-playbook -i inventories soctools.yml -t start-docker-containers`
+Deletion of the SOCTools containers will not delete the data in the volumes, and if the deletion of all data is also required, you should also execute the following command:
+* `docker system prune -a`
 
 
 ## Errors building SOCTools

doc/quickstart.md

+# Hardware and software requirements
+
+You need virtual machine with following minimal configuration:
+* CPU: 8 cores
+* Memory: 32GB
+* Disk: 40GB 
+
+Software requirements are following:
+* Minimal installation of CentOS7
+* Set hostname for your Virtual Machine and create corresponding DNS record (will be needed later)
+* Install Ansible
+  * `sudo yum -y install epel-release`
+  * `sudo yum -y install ansible git`
+  * `sudo ansible-galaxy collection install ansible.posix`
+
+
+# Download SOCTools and prepare installation configuration 
+
+Download the current version using:
+
+`git clone https://gitlab.geant.org/gn4-3-wp8-t3.1-soc/soctools.git`
+
+`cd soctools`
+
+The configuration script will guide you through the quick start process
+
+`./configure.sh`
+
+First you need to fill in configuration file `access.ips`, which contains IP addresses and Networks that will be used to build access lists for services accessible from outside.
+
+- If you want to skip over access list creation process and use default access list, on "Do you want to modify/edit this file now?", press [Enter] or type no and press [Enter]
+
+Next, we are going to set Fully Qualified Domain Name for your SOCTools server.
+
+- On "set FQDN which will be used to access the soctools services. (the DNS record should already be in place.)" you should already have set up hostname and DNS record, so type it here and press [Enter]
+
+We also need the name of your chosen domain in the last step.
+
+- On "Organization's top level domain (will be used as organization name and organization domain in different services)", type the name of the domain used for hosting FQDN entered in the previous step and press [Enter]
+
+Following questions help us prepare your username and certificates that will be used to access various Tools in SOCTools. It also configures these parameters in `group_vars/all/variables.yml`.
+
+- On "firstame:" type your name and press [Enter]
+- On "lastname:" type your surname and press [Enter]
+- On "username:" type the username you want to use and press [Enter]
+- On "Enter CN for Certificate [username]:" press [Enter]
+- On "Correct? type 'yes' or 'no':", type yes and press [Enter]
+
+After entering 'yes' and pressing [Enter], following files and folders will be modified:
+
+- `access.ips`
+- `group_vars/all/variables.yml`
+- `roles/haproxy/files/`
+
+Also, firstame, lastname, and username will be used in the future step, while building CA and certificates for user access
+
+
+
+
+# Install and try SOCTools
+
+Following commands will let you configure the host, build docker images and build CA for service and user certificates:
+
+* `ansible-playbook -i inventories soctools_server.yml`
+* `ansible-playbook -i inventories buildimages.yml`
+* `ansible-playbook -i inventories buildca.yml`
+
+This playbook will generate some errors but this is normal as long as the playbook ignores them and finish without stopping. After the last step you can download and install certificates, doing following steps:
+* Download and import the root certificate located in secrets/CA/ca.crt (On windows the CA certificate should be installed in the Trusted Root Certficiation Authorities store)
+* Download and import in the browseer user certificate (for the user you have created) found in the directory secrets/certificates. To import user certificate, you will need password find in the directory secrets/passwords
+
+At last you can start SOCTools containers and initialize them using you configuration:
+
+* `ansible-playbook -i inventories soctools.yml -t start-docker-containers`
+* `ansible-playbook -i inventories soctools.yml -t init`
+
+After the whole process is finished, SOCTools can be accessed by going to https://<server name>:<port>/ using the following port numbers:
+
+* 9443 - NiFi
+* 5601 - Kibana
+* 6443 - Misp
+* 9000 - The Hive
+* 9001 - Cortex
+* 12443 - Keycloak