{"id":20996180,"url":"https://github.com/stefan-kolb/nucleus","last_synced_at":"2025-06-16T08:36:08.073Z","repository":{"id":25573941,"uuid":"29007690","full_name":"stefan-kolb/nucleus","owner":"stefan-kolb","description":"Platform as a Service API abstraction layer.","archived":false,"fork":false,"pushed_at":"2018-04-03T16:33:49.000Z","size":176382,"stargazers_count":28,"open_issues_count":15,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-14T21:52:19.652Z","etag":null,"topics":["api","cloud","cloud-computing","cloud-foundry","heroku","openshift","paas","platform-as-a-service"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stefan-kolb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-09T08:27:29.000Z","updated_at":"2022-05-24T11:31:25.000Z","dependencies_parsed_at":"2022-08-02T10:41:53.567Z","dependency_job_id":null,"html_url":"https://github.com/stefan-kolb/nucleus","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/stefan-kolb/nucleus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefan-kolb%2Fnucleus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefan-kolb%2Fnucleus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefan-kolb%2Fnucleus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefan-kolb%2Fnucleus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stefan-kolb","download_url":"https://codeload.github.com/stefan-kolb/nucleus/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefan-kolb%2Fnucleus/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260126776,"owners_count":22962686,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","cloud","cloud-computing","cloud-foundry","heroku","openshift","paas","platform-as-a-service"],"created_at":"2024-11-19T07:28:23.052Z","updated_at":"2025-06-16T08:36:08.040Z","avatar_url":"https://github.com/stefan-kolb.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nucleus\n\n[![Build Status](https://travis-ci.org/stefan-kolb/nucleus.svg)](https://travis-ci.org/stefan-kolb/nucleus)\n[![Gem Version](https://badge.fury.io/rb/nucleus.svg)](https://badge.fury.io/rb/nucleus)\n\n_Nucleus_ is a RESTful abstraction layer and Ruby gem to unify core management functions of Platform as a Service (PaaS) systems.\n\nThe API is build using [Ruby](https://www.ruby-lang.org) and the [grape framework](https://github.com/intridea/grape).\nIt provides fully compliant [swagger](http://swagger.io/) schemas that serve for documentation and client generation.\n\n## Table of Contents\n\n* [Supported Vendors](#supported-vendors)\n* [Usage](#usage)\n  * [Ruby Interpreter Compatibility](#ruby-interpreter-compatibility)\n  * [Installation instructions](#installation-instructions)\n  * [Use in your application](#use-in-your-application)\n  * [Use the API](#use-the-api)\n    * [Start the server](#start-the-server)\n    * [API endpoints](#api-endpoints)\n* [Functionality](#functionality)\n  * [Authentication](#authentication)\n    * [Special characters (umlauts, ....)](#special-characters-umlauts-)\n  * [Core constructs](#core-constructs)\n    * [Vendors](#vendors)\n    * [Providers and Endpoints](#providers-and-endpoints)\n  * [Custom API calls (experimental)](#custom-api-calls-experimental)\n    * [Execute a custom API call against the endpoint](#execute-a-native-api-call-against-the-endpoint)\n    * [Execute a custom API call against an endpoint's application](#execute-a-native-api-call-against-an-endpoints-application)\n* [Adapters](#adapters)\n  * [Heroku](#heroku)\n  * [Cloud Foundry v2](#cloud-foundry-v2)\n  * [Openshift v2](#openshift-v2)\n* [Configuration](#configuration)\n  * [Vendors, Providers and Endpoints](#vendors-providers-and-endpoints)\n  * [Application configuration](#application-configuration)\n* [API client(s)](#api-clients)\n  * [Accept Header](#accept-header)\n  * [Error codes](#error-codes)\n  * [Language specific clients](#language-specific-clients)\n* [Tests](#tests)\n* [Schema validation](#schema-validation)\n* [Versioning](#versioning)\n* [Security](#security)\n* [Project structure](#project-structure)\n* [Contributing](#contributing)\n* [Further documentation](#further-documentation)\n\n## Supported Vendors\n\n- [Heroku][heroku]\n- [Cloud Foundry][cloud_foundry] (v2)\n  - [AppFog][appfog], [Anynines][anynines], [IBM Bluemix][bluemix], [Pivotal Web Services][pivotal_ws], [HP Helion][hp_helion]\n- [Openshift][openshift_v2] (v2)\n  - [OpenShift Online][openshift_online], [getup Cloud][getup]\n\n[heroku]: https://www.heroku.com\n\n[cloud_foundry]: https://www.cloudfoundry.org/\n[appfog]: https://www.ctl.io/appfog/\n[anynines]: http://www.anynines.com/\n[bluemix]: https://console.ng.bluemix.net/\n[pivotal_ws]: https://run.pivotal.io/\n[hp_helion]: http://www8.hp.com/de/de/cloud/helion-devplatform-overview.html\n\n[openshift_v2]: https://www.openshift.com/\n[openshift_online]: https://www.openshift.com/features/index.html\n[getup]: https://getupcloud.com/index_en.html\n\nMore information on the vendors and the associated adapter can be found in the [adapters section](#adapters).\n\n## Usage\n\nNucleus can either be used as standalone application/service, or as part of another ruby application.\nPlease make sure to obey the following installation instructions before starting to use Nucleus.\n\n### Ruby Interpreter Compatibility\n\nNucleus is supposed to run on Ruby \u003e= 2.3.\nDue to native gem dependencies, it currently won't work on JRuby.\n\n### Installation instructions\n\n1) The following executables must be available on the system's *PATH*:\n\n    git, ssh\n\n#### Platform-specific notes\n\nUnix systems should run fine out of the box, whereas Windows systems might need some adjustments:\n\n##### Windows\n\nBoth required executables should be located in the `Git/bin` installation directory of [msysGit](https://msysgit.github.io/).\nNucleus is verified to work with [msysGit](https://msysgit.github.io/) and the included version of `OpenSSH`.\nWe did not verify other alternatives, e.g. PuTTY's `plink.exe`.\nPuTTY is supposed to not work due to the lack of the `-o UserKnownHostsFile=NUL -o StrictHostKeyChecking=no` options that allow to connect any git repository without confirmation of the host's identity.\n\n###### Troubleshooting\n\n**Eventmachine**:\n\nEventmachine sometimes fails with the error `Encryption not available on this event-machine`.\nA fix is available, but requires a few steps:\n\n1) Uninstall the gem\n\n```shell\n$ gem uninstall eventmachine\n```\n\n2) Download the OpenSSL package from [http://packages.openknapsack.org/openssl/openssl-1.0.0k-x86-windows.tar.lzma](http://packages.openknapsack.org/openssl/openssl-1.0.0k-x86-windows.tar.lzma)\n\n3) Extract it to a desired location\n\n4) Re-install the gem and point to the OpenSSL installation directory. Escape backslashes or use forward slashes.\n\n```shell\n$ gem install eventmachine -- --with-ssl-dir=C:/SSL\n```\n\n### Use in your application\n\n#### Require nucleus and mark as dependency\n\nAdd a dependency on the Nucleus gem, for instance in your application's Gemfile,\n\n```ruby\ngem 'nucleus'\n```\n\nupon which you would update your bundle.\n\n```shell\n$ bundle install\n```\n\nOr install the gem by yourself:\n\n```shell\n$ gem install nucleus\n```\n\nFinally, require the gem inside your application\n\n```ruby\nrequire 'nucleus'\n```\n\n#### Communicate with an endpoint\n\n1) Configuration [optional]\n\nAdapt the configuration to your needs and adjust the values via the global `nucleus_config` variable.\nThe configuration *must* be changed before initializing the `AdapterResolver`, otherwise the configuration is locked and can't be changed anymore.\n\nFor more information have a look at the [configuration](#configuration) section.\n\n2) Show all currently available API versions:\n\n```ruby\nNucleus::VersionDetector.api_versions\n```\n\n3) Instantiate an `AdapterResolver` for the desired API version:\n\n```ruby\nresolver = Nucleus::AdapterResolver.new('v1')\n```\n\n4) Show all adapters that are supported by Nucleus by this specific API version:\n\n```ruby\nresolver.adapters\n```\n\n```ruby\n{ \"cloud_foundry_v2\"=\u003eNucleus::Adapters::V1::CloudFoundryV2, \"heroku\"=\u003eNucleus::Adapters::V1::Heroku, \"openshift_v2\"=\u003eNucleus::Adapters::V1::OpenshiftV2 }\n```\n\n5) Load your desired adapter implementation:\n\n```ruby\nadapter = resolver.load('cloud_foundry_v2', 'api.pivotal.io', 'your_username', 'your_password')\n```\n\nBy default, the adapter will be populated with the default configuration options that are defined in the vendor's configuration for the selected endpoint_url.\nIf you are using a custom installation, e.g. of *OpenShift* or *Cloud Foundry*, make sure to pass the option that describes the `app_domain` for deployed applications.\nOtherwise, the `web_url` links created by Nucleus will be malformed.\n\n```ruby\nminimal = resolver.load('heroku', 'your_username', 'your_password')\nadapter = resolver.load('cloud_foundry_v2', 'api.example.org', 'your_username', 'your_password', app_domain: 'apps.example.org', check_ssl: false)\n```\n\n6) Start using the platform and invoke commands:\n\n```ruby\n# Show available regions\nadapter.regions\n# Create our first application\napp = adapter.create_application(region: 'default', name: 'myusersfirstapplication', runtimes: ['nodejs'])\n# And delete the application again\nadapter.delete_application(app[:id])\n```\n\nCheck the **documentation** of the `Nucleus::Adapters::V1::Stub` adapter (or any other API version) for a complete list of supported actions.\nYou can also refer to the documentation of the REST interface to get detailed information about the parameter options of `post` and `put` commands,\nincluding which fields are required and those that are only optional.\n\n### Use the API\n\nBesides including the abstraction layer in your application, Nucleus can also be started and serve a RESTful API:\nFor detailed usage information go to the section [API client(s)](#api-clients).\n\n#### Start the server\n\nThe easiest way to run the API is via Docker Hub.\n\n```shell\ndocker pull stfnklb/nucleus\ndocker run -it -p 9292:9292 nucleus\n```\n\nThe server is exposed at `localhost:9292` by default.\n\nOr build it on your own.\nBe aware that there might be issues with line endings inside the configuration files, if you check out Windows or legacy macOS line endings instead of Linux LF line endings.\n\n```shell\n$ docker build -t nucleus .\n$ docker run -it -p 9292:9292 nucleus\n```\n\nIf you want to run Nucleus locally without Docker here's how to do it.\nA rack server can be started in multiple ways.\nThe most convenient solution is to use the provided script:  \n\n```shell\n$ ./bin/nucleus\n```\n\nHowever, you can also start the API using the [thin](http://code.macournoyer.com/thin/) server:\n\n```shell\n$ rackup -s thin config.ru\n```\n\nDue to limitations in the log tailing process, Nucleus currently requires `thin` and does not work on other Rack servers.\nIn theory, it should be possible to make other Rack servers work that also utilize [eventmachine](https://github.com/eventmachine/eventmachine).\n\n#### HTTPS\n\nWe highly encourage you to **only use https connections** when your application is running in production or used outside of your local computer.\nThis is due to the fact that all passwords are passed via the HTTP basic authentication, which does not encrypt your data so that any third party could log and identify your credentials.\n\nTo enforce this policy, Nucleus will automatically redirect all connections on plain HTTP to HTTPS connections if it is running in production (detected via *RACK_ENV*).\n\n#### API endpoints\n\nThe API of Nucleus is documented via [swagger](http://swagger.io).\nAfter you started a server instance, you can access an interactive [swagger-ui](https://github.com/swagger-api/swagger-ui) at the `/docs` path.\n\n## Functionality\n\nThe following list shows the degree to which the adapters implement the offered methods.\nThis list can be auto-generated via:\n\n```\n$ bundle exec rake evaluation:compatibility:markdown\n```\n\n**State: 3/7/2016**\n\nMethod / Vendor|Cloud Foundry v2|Heroku|Openshift v2\n:--|:-:|:-:|:-:\nauth_client|\u0026#10003;|\u0026#10003;|\u0026#10003;\nregions|\u0026#10003;|\u0026#10003;|\u0026#10003;\nregion|\u0026#10003;|\u0026#10003;|\u0026#10003;\napplications|\u0026#10003;|\u0026#10003;|\u0026#10003;\napplication|\u0026#10003;|\u0026#10003;|\u0026#10003;\ncreate_application|\u0026#10003;|\u0026#10003;|\u0026#10003;\nupdate_application|\u0026#10003;|\u0026#10003;|\u0026#10007;\ndelete_application|\u0026#10003;|\u0026#10003;|\u0026#10003;\ndomains|\u0026#10003;|\u0026#10003;|\u0026#10003;\ndomain|\u0026#10003;|\u0026#10003;|\u0026#10003;\ncreate_domain|\u0026#10003;|\u0026#10003;|\u0026#10003;\ndelete_domain|\u0026#10003;|\u0026#10003;|\u0026#10003;\nenv_vars|\u0026#10003;|\u0026#10003;|\u0026#10003;\nenv_var|\u0026#10003;|\u0026#10003;|\u0026#10003;\ncreate_env_var|\u0026#10003;|\u0026#10003;|\u0026#10003;\nupdate_env_var|\u0026#10003;|\u0026#10003;|\u0026#10003;\ndelete_env_var|\u0026#10003;|\u0026#10003;|\u0026#10003;\nstart|\u0026#10003;|\u0026#10003;|\u0026#10003;\nstop|\u0026#10003;|\u0026#10003;|\u0026#10003;\nrestart|\u0026#10003;|\u0026#10003;|\u0026#10003;\ndeploy|\u0026#10003;|\u0026#10003;|\u0026#10003;\nrebuild|\u0026#10003;|\u0026#10003;|\u0026#10003;\ndownload|\u0026#10003;|\u0026#10003;|\u0026#10003;\nscale|\u0026#10003;|\u0026#10003;|\u0026#10003;\nlog?|\u0026#10003;|\u0026#10003;|\u0026#10003;\nlogs|\u0026#10003;|\u0026#10003;|\u0026#10003;\nlog_entries|\u0026#10003;|\u0026#10003;|\u0026#10003;\ntail|\u0026#10003;|\u0026#10003;|\u0026#10007;\nservices|\u0026#10003;|\u0026#10003;|\u0026#10003;\nservice|\u0026#10003;|\u0026#10003;|\u0026#10003;\nservice_plans|\u0026#10003;|\u0026#10003;|\u0026#10003;\nservice_plan|\u0026#10003;|\u0026#10003;|\u0026#10003;\ninstalled_services|\u0026#10003;|\u0026#10003;|\u0026#10003;\ninstalled_service|\u0026#10003;|\u0026#10003;|\u0026#10003;\nadd_service|\u0026#10003;|\u0026#10003;|\u0026#10003;\nchange_service|\u0026#10003;|\u0026#10003;|\u0026#10007;\nremove_service|\u0026#10003;|\u0026#10003;|\u0026#10003;\n\n### Core constructs\n\nNucleus could support any constellation of PaaS offers that are currently available.\nIn order to do so, we differentiate between between vendors, providers, and endpoints:\n\nA *vendor* is the organization that developed the platform software, which also determines the offered functionalities.\nA *provider* runs the platform, which always has at least one *endpoint*.\n\nFor most scenarios the *endpoint* is identical to the *provider*, but in some cases,\nfor instance on [IBM Bluemix][bluemix], *endpoints* distinguish different deployment regions.\n\nIf running Nucleus as web service, all changes made to these entities at runtime will be discarded, unless you enable persistence functionality in the configuration and specify a location where to persist the data to.\n\n#### Vendors\n\nYou can use the API of Nucleus to show a list of all supported vendors.\nThis request is publicly available and does not require any authentication.\n\nHowever, you cannot create, delete or update a vendor at runtime because it represents the logic to communicate with the associated platform.\nAll developers that want to have more information on how to add a new vendor, please see the instructions: [Add a vendor (or implement a new adapter)](wiki/implement_new_adapter.md)\n\n#### Providers and Endpoints\n\nProviders and Endpoints can be managed *without authentication* and support `GET`, `POST`, `PATCH`, `DELETE` requests.\n\nA new entity can be registered at runtime by sending a `POST` request.\nWhereas a provider only requires a `name`, an endpoint also needs the `url` as further attribute.\nPlease refer to the swagger-ui documentation for additional information about the requests.\n\n### Authentication\n\nAuthentication against the endpoint is managed by Nucleus.\nThe credentials must be provided as [Basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) header **within each single request**.\nHeroku requires a combination of username:apikey instead of username:password!\n\n    Authorization: Basic thebase64encodedcredentialsstring\n\n#### Special characters\n\nThe usage of special characters, for instance german umlauts may cause issues with some platforms.\nPlease make sure to select the correct encoding for your credentials before encoding them with Base64:\n\n* Stackato 3.4.2: Different encodings cause the requests to crash and return status 500\n\n### Application logs\n\nBelow are some examples how to use the API in order to obtain detailed application logs.\n\n#### Download a selected logfile of an application\n\n```shell\ncurl -X \"GET\" \"http://localhost:9292/api/endpoints/cf-bosh-local/applications/{app_id}/logs/{log_id}/download\" -H \"Authorization: {auth_header}\" -O -J\n```\n\n#### Download all logfiles of an application\n\n```shell\ncurl -X \"GET\" \"http://localhost:9292/api/endpoints/cf-bosh-local/applications/{app_id}/logs/download\" -H \"Authorization: {auth_header}\" -O -J\n```\n\n#### Tail a selected logfile of an application\n\n```shell\ncurl -X \"GET\" \"http://localhost:9292/api/endpoints/cf-bosh-local/applications/{app_id}/logs/{log_id}/tail\" -H \"Authorization: {auth_header}\" --raw -v\n```\n\n### Custom API calls (experimental)\n\nSometimes you might want to call proprietary functionality that goes beyond Nucleus' unified API approach.\nYou can also execute such custom API calls against the endpoint's API with Nucleus.\nThis feature is included as experimental functionality and **does not return unified objects or errors**.\nThe response of the API is passed 1:1 to the REST client.\n\nThe custom calls can be made either against the endpoint or against an application.\nAllowed HTTP methods are `GET`, `POST`,`PATCH`, `PUT` and `DELETE`.\nData embedded in a requests body is used 1:1 in the API call, header information are going to be discarded.\n\nPlease be aware that you must also include the API version in the path if required by the platform.\nFor instance, Cloud Foundry requests would have to look like: `.../call/v2/app_usage_events`\n\n##### Execute a custom API call against the endpoint\n\nIn this example, we want to get the current user's account information.\nTherefore, we append the `call` action to the endpoint, followed by the API's native path to the resource: `account`\n\n```\nGET /api/endpoints/heroku/call/account\n```\n\n```json\n{\n  \"allow_tracking\": true,\n  \"beta\": false,\n  \"email\": \"theusersemail@provider.domain\",\n  \"id\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\n  \"last_login\": \"2014-11-25T08:52:59Z\",\n  \"name\": \" \",\n  \"two_factor_authentication\": false,\n  \"verified\": false,\n  \"created_at\": \"2014-11-18T09:37:21Z\",\n  \"updated_at\": \"2015-02-18T18:57:33Z\",\n  \"default_organization\": null\n}\n```\n\n##### Execute a custom API call against an endpoint's application\n\nIn this example we try to list the builds of an Heroku application.\nTherefore, we append the `call` action to the application at the endpoint, followed by the API's native path to the resource: `builds`\n\n```\nGET /api/endpoints/heroku/applications/the_application_name/call/builds\n```\n\nThe response is the unprocessed response of the Heroku API as shown in the previous example.\n\n## Adapters\n\nThe functionality to communicate with different platforms is implemented in so called *adapters*.\nHowever, not each adapter can fully support the abstract Nucleus definitions.\nPlease refer to the [functionality section](#functionality) for more information about the supported features.\n\n### Heroku\n\nProviders: [Heroku](http://heroku.com)\n\nHeroku requires a combination of username:apikey instead of username:password for authentication!\n\n### Cloud Foundry v2\n\nProviders: [AppFog][appfog], [Anynines][anynines], [IBM Bluemix][bluemix], [Pivotal Web Services][pivotal_ws], [HP Helion][hp_helion]\n\n#### Issues\n\n**Logs**\n\nCF stopped to provide the `stdout` and `stderr` files in the `logs` directory.\nCurrently, we do not know of an approach to fetch recent log entries without registering an additional service on the application.\n\nMoreover, logs can only be retrieved as long as at least once instance of the CF application is running, hence the application state is `running`.\nIf there are no logs that can be retrieved, the log list will be empty and the request for a particular log file will result in an 404 error.\n\n**Services**\n\n- As of now, we only allow bindable services and create a new instance of the service to add\n- Therefore, services must be `active` and `bindable`\n- Only one instance of the same service can be bound to the application\n\n### Openshift v2\n\nProviders: [OpenShift Online][openshift_online], [getup Cloud][getup]\n\n#### Issues\n\n**Application update**\n\nAn application can't be updated, the `name` and `runtimes` can't be changed once created.\n\n**Application scaling**\n\nApplications not created with Nucleus can't be scaled if they were created with the attribute `scalable = false`\n\n**Services**\n\n- Services can be added to the application, but scaling (gears, memory allocation, ...) and\nfurther configuration are not supported as of now.\n- We focus on the `embedded` cartridges and omit `standalone` services such as *Jenkins*.\n- With no service plans and therefore nothing to change, the *change service* function is not implemented.\n\n**Performance**\n\nRecording is really slow. Even worse, actions quite often fail with Openshift internal timeouts.\n\n## Configuration\n\nSeveral parts of Nucleus can be configured, e.g. whether to persist your data or always start with a clean instance.\nThere are two different locations at which the configuration files can be placed.\nThey are described with increasing importance, meaning that the last option overwrites keys that were also configured in the previous files:\n\n1. A file in user account's home directory. On UNIX systems this file must be placed at `~/.nucleus/nucleus_config.rb`, whereas it is expected at `~/nucleus/nucleus_config.rb` if running Windows.\n2. The `config/nucleus_config.rb` file in the project's directory\n\n### Vendors, Providers, and Endpoints\n\nA vendor is reflected by an adapter implementation, but the providers and their endpoints can either be changed at runtime or via `.yaml` configuration files.\nThese adapter configuration files are located in the project directory at `config/adapters`.\n\n#### Add a new Provider\n\nTo add a new provider, open the `config/adapters` directory and select the platform that the provider is using.\nFor more explanations of the fields, or if the platform is not listed, please refer to the Guide [how to implement a new adapter)](wiki/implement_new_adapter.md).\n\nNext, add your provider and its endpoint(s) to the configuration file.\n\n###### Example adapter configuration\n\n```yaml\n  ---\n  name: \"Openshift 2\"\n  id: \"openshift_v2\"\n  providers:\n    -\n      name: \"Openshift Online\"\n      id: \"openshift-online\"\n      endpoints:\n        -\n          name: \"Openshift Online\"\n          id: \"openshift-online\"\n          url: \"openshift.redhat.com/broker/rest\"\n```\n\n## API clients\n\nThe API can be used with the REST client of your choice.\n\n### Accept Header\n\nNucleus always uses the latest API version if no `Accept` header is specified.\nWe therefore **strongly encourage** you to always specify the `Accept` header.\nThe vendor thereby must be set to `nucleus` and the version must be available.\nOtherwise an error with the HTTP status `406` is returned.\nA sample `Accept` header would be:\n\n```\nAccept = application/vnd.nucleus-v1\n```\n\n### Error codes\n\nThe application uses the following subset of error codes:\n\n```\n400: Bad Request\n401: Unauthorized\n404: Resource not found\n406: API vendor or version not found\n422: Unprocessable Entity due to invalid parameters\n500: Internal processing error\n501: Not implemented, adapter does not provide this feature\n503: Destination service temporarily unavailable\n504: Gateway Time-out\n```\n\nAll errors are returned in a common schema:\n\n```ruby\n{\n  \"status\": HTTP_STATUS_CODE,\n  \"message\": SIMPLE_ERROR_MESSAGE,\n  \"dev_message\": DEVELOPER_MESSAGE_WITH_TECHNICAL_DETAILS_TO_RESOLUTION,\n  \"error_code\": UNIQUE_ERROR_CODE,\n  \"more_info\": LINK_TO_DOCUMENTATION_DESCRIBING_THE_ERROR\n}\n```\n\n### Language-specific clients\n\nAs of now, there is no language-specific API client available.\nAs a reward of providing swagger-compatible API docs, clients can be generated for several languages.\nFor detailed information, please have a look at the [swagger-codegen project](https://github.com/swagger-api/swagger-codegen).\n\n## Tests\n\nThe tests are divided into 3 categories, _unit_, _integration_ and _adapter_ tests.\nYou can either call all tests or each suite separately.\n\n```\nbundle exec rake spec\nbundle exec rake spec:suite:unit\nbundle exec rake spec:suite:integration\nbundle exec rake spec:suite:adapters\n```\n\n## Schema validation\n\nThe generated schema can be validated against the [swagger specification](https://github.com/swagger-api/swagger-spec).\nPlease have a look at the [swagger-codegen project](https://github.com/swagger-api/swagger-codegen).\n\n## Versioning\n\nNucleus follows the [Semantic Versioning](http://semver.org/) standard.\nTherefore, Nucleus also allows to serve multiple versions of the API and provide legacy support.\n\nHowever, be aware that\n__each non-backward compatible change of the application must result in an increase of the major version.__\n\nUntil the first release (v1), the initial version is: `0.1.0`.\n\n## Security\n\nAs described in the [HTTPS](#https) section, we strongly encourage you to only run Nucleus with HTTPS.\n\n### Public key registration\n\nNucleus uses the SSH key authentication for Git deployments.\nThe private (!) key that will be used is located at `config/nucleus_git_key.pem`.\nUsing the pre-generated key mitigates issues with the key usage/generation on various platforms.\nTo prevent abuse we register the key before each command and immediately remove the key once the command has been executed.\n\n**To improve the security of your deployment, you can use your own custom private key.\nTo do so, set the `nucleus_config.ssh.custom_key` option in the [common configuration](#configuration) to the location of the private key file.\nFor reasons of automation, the key must not be password encrypted.**\n\n## Project structure\n\n```\nbin # Binary startup files and GIT__SSH env. agents\nconfig # Configuration files for Nucleus and its adapters\ndoc # Generated YARD documentation\nlib # The Nucleus application source code\nlib/nucleus # Gem compatible directory of the core, includes the AdapterResolver class\nlib/nucleus/adapters # The adapter implementations to communicate with the vendor's platforms, grouped by API version.\nlib/nucleus/core # All other functionality used throughout the application, but rather unrelated to the Grape API: http requests, authentication, errors, etc.\nlib/nucleus/ext # Monkey patched classed and extensions\nlib/nucleus/scripts # Initialization scripts, bootstrapping and shutdown hooks\nlib/nucleus_api/api # Everything that is directly related to the RESTful Grape API: entities, embedded helpers and the actual API version's definitions\nlib/nucleus_api/ext # Monkey patched classed and extensions related only to the API\nlib/nucleus_api/import # Import management of the adapter configuration files\nlib/nucleus_api/persistence # The persistence layer, including the DAOs and the entity's models (Vendor, Provider, Endpoint, ...)\nlib/nucleus_api/rack_middleware # Rack middleware layers for authentication, request ids and logging\nlib/nucleus_api/scripts # Initialization scripts, bootstrapping, rackup and shutdown hooks of the API\npublic # public directory for rack, hosts the swagger-ui files for the live API documentation\nschemas # Kwalify schemas, used to parse the configuration and load new vendors at startup\nspec # All rspec test suites\ntasks # Rake tasks, mostly related to generate tables and statistics\nwiki # Further documentation files\n```\n\n## Contributing\n\nWe love contributions from everyone! See our [contribution guidelines](CONTRIBUTING.md) for details.\n\n## Further documentation\n\n- [Add a vendor (or implement a new adapter)](wiki/implement_new_adapter.md)\n- [Adapter Tests](wiki/adapter_tests.md)\n\nThe technical report [\"Nucleus - Unified Deployment and Management for Platform as a Service\"](http://nbn-resolving.de/urn/resolver.pl?urn:nbn:de:bvb:473-opus4-465595) explaining the details of our implementation is available [here](http://nbn-resolving.de/urn/resolver.pl?urn:nbn:de:bvb:473-opus4-465595).\nNucleus also has been used in the the paper [\"Unified Cloud Application Management\"](http://www.uni-bamberg.de/?id=112935) which was presented at the 12th IEEE World Congress on Services in San Francisco, USA.\nYou can find a preprint version of the paper [here](http://www.uni-bamberg.de/?id=112935).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefan-kolb%2Fnucleus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstefan-kolb%2Fnucleus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefan-kolb%2Fnucleus/lists"}