Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


CircleCI Code Climate Test Coverage

Search engine for agencies' published content


  • Ruby

Use rvm to install the version of Ruby specified in .ruby-version.


Docker can be used to: 1) run just the required services (MySQL, Elasticsearch, etc.) while running the i14y application in your local machine, and/or 2) run the entire i14y application in a Docker container. Please refer to searchgov-services for detailed instructions on centralized configuration for the services.

When running in a Docker container (option 2 above), the i14y application is configured to run on port 3200. Required dependencies - (Ruby, and Gems) - are installed using Docker. However, other data or configuration may need to be setup manually, which can be done in the running container using bash.

Using bash to perform any operations on i14y application running in Docker container, below command needs to be run in search-services.

$ docker compose run i14y bash

For example, to setup DB in Docker:

$ docker compose run i14y bash
$ bin/rails i14y:setup

The Elasticsearch services provided by searchgov-services is configured to run on the default port, 9200. To use a different host (with or without port) or set of hosts, set the ES_HOSTS environment variable. For example, use following command to run the specs using Elasticsearch running on localhost:9207:

ES_HOSTS=localhost:9207 bundle exec rspec spec

Verify that Elasticsearch 7.17.x is running on the expected port (port 9200 by default):

$ curl localhost:9200
  "name" : "002410188f61",
  "cluster_name" : "es7-docker-cluster",
  "cluster_uuid" : "l3cAhBd4Sqa3B4SkpUilPQ",
  "version" : {
    "number" : "7.17.7",
    "build_flavor" : "default",
    "build_type" : "docker",
    "build_hash" : "78dcaaa8cee33438b91eca7f5c7f56a70fec9e80",
    "build_date" : "2022-10-17T15:29:54.167373105Z",
    "build_snapshot" : false,
    "lucene_version" : "8.11.1",
    "minimum_wire_compatibility_version" : "6.8.0",
    "minimum_index_compatibility_version" : "6.0.0-beta1"
  "tagline" : "You Know, for Search"


  • bundle install.
  • Copy config/secrets_example.yml to config/secrets.yml and fill in your own secrets. To generate a random long secret, use rake secret.
  • Run bundle exec rake i14y:setup to create the neccessary indexes, index templates, and dynamic field templates.

If you ever want to start from scratch with your indexes/templates, you can clear everything out: bundle exec rake i14y:clear_all

  • Run the Rails server on port 8081 for compatibility with the search-gov app:
$ rails s -p 8081

You should see the default Rails index page on http://localhost:8081/.

Code Quality

We use Rubocop for static code analysis. Settings specific to I14Y are configured via .rubocop.yml. Settings that can be shared among all repos should be configured via the searchgov_style gem.

Basic Usage

Create a collection for storing documents

$ curl -u dev:devpwd -XPOST http://localhost:8081/api/v1/collections \
 -H "Content-Type:application/json" -d \
 '{"handle":"test_collection","description":"my test collection","token":"test_collection_token"}'

Create a document within that collection

Use the collection handle and token for authorization:

curl http://localhost:8081/api/v1/documents \
  -XPOST \
  -H "Content-Type:application/json" \
  -u test_collection:test_collection_token \
  -d '{"document_id":"1",
      "title":"a doc about rutabagas",
      "path": "",
      "created": "2020-05-12T22:35:09Z",
      "description":"Lots of very important info on rutabagas",
      "promote": false,
      "language" : "en",
      "tags" : "tag1, another tag"

Search for a document within a collection

$ curl -u dev:devpwd http://localhost:8081/api/v1/collections/search?handles=test_collection&query=rutabaga


# Fire up Elasticsearch in search-services
$ docker-compose up elasticsearch7

$ bundle exec rake i14y:setup
$ rake