vagrant.md 4.09 KB
Newer Older
1 2 3
# Vagrant SOCI

[Vagrant](https://www.vagrantup.com/) used to build and provision
4
virtual environments for **hassle-free** SOCI development.
5 6 7 8

## Features

* Ubuntu 14.04 (Trusty) virtual machine
9
* Multi-machine set-up with three VMs: `soci`, `oracle`, `db2`.
10
* Support networking between the configured machines.
11
* `soci.vm`:
12
  * hostname: `vmsoci.local`
13
  * build essentials
14
  * core dependencies
15 16 17 18
  * backend dependencies
  * FOSS databases installed with sample `soci` user and instance pre-configured
  * during provision, automatically clones and builds SOCI from `master` branch.
* `db2.vm`:
19
  * hostname: `vmdb2.local`
20
  * IBM DB2 Express-C 9.7 installed from [archive.canonical.com](http://archive.canonical.com) packages.
21 22 23 24
* `oracle.vm`:
    * *TODO*: provision with Oracle XE
* SOCI local git repository (aka `$SOCI_HOME`) is automatically shared on host
  and all guest machines.
25 26 27 28 29 30 31 32 33 34 35 36 37

## Prerequisites

* Speedy broadband, time and coffee.
* Recommended 4GB or much more RAM (tested with 16GB only).

### SOCI DB2 backend

The `soci.vm` will be configured properly to build the DB2 backend only if
it is provisioned with complete DB2 CLI client (libraries and headers).
You need to download "IBM Data Server Driver Package (DS Driver)" manually
and make it visible to Vagrant:

38 39 40
1. Go to [IBM Data Server Client Packages](http://www-01.ibm.com/support/docview.wss?uid=swg21385217).
2. Download "IBM Data Server Driver Package (DS Driver)".
3. Copy the package to `${SOCI_HOME}/tmp` directory, on host machine.
41 42 43

## Usage

44 45
Below, simple and easy development workflow with Vagrant is outlined:

46
* [Boot](https://docs.vagrantup.com/v2/getting-started/up.html)
47 48

```console
49 50
vagrant up
```
51

52
or boot VMs selectively:
53 54

```console
55
vagrant up {soci|db2}
56
```
57

58 59
First time you run it, be patient as Vagrant downloads VM box and
provisions it installing all the necessary packages.
60 61

* You can SSH into the machine
62 63

```console
64
vagrant ssh {soci|db2}
65 66
```

67 68 69
* Run git commands can either from host or VM `soci` (once connected via SSH)

```console
70
cd /vagrant # aka $SOCI_HOME
71 72
git pull origin master
```
73 74 75 76 77

* You can edit source code on both, on host or VM `soci`.
* For example, edit in your favourite editor on host machine, then build, run, test and debug on guest machine from command line.
* Alternatively, edit and build on host machine using your favourite IDE, then test and debug connecting to DBs on guest machines via network.

78
* Build on VM `soci`
79 80

```console
81 82 83 84 85
vagrant ssh soci
cd /vagrant    # aka $SOCI_HOME
cd soci-build  # aka $SOCI_BUILD
make
```
86

87
You can also execute the `build.h` script provided to run CMake and make
88 89

```console
90 91
vagrant ssh soci
cd $SOCI_BUILD
92
/vagrant/scripts/vagrant/build.sh
93
```
94 95

* Debug, only on VM `soci`, for example, with gdb or remotely Visual Studio 2017.
96 97

* [Teardown](https://docs.vagrantup.com/v2/getting-started/teardown.html)
98 99

```console
100
vagrant {suspend|halt|destroy} {soci|db2}
101 102
```

103
Check Vagrant [command-line interface](https://docs.vagrantup.com/v2/cli/index.html) for complete list of commands.
104 105 106

### Environment variables

107
All variables available to the `vagrant` user on the VMs are defined in and sourced from `/vagrant/scripts/vagrant/common.env`:
108

109 110 111
* `SOCI_HOME` where SOCI master is cloned (`/vagrant` on VM `soci`)
* `SOCI_BUILD` where CMake generates build configuration (`/home/vagrant/soci-build` on VM `soci`)
* `SOCI_HOST` network accessible VM `soci` hostname (`ping vmsoci.local`)
112 113 114
* `SOCI_USER` default database user and database name
* `SOCI_PASS` default database password for both, `SOCI_USER` and root/sysdba
  of particular database.
115 116 117
* `SOCI_DB2_HOST` network accessible VM `db2` hostname (`ping vmdb2.local`)
* `SOCI_DB2_USER` admin username to DB2 instance.
* `SOCI_DB2_USER` admin password to DB2 instance.
118 119 120 121 122 123

Note, those variables are also used by provision scripts to set up databases.

## Troubleshooting

* Analyze `vagrant up` output.
124 125
* On Windows, prefer `vagrant ssh` from inside MinGW Shell where  `ssh.exe` is available or learn how to use Vagrant with PuTTY.
* If you modify any of `scripts/vagrant/*.sh` scripts, **ensure** they have unified end-of-line characters to `LF` only. Otherwise, provisioning steps may fail.