ICD - Interface Control Document Management
Scala CSS Other
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
icd-db
icd-git
icd-web
icd
project
.gitignore
CHANGELOG.md
README.md
build.sbt
docker-build.sh
docker-run.sh
install.sh

README.md

ICD - Interface Control Document Management

This project contains support for validating, searching and viewing subsystem APIs and ICDs (Interface Control Document between two TMT subsystems).

The validation is based on JSON Schema, however the schema descriptions as well as the ICDs themselves may also be written in the simpler HOCON format.

Versions of ICDs are managed in GitHub repositories and the subsystem model files can be imported (with version history) into a local MongoDB database, which is used by command line applications and a web app.

Three command line applications (icd, icd-db), icd-git) and a web app (icd-web) are provided for working with ICDs, querying and viewing the data.

The applications here assume the MongoDB database is running. To start the MongoDB server, you can run a command like this:

mongod -dbpath $db

where $db is the directory containing the database.

The default database name used is icds and can be configured in icd-db/src/main/resources/reference.conf, in /conf/reference.conf or via equivalent -D (system property) command line options.

ICD Subprojects

There are currently these ICD subprojects:

  • icd - supports validating an API against the JSON schema as well as saving it as a Markdown, HTML or PDF document
  • icd-db - supports ingesting API files into a MongoDB database, querying the db and saving an API or ICD as a document
  • icd-git - work directly with ICD model files stored on GitHub, publish ICDs, ingest ICD releases into the ICD database
  • icd-web - a Play/Scala.js based web app for working with ICDs

Build and Install

An install.sh script is provided that builds and installs all of the subprojects into the ../install_icd directory. This is basically just the command sbt stage in each project followed by copying the products to the install directory. A binary is installed for each subproject, with the same name as the subproject (except for icd-web, where the binary produced is icdwebserver).

For the command line apps, the --help option prints a summary of the command line options.

The icdwebserver application starts the web app (by default on localhost:9000). You can change the port used by adding an option like this: -Dhttp.port=9876.

Note that the build is set up so that the Play subproject is selected on start. So to run any commands (like sbt clean or sbt stage) that should apply to the other projects, you need to first switch to that project or the root project. For example sbt clean "project root" clean.

Play Project icd-web

To start the server for the web app during development, you can use sbt run from this directory. Then go to http://localhost:9000 in a web browser.

See icd-web/README.md for more information.

Importing ICD-Model-Files from GitHub into the ICD Database with Version History

Using the icd-git command line application you can publish subsystem APIs and ICDs between subsystems. Publishing a subsystem or ICD adds an entry to a JSON file on GitHub which is used later to extract specific versions of the model files.

The app also lets you import subsystem model files directly from the GitHub repositories into a local MongoDB database for use with the icd tools.

Warning: The icd-git app will currently delete the current contents of the ICD database before ingesting the files from the repository (This may be changed in the future).

The icd web app lists the published versions of subsystems and ICDs from GitHub and the model files are checked out and ingested into the database automatoically as needed (when you select a subsystem from the menu, for example).

Docker Install

Two Docker related scripts are provided in the top level directory.

  • docker-build.sh - Runs sbt docker:stage and docker build to build the docker image

  • docker-run.sh - Can be used to run the ICD web server inside Docker

Note that both scripts should be edited to add the correct docker user. See comments in the scripts for more information.