Skip to content

Latest commit

 

History

History
208 lines (136 loc) · 7.92 KB

DEVELOPMENT.md

File metadata and controls

208 lines (136 loc) · 7.92 KB
Raw

Apisonator

Development environment set up

Prerequisites

To learn how to run the project once the environment has been set up, refer to the Running section.

The first thing you will need is cloning the project:

$ git clone git@github.com:3scale/apisonator.git

Next cd into the directory, cd apisonator.

Ruby version management

In order to manage Ruby versions for local development, we recommend using asdf.

Once installed, use the provided .tool-versions.sample file to get the appropriate versions.

cp .tool-versions.sample .tool-versions

Services

Apisonator requires a Redis server to run. By default, it will try to connect to:

redis://localhost:6379

A podman-compose.yml file is provided in order to make it easier to launch some preconfigured setups, like sentinels or twemproxy.

To launch a single redis instance listening in the default URL, just run:

podman-compose -f script/config/podman-compose.yml start redis-master

Keep in mind that the test suite can't be launched against a twemproxy.

Configuring tests environment

The test suite will read the environment variables set in /.env.test.

You can set any documented variable, for example, to make the test suite point to another redis instance.

Running tests

To execute all tests from within the development environment, run this command:

$ bundle exec script/test

Running tests (advanced)

You can execute the following command to run all tests:

$ bundle exec rake

Or to run the tests in Asynchronous mode:

$ CONFIG_REDIS_ASYNC=true bundle exec rake

You can also specify execution of individual tests or type of tests.

If the test is a Unit::Test type test (located in test directory) you can execute:

$ bundle exec rake test:[unit|integration|special] [TEST=<test-file]>

If the test is a RSpec type test (located in spec directory) you can execute:

$ bundle exec rake spec:[unit|integration|acceptance|api|use_cases] SPEC=<test-file>

Alternatively there is another syntax to execute a RSpec type test:

$ bundle exec rake spec:specific[<test-file>]

where in this last case the [ ] characters must be literally placed.

Finally, you can also execute tests with rspec directly with:

$ RACK_ENV="test" bundle exec rspec --require=spec_helper <test-file>

For more information on accepted commands for testing with Rake you can execute:

$ bundle exec rake -T

Testing API users from the outside

You can test users of Apisonator API services by starting its dependencies and then apisonator itself:

$ bundle exec 3scale_backend start -p 3000

This will launch the application and wait for requests. You could now ie. launch Pisoni's testing against this Apisonator instance.

You can hit CTRL+C at any time to exit. If you wanted to pass extra parameters for the launcher, such as daemonizing, you could run this:

$ bundle exec 3scale_backend start -p 3000 -d

Documentation

Make sure to read the corresponding Swagger-generated documentation, located in docs/active_docs/Service Management API.json for the external API. You can also generate the documentation of the Internal API with Rake tasks.

Contributing

This is our basic integration flow:

  1. Fork the project.
  2. Create a topic branch and add your changes there.
  3. Create a Pull Request. To accept a PR, we require:
  4. The test suite should be green, both in the PR code and when merged.
  5. The core team or other contributors should review it.
  6. Someone in the core team should approve it.
  7. Merge to master.

We keep stable branches receiving bug and security fixes for long term releases.

Releasing a new version

Currently we need to follow this process:

  1. Change the contents of version.rb with the new version.
  2. Run bundle install with all Gemfiles to update all lockfiles.
  3. Run bundle exec rake license_finder:report:xml > licenses.xml.
  4. Modify CHANGELOG.md filling up data about notable changes along with associated issue or PR numbers where available.
  5. Run bundle exec rake release:changelog:link_prs to link the issue or PR numbers in the CHANGELOG.md file and check the diff makes sense.
  6. Review and commit "apisonator: release X.Y.Z".
  7. Verify the tests pass and fix any issue that crops up. If at all possible, deploy the version as a pre-release in a staging environment for further testing and early detection of issues.
  8. Post the PR on 3scale/apisonator.
  9. When merged, generate the tag with bundle exec rake release:tag and push it. The tag should be a signed, annotated tag, usually with the format vX.Y.Z.

Running

Apisonator has its own application runner for the listener service:

bundle exec 3scale_backend help

That will give you a help message so that you figure out how to invoke it. Some advanced usage patterns are available, as well as support for multiple application servers. The usual invocation would look something like:

$ bundle exec 3scale_backend start -p 3001

That would start the listener service in port 3001. There are however additional commands and flags that are worth knowing, so please take a look at the help message. An interesting command would be this one:

$ bundle exec 3scale_backend -s puma -X "-w 3" start -p 3001

That would be identical to the command above, except it would force the server to be Puma with 3 workers. You can obtain more info about the server specific options with:

$ bundle exec 3scale_backend -s puma help-server

Additional information which is really important to how the application runs can be found in the manifest:

$ bundle exec 3scale_backend manifest

Running from your IDE

Some IDEs like VSCode or RubyMine allow to add custom launchers for scripts. This is convenient to launch both Worker and Listener.

For that, you'll need to create the following configurations:

Worker

Field Value
Name worker
Ruby script /path/to/project/apisonator/bin/3scale_backend_worker
Script arguments --debug
Working directory /path/to/project/apisonator
Environment variables RACK_ENV=development

In case you want to run the worker in async mode you can add CONFIG_REDIS_ASYNC=true to the environment variables here or directly add it to your .env file.

Puma Listener (sync mode)

Field Value
Name listener (puma)
Ruby script /path/to/project/apisonator/bin/3scale_backend
Script arguments -s puma -X start -p 3001
Working directory /path/to/project/apisonator
Environment variables RACK_ENV=development

Falcon Listener (async mode)

Field Value
Name listener (falcon)
Ruby script /path/to/project/apisonator/bin/3scale_backend
Script arguments -s falcon start -p 3001
Working directory /path/to/project/apisonator
Environment variables RACK_ENV=development;CONFIG_REDIS_ASYNC=true