ViClarity

Getting Started

Prerequisites:

• dip (https://github.com/bibendi/dip)
• docker
• docker-compose

Installation:

1. Clone the repository

git clone ssh://[email protected]:7999/viclarity/viclaritysupport.git

2. Run provision script

dip provision

How it works?

You can find provision script test in dip.yml configuration file. It consists of several parts executed both on host machine and running docker container.

dip prepare is the only script is running on host machine. It creates .env file (if not created) and copies .env.example to it.

dip compose build is about building and fetching docker images

dip compose up -d postgres redis runs database dependencies required to application start

dip bash -c /bin/setup doing everything related to application start inside the container. Installing gems, updating database schema, etc...

docker-compose

If default setup doesn't work for you, feel free to use docker-compose.override.yml. Also, put changes (with comment) to git-tracked file from the repository.

This is the list of extra services needed for the development:

• worker - another application processes to run background tasks inside.
• mailhog - is an email testing tool for developers. Documentation.

Mailhog is serving at http://localhost:8025 by default

IDP SAML PROVIDER

---

We have a test saml idp image in our docker setup. It doesn't start automatically with rails project. To start it run docker-compose up dummy_idp. Copy env varialbes from example file to your local .env file. Don't forget to add dummy to OMNIAUTH_PROVIDERS list. Values hardcoded and depends on original test-saml-idp image. SP configuration is in /config/dummy_idp/saml20-sp-remote.php file.

More info about docker setup: https://hub.docker.com/r/kristophjunge/test-saml-idp/

SimpleSamlPHP documentation: https://simplesamlphp.org/docs/stable/index.html

There are two static users configured in the IdP with the following data:

UID	Username	Password	Group	Email
1	user1	user1pass	group1	[email protected]
2	user2	user2pass	group2	[email protected]

Admin password: secret

Environment

---

All available environment variables MUST be listed in .env.example file. If application requires some value for it, please add it with content. Don't put real credentials there. This file is required for CodeDeploy AWS scripts for all (staging/production) environments.

On real environments (staging/production/production_us), configuration loaded from .env file using dotenv tool.

If you need some change only in your local environment, make them in .env file.

Common issues

---

Issue with M1 Processors When Running the Application Locally

If you encounter the error Uncaught exception: cannot load such file -- google/protobuf_c while trying to run the application locally on M1 processors, you can resolve this issue by installing the gem in the console. To do this, run the following command: gem install --platform ruby google-protobuf -v 3.18.1 (or another actual protobuf gem version from the Gemfile)

Databases

---

Please note, application is connected with 2 different database. One database instance used locally, but not on AWS environemnts. The implementation has the same interfaces as in rails 6. RailsDoc lives there. The secondary database has prefix reports. If you want to run migrations, use command rake db:migrate:reports. The same rules for other commands.

Commands

---

Read dip documentation and dip.yml configuration before the start. All most popular commands should work.

dip rails s starts default rails server at http://localhost:3000

dip rspec runs all unit tests inside the new created web container

dip bash attaches new container session to your terimnal

dip

Dip can be injected into the current shell (ZSH or Bash).

eval "$(dip console)"

After that we can type commands without dip prefix

Contribution

---

New Pull Request

Create your new git branche based on default master branch. Once development done, create new pull request on bitbucket server. Please take care about automatical checks. Pull request MUST follow the template:

[VICLARITY-X][Y] Ticket Description

Where X is the ticket number from VICLARITY jira board. Y - ticket number from VICLARITYDEV board.

Staging release

Just merge your branch into the master one. We have CD setup.

Squash, fast-forward only merge option MUST be used there.

Production release

Before new production release PR with required changes should be created. Example of production relase pull request:

[RELEASE-YY-M-N] Description of the release.

YY, M - is the current year and month. N - is the sequential number of the release this month.

production is the target branch, CD should do deployment after merge. Default merge strategy must be used.

Mobile API

The Mobile API is written using the Grape gem. All endpoints are located in the public_api/api/v3 folder

In order to get all implemented routers, run the command rake grape:routes

Survey integration

• Run ViClarity application
• Authorize to main app as admin user. Make sure, that user has some company. That company should have survey_enabled flag set true. You can do it in rails console
• Go to the list of applications. There should be app named 'survey'. If there's none - create it. Specify Callback URL as following On app page you can get Application Id and Secret. Set them up to .env.development file in Survey app folder (as DOORKEEPER_APP_ID and DOORKEEPER_APP_SECRET variables respectively). By default, DOORKEEPER_APP_URL should point to the main Viclarity app (port 3001) DOORKEEPER_APP_REDIRECT should be equal to the callback url you have specified earlier
• Run the Survey app. Go to root page
• You will be redirected to url. Enter auth data for ViClarity user. After authentication you will be redirected back to Survey page