Prerequisites

Ruby 3.2.0 Rails 7.1.0

rbenv or rvm recommanded

Environment variables

Some environment variables are needed to run this application.

DATABASE_URL=postgres://<user>:<pass>@localhost:5432 # The database URL
HOST=entourage.localhost # The Host that is used in Nginx routing if multiple app exists behind the same port

You can source these environment variables from a .env file.

To get started : cp .env.dist .env and fill in the missing informations!

HMAC request signing (anti-bot)

Two variables protect the account creation endpoint (POST /api/v1/users) against bots. Each mobile app signs its requests with a shared secret; the backend verifies the signature.

Variable	Used by
HMAC_SECRET_ANDROID	Android app (BuildConfig.HMAC_SECRET)
HMAC_SECRET_IOS	iOS app (ApiKeys.plist → HmacSecret)

Generate a secret with:

ruby -e "require 'securerandom'; puts SecureRandom.hex(32)"

Deployment order:

1. Deploy the backend without setting these variables → the check is skipped (backwards-compatible).
2. Release the updated Android and iOS apps (they include the signing code).
3. Set HMAC_SECRET_ANDROID and HMAC_SECRET_IOS in the environment and restart the backend → the check activates for v9.0.0+ keys.

In development, leave both variables empty: requests are passed through without signature verification.

Note that the .env file is used for all Rails environments. If you want to target only one (e.g. the development environment but not the test environment), use a file named .env.{environment_name} (e.g .env.development).

You will find more informations about this in the dotenv gem's README.

Docker

You can run this application using Docker.

There is a wrapper, bin/d, that allows you to run command in the correct container.

Example :

bin/d # Shows help
bin/d up # Setup needed containers
# bin/d gem install bundler -v '2.2.16'
# bin/d bundle install
bin/d bundle exec rake db:migrate
bin/d foreman start web

You can run below commands prepending bin/d to them and it will run in the container !

Note: after modifying the Dockerfile, you might need to run

docker-compose -f docker-compose.yml -f docker-compose.dev.yml build spring

This commands mirrors what happens in bin/docker/up to build the dev variant of the Docker image. TODO: there has to be a simple way to do this. We should update the bin/docker/* script as needed or at least create one for this.

Docker - Tests

RAILS_ENV=test bin/d bundle exec rake db:drop db:create db:migrate
RAILS_ENV=test bin/d bundle exec rspec

Docker - Psql

If you want to connect directly to docker psql, use:

docker-compose exec --env RAILS_ENV=development postgresql psql postgres://guest:guest@postgresql:5432/entourage-dev

See docker-compose.yml for more details.

Local install

Resolve dependencies and database migration

gem install 'bundler:~>1'
bundle install
bundle exec rake db:create
bundle exec rake db:migrate # if any trouble with postgis, please see Postgis section below

Launch application

bundle exec rails server

Or, with foreman :

# gem install foreman
foreman start web

Running scheduled jobs

Scheduled jobs documentation is accessible here

Configure job worker

bundle exec sidekiq -c 5 -q mailers -q default -q broadcast -q denorm

Accessing admin panel

To access the admin panel, you need to set an entry in your /etc/hosts :

127.0.0.1 admin.entourage.localhost

You also need to create an admin user :

echo "UserServices::PublicUserBuilder.new(params: {phone: '+33606060606', admin: true}, community: Community.new(:entourage)).create(sms_code: '123456')" | rails c

Then, browse admin.entourage.localhost:<port>.

Rspec tests

Setup database :

rake db:drop db:create db:migrate RAILS_ENV=test

Run tests with

$ rspec

Database dump

Import a database dump

bin/d db-restore path/to/snapshot.dump

Generate a stripped database dump from production data

You need to have access to the entourage-back Heroku application.

bin/d db-pull entourage-back
bin/d rake db:strip
bin/d db-dump path/to/snapshot.dump

Postgis

If you have any trouble with postgis during db:migrate, please install postgis:

Using PSQL 12

sudo apt install postgis postgresql-12-postgis-3
sudo apt-get install postgresql-12-postgis-3-scripts

Using PSQL 11

sudo apt install postgis postgresql-11-postgis-3
sudo apt-get install postgresql-11-postgis-3-scripts

Then, activate postgis in your database (DO NOT INSTALL it in the database called postgres):

psql
\c entourage-dev
entourage-dev=# CREATE EXTENSION postgis;
entourage-dev=# SELECT PostGIS_version();

API documentation

1. open in a browser: public/doc/api/index.html
2. or open directly URL : https://admin.entourage.social/doc/api/index.html

Profiling

rbspy

To profile a request (in a puma worker):

bin/d -u root -- rbspy record --pid $(cat tmp/puma.pid) --subprocesses --file flamegraph

Dredd tests (Deprecated)

Test the API documentation compliance with Dredd

Install Dredd

$ npm install -g dredd

Setup database for Dredd tests:

• Reset DB to reset id sequence
• Populate database with Dredd specific seeds (cf file ./db/seeds/dredd.rb)

$ rake db:reset dredd:seeds

rake dredd:seeds task description:

• Removes all newsletter subscriptions
• Removes all users
• Generates the dredd user

Run Dredd

$ rake dredd

Dredd config

Dredd options are listed in dredd.yml file

Guard

Guard Rspec (default)

Launch automatically tests with:

$ bundle exec guard

Guard Api blueprint

Launch automatically dredd and aglio (static documentation generation) with:

$ bundle exec guard -g apib

Redirection to app stores :

In order to redirect a mobile to the application from a SMS, we redirect toward a page on the website :

http://api.entourage.social/store_redirection

• If you visit this page from an iOS device you will be redirected to the Appstore
• If you visit this page from an Android device you will be redirected to the PlayStore

The logic and URL for the store can be found here : https://s3-eu-west-1.amazonaws.com/entourage-ressources/store_redirection.html