:toc: preamble
:toclevels: 4

= Vouchery Internal Documentation

:author: Kjell Morgenstern
{author} https://circleci.com/gh/KjellMorgenstern/vouchery[image:https://circleci.com/gh/KjellMorgenstern/vouchery.svg?style=svg&circle-token=7b3cf46c2f76dffab72e25060731e81db8260ec0[CircleCI status]]

== Monitoring

* Statuscake.com
* Rollbar.com
* UptimeRobot.com

== User Documentation

The API documentation is at https://staging.vouchery.io/documentation. It is updated automatically on deployment. +
A README.io based version of the API documentation is at
https://docs.vouchery.io.

== Dependencies
This project uses

* rbenv
* Ruby >= 2.4.1
* Rails >= 5.1.3
* Postgresql + Postgis
* Minitest
* Capybara
* Capistrano
* Brakeman
* Rubocop
* Guard (optional)
* Capistrano 3


== Development

Use the usual rails commands to fire up everything.

=== OS X dev environment

To setup a basic development environment for MacOS, use brew.

[source,bash]
----
brew install chromedriver
brew install rbenv ruby-build
brew install postgresql
brew install postgis
rbenv install 2.4.1
bundle install
----

=== Starting the server

Make sure postgres is running:
[source,bash]
----
pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log start
----

To connect to the database in development environment, set the
PGUSER variable (e.g in your .bashrc), and allow password-less login for that user.

And setup the local project:
[source,bash]
----
bundle exec rails db:create
bundle exec rails db:schema:load
bundle exec assets:precompile
bundle exec rails test:prepare
----

And fire it up:
[source,bash]
----
bundle exec rails s
----

== Tests

Tests are ecuted on CircleCI. You can basically see (and modify) the calls which are executed on CircleCI in the ./circlci/config.yml file.

You can als run tests locally. Chrome >= 62 is needed for some of the tests.

[source,bash]
----
bundle exec rails test
----

It is also possible to execute a single test.
[source, bash]
----
# Excute only the test "should show campaign"
bundle exec rails -n test_should_show_campaign
----
This is also possible by giving a filename and line number. Nice: The "RubyTest" plugin for Sublime Text supports calling the test which is under your curser.

== Deployment

Deployment is automated with Capistrano3. +
TLS certificatas are automated with Capistrano3.
Chef for installing packages is not yet set up.

=== Chef

We plan to use Chef for preparing the server. Until then, it is recommended to install the following packages (Ubuntu 16.04)

==== Packages

[source,bash]
----
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
apt-get update
apt-get upgrade
apt-get install postgresql postgis nginx git autoconf bison build-essential libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm3 libgdbm-dev libpq-dev nodejs fail2ban yarn nodejs
----

=== rbenv

To setup rbenv

[source,bash]
----
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc
git clone https://github.com/tpope/rbenv-aliases.git ~/.rbenv/plugins/rbenv-aliases
rbenv alias --auto
git clone https://github.com/rbenv/rbenv-default-gems.git ~/.rbenv/plugins/rbenv-default-gems
rbenv install 2.4.1
rbenv global 2.4.1
gem install bundler
----

=== TLS

Without a certificate file, nginx will not start https service, or even not start at all!

[source,bash]
----
 sudo apt-get install software-properties-common
 sudo add-apt-repository ppa:certbot/certbot
 sudo apt-get update
 sudo apt-get install python-certbot-nginx
----

Certificates can be created / renewed with capistrano:

[source,bash]
----
bundle exec cap production security:certbot_create
----

[source,bash]
----
bundle exec cap production security:certbot_renew
----

Note: a cron job to renew certs on the servers was not yet created.
First, establishing the cron job should be part of a chef recipe.
Second, the renewal process (and the whole certificate generation) is
not yet validated / still changing to often.

=== Firewall
On AWS EC2 use instance manager to allow access.

Configuration on the server can be done with 'ufw'.

Some commands:
[source, bash]
----
ufw app list
ufw allow ssh

iptables --list
iptables -L

# See who us currently banned
fail2ban-client status
jail.local

# Manually unban an IP,
fail2ban-client set ssh unbanip a.b.c.d

tail -f -n40 /var/log/auth.log

# For debugging ip tables rules
iptables -L -v  # Show hits
iptables -t raw -A PREROUTING -p tcp --dport 3205 -j TRACE   # Trace packages on port 3205
sudo iptables -L -v -t raw  # Show hits on "TRACE"
----


=== PostGIS

Opinions on the internet differ wether PostGIS is part of the environment
(should be setup with chef) or if it is part of the database (and thus is a job for capistrano). We made an effort to deploy with capistrano. In case it does not work, the following manual steps might be required. +
Login as postgres user is required to modify the extension. First,
create the extension in the shared_extension schema

[source,psql]
----
create extension postgis with schema shared_extensions;
----

In case the extension already exists (and is in the public schema), the
extension can be altered:

[source,psql]
----
alter extension postgis set schema shared_extensions;
----

Test if the postgis extension is installed correctly.
This should not work

[source,psql]
----
# Within the public schema, call
create table "test123" ("pos" geography(POINT, 4326));
----

But this should work

[source,psql]
----
# Within the public schema, call
create schema bla;
set search_path = bla, shared_extensions;
create table "test123" ("pos" geography(POINT, 4326));
----

Cleanup

Drop the table that we created in the 'bla' schema.
[source,psql]
----
drop table "test123";
----

=== Capistrano

We use capistrano3 to deploy updates and manage clients. This includes calling yarn to build the frontend. Capistrano will read directly from github. Therefore, it is required that you create
a ssh keypair on the server, and add the public key to the vouchery deployment keys on github.

==== First time deployment

When deploying to a server for the first time, run

[source,bash]
----
bundle exec cap <target> setup
----

where <target> is either `staging` or `production`.

==== Staging

To deploy to staging

[source,bash]
----
bundle exec cap staging deploy
----

==== Production

To deploy to production

[source,bash]
----
bundle exec cap production deploy
----

Sometimes, puma does not restart properly after deployment. This shows
as 502 error on the deployment site. In that case e.g. for production,
run

[source,bash]
----
bundle exec cap production puma:restart
----

When deploying to production, always manually check for success 1. Go to
main page demo.vouchery.io 2. Login 3. Open one campaign from list

=== Documentation

If you want to update the documentation, use the `swagger` targets.
[source,bash]
----
bundle exec rails swagger:raw
----

Don't forget to add the new documentation `git add -u app/views/pages'.

== Keys

The rollbar API key is stored in the file `rollbar.rb`.
The google API key is stored in the file `app/views/areas/index.html.erb` and `app/views/layouts/_minimal.html.erb`.

=== Adding new users

Adding new users is currently intentionally disabled in the fronted.
To add a new user on staging, use the rails console.

[source,bash]
----
RAILS.env=staging bundle exec rails console
----

[source,rails]
----
my_new_user = User.new(name:"NewUser", password:"NewPassword")
my_new_user.save
----

Login with that NewUser.
Add the users desired subdomain to vouchery.io.
Create a project with that new user.

Note: Using multiple users from one desktop at a time is not supported. This means you have
to logout manually before a login with a differnt user (TODO: automatically close the previous session during login, there is a low priority ticket for that if I remember correct).