This repository is responsible for installing and configuring the VisAnalyticsKit (VAK) StateLogger Backend. It provisions a multi tier environment, with different stages.
In detail it installs couchbase-server and the acompaning sync_gateway to be able to send logs from any mobile device to a remote location. An overview can be seen in the following figure:
Each of these components ships (Couchbase Server and Sync Gateway) in a docker container. The components are orchestrated through docker-compose and are by default configured to communicatie with each other.
Tested on OSX 10.11 and macOS 10.12.
If you are on OS X / macOS you probably have homebrew installed, if not you are definitely missing out, so be sure to have it ready. Also to be able to use the local development environment this tool relies on the availabilty of vagrant and virtualbox or any other provider that is supported by vagrant. A list of providers can be found in the vagrant documentation.
One can install vagrant, virtualbox and lots of other tools via brew-cask, so be sure to have that installed as well.
To ease the usage of the backend component in the local environment, where you usually don't have a DNS-server running, I suggest installing the vagrant plugin hostsupdater. The plugin takes care of adding and removing your project hostname defined in the Vagrantfile to '/etc/hosts' on vagrant up and vagrant destroy. It only adds the entry on the initial vagrant up. Because we are editing a system file you have to have sudo privileges.
(OSX specific) The following commands can be used to prepare your local machine:
Preparations
# GET CASK
brew install caskroom/cask/brew-cask
# GET vagrant and virtualbox
brew cask install vagrant virtualbox
# if you have another virtualization platform installed and would rather use that instead please check if vagrant supports said platform.
# eventually you'll need to add the platform to the vagrant file. currently only virtualbox and parallels are supported.
# if you for example chose the "parallels"-platform make sure to install the "vagrant-parallels" plugin
# vagrant plugin install vagrant-parallels
# Optionally install vagrant hostsupdater
vagrant plugin install vagrant-hostsupdater
# install ansible
brew install ansible
# add a ssh key to ~/.ssh
ssh-keygen -t rsa -b 4096 -C 'vak-statelogger-backend' -f ~/.ssh/vagrant_ssh
# Add the following to your ssh-config located at ~/.ssh/config which creates a ssh configuration entry.
# for better readability the follwing is just appended to ~/.ssh/config file
#
# Host vak.telemetry.dev
# Hostname 192.168.34.11
# Identityfile ~/.ssh/vagrant_rsa
# StrictHostKeyChecking no
# User root
# LogLevel ERROR
echo 'Host vak.telemetry.dev\n\tHostname 192.168.34.11\n\tIdentityfile ~/.ssh/vagrant_rsa\n\tStrictHostKeyChecking no\n\tUser root\n\tLogLevel ERROR \n\n' >> ~/.ssh/config
Installation
The tool is kind of opinionated about how to use vagrant. So in general one would just vagrant up and if one needed to get onto the vagrant machine just use vagrant ssh. That way is also obviously working in this environment but is strongly discouraged.
There is also no provisioning on vagrant up. I chose it to be that way because my different environments should all resemble the production environment as much as possible. The advantage of this is that the deploy/orchestration/provisioning scripts are thoroughly tested - currently not in a repeatable way through tools like serverspec, test-kitchen or alike - but by intense work and sweat :]. Therefore the deployment to the different stages should be fairly easy and straight forward.
This is by nomeans trying to be a full documentation for vagrant but one needs to know the basic commands provided. For the full documentation either enter vagrant --help or visit the command line documentation.
The commands most often needed are the follwing:
- vagrant up => starts a virtualmachine defined by a corresponding Vagrantfile
- vagrant reload => reloads the virtualmachine
- vagrant suspend => suspend state of the machine, keeps everything saved, like hibernate
- vagrant destroy => destroys the machine, great if you want to start over
Starting vagrant
# change to the working directory where you cloned or copied this repository
cd /path/to/this-repository
# add an Ubuntu base box (Trusty x64)
# that might take a while, because you are downloading the image
vagrant box add ubuntu/trusty64
# optinonal add another base box
# for example the openSUSE-13.2 image from webhippie
# again this takes some time
# vagrant box add webhippie/opensuse-13.2
# you can also set the VAK_PROVIDER environment variable to 'parallels' to use that virtualization provider
# when the boxes have finished downloading `vagrant up` will start a virtualmachine with ubuntu/trusty64
# optional: `box_type=opensuse vagrant up` will boot a virtualmachine with opensuse-13.2
# remark: sadly this only works on the initial vagrant up : `[
vagrant up
# if you have chosen to install the hostsupdater plugin you will now be asked to enter your password.
#
# when the command ran successfully you should be able to ssh into it by just entering
ssh vak.telemetry.dev
# welcome to you newly created virtualmachine :]Now you are good to go and provision your machine like you would with any other remote machine.
Provision and orchestrate the backend
# change to the ansible folder
cd ./data/ansible
# we are assuming the single host vagrant environment
# all the necessary dependent roles are located in the "roles"-folder.
# if you are ready to provison your machine enter this cmd:
ansible-playbook install.yml
# the command will take some time to finish, so why not fetch a nice
# hot beverage of choice? :)
# for another environment like the staging server call the following command:
# ansible-playbook install.yml -i env/staging --ask-become-pass
# you will be prompted to enter a sudo password so, that ansible is able to provision the machine
When everything went well you can now visit your newly installed couchbase server and your sync_gateway.
The default location of the couchbase-server is http://vak.telemetry.dev:8091
To login into the server you need to enter the follwing credentials:
- user: desmond
- password: secret_password
The following depicts a session view:
function (doc, meta) {
if(doc.type && doc.type === 'session') {
emit(doc.entityId, [doc.alias, doc.startTimestamp]);
}
}Make sure to select "descending" in the filter results.
The default location of the sync_gateway is http://vak.telemetry.dev:4985.
The sync gateway also sets a user and password:
- user: hurley
- password: secret_password
It's also possible to disable the GUEST user by specifing sync_gateway_config_disable_guest: "true".
The complete configuration keys and their corresponding values can be scrutinzed here.
To visualize the data we added a simple nodejs app. It's available at http://vak.telemetry.dev:3000.