Skip to content
This repository has been archived by the owner on Jun 4, 2021. It is now read-only.

Developer setup

Jump to bottom
Scott McClellan edited this page Aug 30, 2019 · 11 revisions

Overview

The general process for developing in Razor is fairly simple, and similar to most open source projects:

  1. Obtain the source code from git.
  2. Install JRuby and library dependencies.
  3. Create the dev/test database.
  4. Configure your development instance.
  5. Migrate the database.
  6. Run the tests successfully.

I will try and go through each of those steps in reasonable detail. In this guide I make the assumption that your primary interest is in the razor server, rather than the supporting MK or client components.

Obtain the source code from git.

Razor is developed on git; there are three primary components:

You only require the repository that you intend to develop on; for the purpose of this guide check out the razor-server repository. There are no specific location requirements for this; most developers throw it somewhere inside their home directory.

In order to submit changes back you will need to have a GitHub account, and to fork the repository into your own account. We ask that changes be sent as a pull request to the main repository from your own fork -- and do that internally, as well as for external contributions.

Important things to know about sending changes in:

  • All commits must solve one, and only one, problem.
    • multiple commits can be included in a single pull request.
    • multiple problems can be solved in a single pull request, but may delay getting some of those fixes into the tree.
  • All changes must have a good commit message:
    • the summary line describes the change the way release notes would.
    • it describes the one problem that this change solves.
    • it describes how you believe the problem is solved at a high level.
      • that is: why this solves it, not what code you changed to solve it
      • eg: "fixes crash by handling messages robustly", not "fixes crash by catching an exception and logging it"
    • there are NO merge commits in your pull request
      • if you need to absorb changes from master, use git rebase to integrate them
  • We will git rebase / git am your changes to master without a merge commit.
  • Review happens in the pull request, and you may need to adjust your code based on that.

Install JRuby and library dependencies.

Once you have the source code, check the Gemfile. This will include a ruby declaration that gives you the current JRuby version required to work with Razor. This is the same version that is bundled in TorqueBox -- but for development you will need that installed on the system, not just in the bundle.

Install that JRuby; from now on I am going to assume that you installed it so that invoking ruby will run JRuby. We generally use rbenv or rvm to isolate that, but any way that works for you is fine.

Once JRuby is installed, ensure that the bundler gem is installed.

Then, run bundle install to get all the necessary gems installed, including test and development gems. Season to taste with global / local installs; it doesn't matter which you choose, as long as you do the right thing to make those gems visible to our code which doesn't explicitly use bundler during testing.

Create the dev/test database.

Note: The database can be run via docker. Run bundle exec rake docker:db to** **bring up the service.

Install PostgreSQL 9.2 or later.

Create a database for Razor testing. The most common approach is to create a "razor" database, used for all operations, and owned by yourself:

] sudo -u postgresql createdb -O $(whoami) razor

Season to taste for your local distribution and installation of PostgreSQL. That example assumes you have already created a database role matching your own username, and given it appropriate access (eg: login, whatever else you want.)

Ensure that TCP access to that database from localhost is available through the pg_hba.conf file. You can use trust or password authentication; just make sure whatever mode you select allows TCP connections with the username and password you will use shortly to configure Razor.

Configure your development instance.

  • Copy the config.yaml.sample file to config.yaml
  • Edit the "repo_store_root" in the "all" section to a valid directory (or, alternately, create the directory listed).
  • Copy the "database_url" from the "production" section to the "all" section.
  • Delete the "production", "test", and "development" sections entirely.
  • Edit the "database_url" in the "all" section to connect to the database you just created. (eg: set the name, username, password, etc, appropriately.)

You can, if you wish, use separate databases for development and testing. If so, create and configure them separately in the obvious way.

Migrate the database.

Migrate the database; if you followed the guide you can run this in the "development" environment and have "test" work automatically; this is generally useful because you will want to run tests while you are working on code changes, and they need to use the current database migrations including any local changes you have added.

./bin/razor-admin migrate-database

That should work since we already installed JRuby and the other support tools; you should see some logging output showing progress through the migrations, including all the raw SQL commands issued.

If this fails, fix the problems; this is the first point that all the components have come together to check that you installed the right JRuby, the bundled dependencies, and got your PSQL configuration right.

Run the tests successfully.

Finally, run the tests:

bundle exec rspec spec

That should all run through correctly.

A potentially more useful invocation is:

TORQUEBOX_FALLBACK_LOGFILE=/dev/null JRUBY_OPTS='--debug' bundle exec rspec -d spec

That sets two useful things:

  • TORQUEBOX_FALLBACK_LOGFILE is the path to use for output from the built-in logging system, which defaults to the console. That is the very verbose logging that you see in the first run.
  • JRUBY_OPTS: the --debug flag turns on JRuby engine debugger support, which generates additional internal data to help debugging -- and in our case, code coverage testing.

[Optional] Start torquebox service

Assure you are back in the razor-server repository root and deploy the app:

cd <your razor-server repo root>
torquebox deploy

To run the service for local testing on port 8150, issue:

torquebox run -b 0.0.0.0 --port 8150

The razor-client should now be able to connect to the Razor server.

Docker support

If you'd like to run Razor inside a docker container, which is potentially useful for development, run:

bundle exec rake docker:start

This starts up a Torquebox instance and supporting database. Once this is running, the Razor client should connect to the API by default. Run bundle exec rake -T for more info on which docker commands are available.

Perform a celebratory dance!

Perform a celebratory dance!

Clone this wiki locally