.gitignore

+# Compiled book
+/_book/
+
+# Build deps
+/node_modules/

.gitlab-ci.yml

+# requiring the environment of NodeJS 10
+image: node:10
+
+# add 'node_modules' to cache for speeding up builds
+cache:
+  paths:
+    - node_modules/ # Node modules and dependencies
+
+before_script:
+  - npm install gitbook-cli -g # install gitbook
+  - gitbook fetch 3.2.3 # fetch final stable version
+  - gitbook install # add any requested plugins in book.json
+    
+# the 'pages' job will deploy and build your site to the 'public' path
+pages:
+  stage: deploy
+  script:
+    - gitbook build . public # build to public path
+  artifacts:
+    paths:
+      - public
+    expire_in: 1 week
+  only:
+    - master # this job will affect only the 'master' branch

0-quickstart/README.md

+# Quickstart
+
+Quickstart is intended for users that want to spin up a virtual machine instance in the cloud as quickly as possible.
+
+To create a virtual machine instance, you need to
+* sign in via the MetaCentrum cloud web interface,
+* create an *ssh* key pair or use an existing key pair,
+* set up or update a security group,
+* start a virtual machine instance,
+* log in to the running instance using *ssh* (secure shell).
+
+## Sign In
+The web interface is available at [https://cloud.muni.cz](https://cloud.muni.cz).
+
+To sign in,
+* select `ENIFRA CESNET`,
+* click on `Sign In`,
+* select your institution from the drop-down list (use the search box at the top as a filter),
+* provide your institution-specific sign-in credentials,
+* wait to be redirected back to our web interface.
+
+## Create Key Pair
+All virtual machine instances running in the cloud have to be accessed remotely. The most common way of accessing a virtual machine instance remotely is the secure shell - *ssh*. Using *ssh* requires a pair of cryptographic keys.
+
+1. To create a new *ssh* key pair, go to **Project > Compute > Key Pairs** and click the button "Create Key Pair"
+{% reveal text="Show Screenshot" %}
+  ![](/0-quickstart/CreateKeyPair1.png)
+{% endreveal %}
+2. Name your new key and click on "Create Key Pair" again. Avoid using special characters, if possible.
+{% reveal text="Show Screenshot" %}
+  ![](/0-quickstart/CreateKeyPair2.png)
+{% endreveal %}
+3. You can see your newly created key pair and its fingerprint. We recommend you store the key in a safe location and back it up in case you accidentally delete it.
+{% reveal text="Show Screenshot" %}
+  ![](/0-quickstart/CreateKeyPair3.png)
+{% endreveal %}
+
+## Update Security Group
+In OpenStack, all incoming traffic from external networks to virtual machine instances is blocked by default. You need to explicitly allow access to individual virtual machine instances and services via a security group.
+
+You need to add two new rules to be able to connect to your new instance (or any instance using the given security group). This is similar to setting up firewall rules on your router or server. If set up correctly, you will be able to access your virtual machine via *ssh* from your local terminal.
+
+1. Go to **Project >  Network > Security Groups**. Here you can see the default security group. You can either edit the default group by clicking on "Manage Rules" or create a new one. The simplest way is to edit the default group.
+{% reveal text="Show Screenshot" %}
+  ![](/0-quickstart/SecurityGroups1.png)
+{% endreveal %}
+2. Click on "Add rule", choose "SSH" and leave the remaining fields unchanged. This will allow you to access your instance.
+{% reveal text="Show Screenshot" %}
+  ![](/0-quickstart/SecurityGroups2.png)
+{% endreveal %}
+3. Click on "Add rule", choose "ALL ICMP" and leave the remaining fields unchanged. This will allow you to `ping` your instance.
+{% reveal text="Show Screenshot" %}
+  ![](/0-quickstart/SecurityGroups3.png)
+{% endreveal %}
+
+## Start Instance
+1. Navigate to **Quickstart** and click on "Launch Instance".
+{% reveal text="Show Screenshot" %}
+  ![](/0-quickstart/qs1.png)
+{% endreveal %}
+2. Choose a name for your virtual machine.
+{% reveal text="Show Screenshot" %}
+  ![](/0-quickstart/qs3-1.png)
+{% endreveal %}
+3. Choose an Operating System to run on your instance, also known as an **Image**.
+{% reveal text="Show Screenshot" %}
+  ![](/0-quickstart/qs3-2.png)
+{% endreveal %}
+4. Choose a suitable size of the new instance, also known as a **Flavor**.
+{% reveal text="Show Screenshot" %}
+  ![](/0-quickstart/qs3-3.png)
+{% endreveal %}
+5. Select the previously created *ssh* key pair by name.
+{% reveal text="Show Screenshot" %}
+  ![](/0-quickstart/qs3-4.png)
+{% endreveal %}
+6. Click on "Launch instance" and wait until **Quickstart** provides you with information about the running virtual machine instance.
+{% reveal text="Show Screenshot" %}
+  ![](/0-quickstart/qs4.png)
+{% endreveal %}
+7. *[Optionally]* Add a persistent volume to the running virtual machine instance.
+{% reveal text="Show Screenshot" %}
+  ![](/0-quickstart/qs5.png)
+{% endreveal %}
+8. Close the dialog with "Finish" to return to the list of active instances.
+{% reveal text="Show Screenshot" %}
+  ![](/0-quickstart/qs6.png)
+{% endreveal %}
+
+## Log In
+Follow instructions provided by **Quickstart** and log in remotely:
+> ssh -i ${PATH_TO_SSH_KEY_FILE} ${USER}@${IP_ADDRESS}

1-gui/README.md

+# Using OpenStack's Web Interface
+
+This introduction is intended for users that want to start a larger number of virtual machine instances in the cloud or use advanced features through the Graphical User Interface of OpenStack.
+
+The process is similar to creating a virtual machine instance in [Quickstart](/documentation/0-quickstart/), you need to
+* sign in via the MetaCentrum Cloud web interface,
+* create an *ssh* key pair or use an existing key pair,
+* create virtual private network,
+* create virtual router,
+* join virtual private network to internet through router interfaces,
+* set up or update a security group,
+* start a virtual machine instance,
+* allocate floating IP address (add or remove IP address to/from virtual machine instance)
+* log in to the running instance using *ssh* (secure shell),
+* (optional) create new volume (add/remove volume to/from virtual machine instance).
+
+## Sign In
+
+The web interface is available at [https://cloud.muni.cz](https://cloud.muni.cz).
+
+To sign in,
+* select `ENIFRA CESNET`,
+* click on `Sign In`,
+{% reveal text="Show Screenshot" %}
+  ![](/1-gui/sign_in1.png)
+{% endreveal %}
+* select your institution from the drop-down list (use the search box at the top as a filter),
+{% reveal text="Show Screenshot" %}
+  ![](/1-gui/sign_in2.png)
+{% endreveal %}
+* provide your institution-specific sign-in credentials,
+{% reveal text="Show Screenshot" %}
+  ![](/1-gui/sign_in3.png)
+{% endreveal %}
+* wait to be redirected back to our web interface.
+
+## Create Key Pair
+
+All virtual machine instances running in the cloud have to be accessed remotely. The most common way of accessing a virtual machine instance remotely is the secure shell - *ssh*. Using *ssh* requires a pair of cryptographic keys.
+
+1. To create a new *ssh* key pair, go to **Project > Compute > Key Pairs** and click the button "Create Key Pair"
+{% reveal text="Show Screenshot" %}
+  ![](/0-quickstart/CreateKeyPair1.png)
+{% endreveal %}
+
+2. Name your new key and click on "Create Key Pair" again. Avoid using special characters, if possible.
+{% reveal text="Show Screenshot" %}
+  ![](/0-quickstart/CreateKeyPair2.png)
+{% endreveal %}
+
+3. You can see your newly created key pair and its fingerprint. We recommend you store the key in a safe location and back it up in case you accidentally delete it.
+{% reveal text="Show Screenshot" %}
+  ![](/0-quickstart/CreateKeyPair3.png)
+{% endreveal %}
+
+## Create Network
+
+1. In **Project > Network > Network Topology** you can see the actual status of your networks. In the beginning there are only public networks visible, because you haven't created yet your network. You can do it by clicking on the button "Create Network". This network will serve as connection of your instances.
+{% reveal text="Show Screenshot" %}
+  ![](/1-gui/network1.png)
+{% endreveal %}
+
+2. Name the network, which will join your instances, and click "Next".
+{% reveal text="Show Screenshot" %}
+  ![](/1-gui/network2.png)
+{% endreveal %}
+
+3. In Subnet tab name your subnet and choose a range of valid IP addresses (e.g. 10.1.1.0/24 or whatever you wanti) in CIDR format. The gateway will be automatically added as default (in our example it would be 10.1.1.1). Click "Next".
+{% reveal text="Show Screenshot" %}
+  ![](/1-gui/network3.png)
+{% endreveal %}
+
+4. In Subnet Details tab in Allocation Pools you can choose what ranges will be served by DHCP server (what ranges will be automatically assigned if a machine will use DHCP server for joining a subnet). Use format in description (e.g. for range between 10.1.1.220 and 10.1.1.249 write: 10.1.1.220,10.1.1.249 - so limits separated by comma). You can leave default DNS servers. Click "Create".
+{% reveal text="Show Screenshot" %}
+  ![](/1-gui/network4.png)
+{% endreveal %}
+
+5. Now in **Project > Network > Network Topology** you should see the new network created by you.
+{% reveal text="Show Screenshot" %}
+  ![](/1-gui/network5.png)
+{% endreveal %}
+
+   Now you can continue by creating router.
+
+## Create Router
+
+1. In **Project > Network > Network Topology** or in **Project > Network > Routers** push the button "Create Router". This router will serve as connection between your subnet and public network.
+{% reveal text="Show Screenshot" %}
+  ![](/1-gui/router1.png)
+{% endreveal %}
+
+2. Add router name, select External Network (public network, through which you will be connected to internet) and click "Create Router". The router should be created and joined to public network.
+{% reveal text="Show Screenshot" %}
+  ![](/1-gui/router2.png)
+{% endreveal %}
+
+3. In **Project > Network > Network Topology** the router should be now visible.
+{% reveal text="Show Screenshot" %}
+  ![](/1-gui/router3.png)
+{% endreveal %}
+
+4. Now you can go to **Project > Network > Network Topology** and create interface for connection to your subnet. Pointing over the router icon you will get to information window, where is a button "Add Interface". Click on it.
+{% reveal text="Show Screenshot" %}
+  ![](/1-gui/router4.png)
+{% endreveal %}
+
+5. In opened pop-up window choose the available subnet. Click "Submit".
+{% reveal text="Show Screenshot" %}
+  ![](/1-gui/router5.png)
+{% endreveal %}
+
+6. In **Project > Network > Network Topology** you can now see your network joined to public network.
+{% reveal text="Show Screenshot" %}
+  ![](/1-gui/router6.png)
+{% endreveal %}
+
+## Create Virtual Machine Instance(s)
+
+The creation of virtual machine instances is very straight-forward:
+1. In **Compute > Instances** push the button "Launch Instance"
+{% reveal text="Show Screenshot" %}
+![](/1-gui/instance0.png)
+{% endreveal %}
+
+2. Choose Instance Name, (optionally) Description, Availability Zone and Count of instances, how many VMs you want to create. If you are creating more instances, the number in format '-X' will be added automatically to the Instance Name for each instance.
+{% reveal text="Show Screenshot" %}
+![](/1-gui/instance1.png)
+{% endreveal %}
+
+3. Choose the source of booting (you can boot your Instances from Image or a snapshot), Volume Size and from Available choose the desired image to boot from. According to the purpose of your project you can change these default settings Create New Volume and Delete Volume on Instance Delete (default "No"), if you want to use created volume and if you want to have not persistant volume.
+{% reveal text="Show Screenshot" %}
+![](/1-gui/instance2.png)
+{% endreveal %}
+
+4. Pick the flavour - size of Instances created: VCPUs, RAM, Total Disk (Root). There are a few possibilities to choose from. You can add [additional disk]() later.
+{% reveal text="Show Screenshot" %}
+![](/1-gui/instance3.png)
+{% endreveal %}
+
+5. Next you check if your Instances were added to network created earlier
+{% reveal text="Show Screenshot" %}
+![](/1-gui/instance4.png)
+{% endreveal %}
+
+6. (optional) Security Groups tab you can see to what security group instances will be added. Usually you would like to stick with default option. Click on "Next".
+{% reveal text="Show Screenshot" %}
+![](/1-gui/instance5.png)
+{% endreveal %}
+
+7. In Key Pair you need to add your earlier created public key. It will be added to authorized keys on instances and will allow you to ssh access to them from terminal/Putty or whatever you are using as ssh tool for connecting.
+{% reveal text="Show Screenshot" %}
+![](/1-gui/instance6.png)
+{% endreveal %}
+
+8. (optional) You can now go to Metadata (the left bottom tab) and choose the packages of software, which you want to have installed on your instances.
+{% reveal text="Show Screenshot" %}
+![](/1-gui/instance7.png)
+{% endreveal %}
+
+9. Then you can click on Launch Instance. After a few minutes they will be ready for using.
+{% reveal text="Show Screenshot" %}
+![](/1-gui/instance8.png)
+{% endreveal %}
+
+## Allocate and Associate a Floating IP (optional)
+
+Sometimes we want to have an instance accessible from public network. In OpenStack project you can do it easily from the menu for each instance in **Project > Compute > Instances** or you can manage them more conscious way with at first allocating and then associating of IP address with instance. (You can of course later disassociate IP address from instance or disallocate IP address from your pool, when you don't need it, or associate with another instance and so on.)
+
+1. Go to **Project > Network > Floating IPs** and click on "Allocate IP to Project"
+{% reveal text="Show Screenshot" %}
+![](/1-gui/allocate_IP0.png)
+{% endreveal %}
+
+2. In pop-up window choose from which public network (Pool) do you want to allocate IP address for your instance eventually what will be the name of IP address. You have to choose the public network, to which your network is connected to, otherwise it won't work. Click on "Allocate".
+{% reveal text="Show Screenshot" %}
+![](/1-gui/allocate_IP1.png)
+{% endreveal %}
+
+3. Now you should have IP address to your disposal.
+{% reveal text="Show Screenshot" %}
+![](/1-gui/allocate_IP2.png)
+{% endreveal %}
+
+4. The next step is associate the free IP address to an instance. Click on "Associate".
+{% reveal text="Show Screenshot" %}
+![](/1-gui/allocate_IP2a.png)
+{% endreveal %}
+
+5. Select IP address and Port to be associated and click on "Associate".
+{% reveal text="show screenshot" %}
+![](/1-gui/allocate_IP3.png)
+{% endreveal %}
+
+6. In **Project > Compute > Instances** you should be able to see instance with the associated public IP address.
+{% reveal text="show screenshot" %}
+![](/1-gui/allocate_IP4.png)
+{% endreveal %}
+
+## Create Volume
+> TODO