README.md

   1 # Vagrant Sandboxes for OSM
   2
   3 Copyright 2020 Telefónica Investigación y Desarrollo S.A.U.
   4 Licensed under the Apache License, Version 2.0 (the "License");
   5 you may not use this file except in compliance with the License.
   6 You may obtain a copy of the License at
   7     http://www.apache.org/licenses/LICENSE-2.0
   8 Unless required by applicable law or agreed to in writing, software
   9 distributed under the License is distributed on an "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  11 See the License for the specific language governing permissions and
  12 limitations under the License.
  13
  14 ## Goal
  15
  16 The goal is adopting a methodology for local testing that is fully repeatable and well-known by the Depops MDL team in OSM.
  17
  18 This means that:
  19
  20 - Local testers should use (and rebuild regularly) the appropriate sandbox to perform tests and/or contributions to test plans, so that potential issues can be reliably diagnosed and solved.
  21 - This means that all known changes in the installation procedures of any sandbox will be captured in the companion "provisioner" script (typically, `provisioner.sh`), so that the exact procedure can be well-known and testable by everyone.
  22 - In case something that was known to work in a sandbox started to fail:
  23   - It should be reported as a bug if there were no further contributions to the sandbox, since it is likely to be a gap in the knowledge/testing of the corresponding provisioning procedure, that might have changed over time (e.g new dependencies, change of repositories, hardcoded locations, etc.)
  24   - In case new contributions (e.g. new tests, new patches, etc.) were not functional in the corresponding sandbox, the contributor should review them locally first, since they are likely to have issues.
  25
  26 ## Pre-requirements
  27
  28 - VirtualBox and Vagrant locally installed.
  29 - Host properly configured to use SSH and Git with OSM.
  30   - NOTE: In the case of a Windows host, this means:
  31     - Having your SSH keys (public and private in the `%userprofile%/.ssh` folder (the one equivalent to `~/.ssh` in Linux/Mac),
  32     - Having Git installed and properly configured in Windows, i.e. check that `%userprofile%/.gitconfig` exists and has the proper configuration.
  33       - In particular, it is required that the `user.name` there contains your EOL account name (i.e. avoid using a full name there). Beware that only the global profile is supported.
  34
  35 ## Basic use of Vagrant
  36
  37 To build a sandbox from scratch:
  38
  39 ```bash
  40 cd folder_of_the_sandbox
  41 vagrant up
  42 ```
  43
  44 NOTE: All the examples that follow are suppossed to be run in the same sandbox's folder.
  45
  46 To access the VM via SSH:
  47
  48 ```bash
  49 vagrant ssh
  50 ```
  51
  52 To destroy the VM:
  53
  54 ```bash
  55 vagrant destroy
  56 ```
  57
  58 To rebuild and reprovision the VM:
  59
  60 ```bash
  61 vagrant destroy && vagrant up
  62 ```