API

Development

System

If you’re using windows, it is better to use WSL so your development environment is similar to the production environment.

Development environment setup

You will have to use the bin/dev script, you might have to make it executable:

chmod +x bin/dev

You will be using the following commands:

bin/dev td   # testdiff - Test only the files that have been modified
bin/dev t    # test - Test all files or a specific file
bin/dev tdb  # testdb - Setup the test databases
bin/dev s    # server - Start the Rails server binding to 0.0.0.0
bin/dev c    # console - Start the Rails console
bin/dev u    # up - Install all required gems (bundle install)
bin/dev ce   # credentials:edit - Edit Rails credentials using VS Code
bin/dev l    # lint - Run RuboCop to auto-correct linting issues
bin/dev d    # doc - Generate YARD documentation and start the YARD server

Start python web server (needed for AI features)

You also have bin/dev script in the app/python dir where the python code lives.

  1. Create and activate a python virtual environment if you haven't already.

    python3 -m venv /rails/.venv

  2. Activate the python virtual environment.

    source /rails/.venv/bin/activate

  3. Install dependencies and run the python server

    app/python/bin/dev u
app/python/bin/dev s

VS Code

Type ctrl/command + shift + p and search for:

Extensions: Show Recommended Extensions

You will find a list of recommended extensions for the project that you can install to speed up your development.

Using dev containers

This is the recommended approach unless you face issues with docker, you’ll then need to use the local setup.

  1. Have docker installed and running on your machine.

  2. Open the project in VSCode.

  3. Install the Dev Containers extension in VSCode.

  4. Type Cmd/Ctrl + Shift + P and search for >Dev Containers: Reopen in Container. This will build the container and open the project in it.

  5. You can use the terminal in VSCode to run the commands:

Install dependencies:

bin/dev u # or bin/dev up

Run the server:

bin/dev s # or bin/dev serve

  1. Modify credentials:

    bin/dev ce # -e production or test (is development if not specified)... short for bin/dev credentials:edit

Attention - This assumes you are using ssh keys to connect to github and that the ssk keys are in the .ssh directory in your home directory. Otherwise, git commands will not work. - If the VS Code source control (git) extension is not working, do Cmd/Ctrl + Shift + P and search >Developer: Reload Window. - To rebuild the container if you change config files or need a new environment, do the following: 1- Type Cmd/Ctrl + Shift + P and search for >Dev Containers: Rebuild Container. 2- Wait for the container to be rebuilt and the project to be opened in it.

Local setup

  1. Install ruby, your ruby version should match the one in the Gemfile file.

  2. Install rails

  3. Create a .env file in the root of the project following the .env.example file.

  4. Install the dependencies packages present in the Dockerfile's apt-get install command which are basically:

  5. java 17 openjdk (don't forget to set the JAVA_HOME and RUBY_RJB_JVM_OPTS environment variables)

  6. freetds + dependencies

  7. Install dependencies:

    bin/dev u # or bin/dev up

    You will also need Java with the JAVA_HOME environment variable set to install the pdf-related dependencies. You can check oracle's documentation on how to do so.

  8. Start the development server:

    bin/dev s # or bin/dev serve

    This starts your app in development mode, rebuilding assets on file changes.

Linting

Lint and auto-correct your code using rubocop:

bin/dev l # or bin/dev lint

Push your code

When working in teams, it’s important to follow the Github flow to push your code.

Dependencies update

Dependabot’s PRs should be reviewed and merged as soon as possible to keep the project up to date.

Dump the database

Use this python command line tool:

mssql-scripter -S $HOST -d $DB_NAME -U sa -P $PASSWWORD > $SCHEMA_PATH.sql

Testing

If database changes has been made, setup test dbs:

bin/dev tdb # or testdb

To run all tests, execute:

bin/dev t # or test

To run a specific test file, execute:

bin/dev t test/models/user_test.rb

To run the tests you changed only, execute:

bin/dev td # testdiff

Documentation

Database

To generate erd diagram PDFs, add your models to the .erdconfig file then run:

bundle exec erd

To generate an interractive mermaid ERD:

bundle exec rails mermaid_erd
open mermaid_erd/index.html

The mermaid erd is available online at schema.paiehub.ca. To update the content of the mermaid ERD, do the following:

npm install -g wrangler # Install wrangler if not currently present
wrangler login
bundle exec rails mermaid_erd
wrangler pages deploy mermaid_erd --project-name schema

If asked for a project name, use the name “schema”

Code documentation

To generate a reloadable documentation website based on the comments over the code, run:

bin/dev d # doc

The rails doc is available online at railsdoc.paiehub.ca. To update the content of the code doc, do the following:

npm install -g wrangler # Install wrangler if not currently present
wrangler login
bin/dev d
wrangler pages deploy ./doc --project-name railsdoc

Deployment

On your machine used to trigger the deployment

You will need to have access to the remote machine which will itself deploy. Get its password and copy your ssh key to it:

ssh-copy-id root@192.168.11.50 # Ip present in bin/deploy

then do

bin/deploy

On the remote machine where the app will be deployed

If you’re using a fresh rocky linux machine, execute first on it:

sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io
sudo systemctl start docker

If you have a bad installation of docker or if docker is causing issues, remove it using and then reinstall:

sudo systemctl stop docker

sudo dnf remove -y docker-ce docker-ce-cli containerd.io

sudo rm -rf /var/lib/docker
sudo rm -rf /var/lib/containerd

sudo groupdel docker

On the deployment machine

To deploy to production, have .env.production file in the root of the project and run:

kamal deploy

To deploy to staging, have .env.staging file in the root of the project and run:

kamal deploy -d staging