wqwVHSp6

1:toc: preamble
2:toclevels: 4
3
4= Vouchery Internal Documentation
5
6:author: Kjell Morgenstern
7{author} https://circleci.com/gh/KjellMorgenstern/vouchery[image:https://circleci.com/gh/KjellMorgenstern/vouchery.svg?style=svg&circle-token=7b3cf46c2f76dffab72e25060731e81db8260ec0[CircleCI status]]
8
9== Monitoring
10
11* Statuscake.com
12* Rollbar.com
13* UptimeRobot.com
14
15== User Documentation
16
17The API documentation is at https://staging.vouchery.io/documentation. It is updated automatically on deployment. +
18A README.io based version of the API documentation is at
19https://docs.vouchery.io.
20
21== Dependencies
22This project uses
23
24* rbenv
25* Ruby >= 2.4.1
26* Rails >= 5.1.3
27* Postgresql + Postgis
28* Minitest
29* Capybara
30* Capistrano
31* Brakeman
32* Rubocop
33* Guard (optional)
34* Capistrano 3
35
36
37== Development
38
39Use the usual rails commands to fire up everything.
40
41=== OS X dev environment
42
43To setup a basic development environment for MacOS, use brew.
44
45[source,bash]
46----
47brew install chromedriver
48brew install rbenv ruby-build
49brew install postgresql
50brew install postgis
51rbenv install 2.4.1
52bundle install
53----
54
55=== Starting the server 
56
57Make sure postgres is running:
58[source,bash]
59----
60pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log start
61----
62
63To connect to the database in development environment, set the
64PGUSER variable (e.g in your .bashrc), and allow password-less login for that user.
65
66And setup the local project:
67[source,bash]
68----
69bundle exec rails db:create
70bundle exec rails db:schema:load
71bundle exec assets:precompile
72bundle exec rails test:prepare
73----
74
75And fire it up:
76[source,bash]
77----
78bundle exec rails s
79----
80
81== Tests
82
83Tests are ecuted on CircleCI. You can basically see (and modify) the calls which are executed on CircleCI in the ./circlci/config.yml file.
84
85You can als run tests locally. Chrome >= 62 is needed for some of the tests.
86
87[source,bash]
88----
89bundle exec rails test
90----
91
92It is also possible to execute a single test.
93[source, bash]
94----
95# Excute only the test "should show campaign"
96bundle exec rails -n test_should_show_campaign
97----
98This 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.
99
100== Deployment
101
102Deployment is automated with Capistrano3. +
103TLS certificatas are automated with Capistrano3.
104Chef for installing packages is not yet set up.
105
106=== Chef
107
108We plan to use Chef for preparing the server. Until then, it is recommended to install the following packages (Ubuntu 16.04)
109
110==== Packages
111
112[source,bash]
113----
114curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
115echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
116curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
117apt-get update
118apt-get upgrade
119apt-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
120----
121
122=== rbenv
123
124To setup rbenv
125
126[source,bash]
127----
128git clone https://github.com/rbenv/rbenv.git ~/.rbenv
129git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
130echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
131source ~/.bashrc
132echo 'eval "$(rbenv init -)"' >> ~/.bashrc
133source ~/.bashrc
134git clone https://github.com/tpope/rbenv-aliases.git ~/.rbenv/plugins/rbenv-aliases
135rbenv alias --auto
136git clone https://github.com/rbenv/rbenv-default-gems.git ~/.rbenv/plugins/rbenv-default-gems
137rbenv install 2.4.1
138rbenv global 2.4.1
139gem install bundler
140----
141
142=== TLS
143
144Without a certificate file, nginx will not start https service, or even not start at all!
145
146[source,bash]
147----
148 sudo apt-get install software-properties-common
149 sudo add-apt-repository ppa:certbot/certbot
150 sudo apt-get update
151 sudo apt-get install python-certbot-nginx
152----
153
154Certificates can be created / renewed with capistrano:
155
156[source,bash]
157----
158bundle exec cap production security:certbot_create
159----
160
161[source,bash]
162----
163bundle exec cap production security:certbot_renew
164----
165
166Note: a cron job to renew certs on the servers was not yet created.
167First, establishing the cron job should be part of a chef recipe.
168Second, the renewal process (and the whole certificate generation) is
169not yet validated / still changing to often.
170
171=== Firewall
172On AWS EC2 use instance manager to allow access.
173
174Configuration on the server can be done with 'ufw'.
175
176Some commands:
177[source, bash]
178----
179ufw app list
180ufw allow ssh
181
182iptables --list
183iptables -L
184
185# See who us currently banned
186fail2ban-client status
187jail.local
188
189# Manually unban an IP, 
190fail2ban-client set ssh unbanip a.b.c.d
191
192tail -f -n40 /var/log/auth.log
193
194# For debugging ip tables rules
195iptables -L -v  # Show hits
196iptables -t raw -A PREROUTING -p tcp --dport 3205 -j TRACE   # Trace packages on port 3205
197sudo iptables -L -v -t raw  # Show hits on "TRACE"
198----
199
200
201=== PostGIS
202
203Opinions on the internet differ wether PostGIS is part of the environment
204(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. +
205Login as postgres user is required to modify the extension. First,
206create the extension in the shared_extension schema
207
208[source,psql]
209----
210create extension postgis with schema shared_extensions;
211----
212
213In case the extension already exists (and is in the public schema), the
214extension can be altered:
215
216[source,psql]
217----
218alter extension postgis set schema shared_extensions;
219----
220
221Test if the postgis extension is installed correctly.
222This should not work
223
224[source,psql]
225----
226# Within the public schema, call
227create table "test123" ("pos" geography(POINT, 4326));
228----
229
230But this should work
231
232[source,psql]
233----
234# Within the public schema, call
235create schema bla;
236set search_path = bla, shared_extensions;
237create table "test123" ("pos" geography(POINT, 4326));
238----
239
240Cleanup
241
242Drop the table that we created in the 'bla' schema.
243[source,psql]
244----
245drop table "test123";
246----
247
248=== Capistrano
249
250We 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 
251a ssh keypair on the server, and add the public key to the vouchery deployment keys on github.
252
253==== First time deployment
254
255When deploying to a server for the first time, run
256
257[source,bash]
258----
259bundle exec cap <target> setup
260----
261
262where <target> is either `staging` or `production`.
263
264==== Staging
265
266To deploy to staging
267
268[source,bash]
269----
270bundle exec cap staging deploy
271----
272
273==== Production
274
275To deploy to production
276
277[source,bash]
278----
279bundle exec cap production deploy
280----
281
282Sometimes, puma does not restart properly after deployment. This shows
283as 502 error on the deployment site. In that case e.g. for production,
284run
285
286[source,bash]
287----
288bundle exec cap production puma:restart
289----
290
291When deploying to production, always manually check for success 1. Go to
292main page demo.vouchery.io 2. Login 3. Open one campaign from list
293
294=== Documentation
295
296If you want to update the documentation, use the `swagger` targets.
297[source,bash]
298----
299bundle exec rails swagger:raw
300----
301
302Don't forget to add the new documentation `git add -u app/views/pages'.
303
304== Keys
305
306The rollbar API key is stored in the file `rollbar.rb`.
307The google API key is stored in the file `app/views/areas/index.html.erb` and `app/views/layouts/_minimal.html.erb`.
308
309=== Adding new users
310
311Adding new users is currently intentionally disabled in the fronted.
312To add a new user on staging, use the rails console.
313
314[source,bash]
315----
316RAILS.env=staging bundle exec rails console
317----
318
319[source,rails]
320----
321my_new_user = User.new(name:"NewUser", password:"NewPassword")
322my_new_user.save
323----
324
325Login with that NewUser.
326Add the users desired subdomain to vouchery.io.
327Create a project with that new user.
328
329Note: Using multiple users from one desktop at a time is not supported. This means you have
330to 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).