Cortex CMS

Cortex CMS is a multitenant identity, content distribution/management and reporting platform built by the Content Enablement team at CareerBuilder. Its purpose is to provide central infrastructure for next-generation applications; exposing a single point of management while enabling quicker build-out of new software.

Cortex follows a decentralized, API-only architecture - it is not built like Wordpress or Drupal, which are considered monolithic, all-in-one solutions.

Setup
- Environment
- Dependencies
  - System
    - OS X
    - Linux
  - Application
- Database
- Server
- Deployment
Running Test Suite
API
- Documentation
Consuming Cortex
Applications Using Cortex
Troubleshooting
Contributing
License
Copyright

Setup

Environment

Copy and rename the example .env.example file as .env and modify it to match your environment.

For a rudimentary setup, these variables should be configured:

Execute $ bundle exec rails secret twice to generate both an APP_SECRET and DEVISE_SECRET
If the superuser isn't used for the app databases, the DATABASE_USERNAME and DATABASE_PASSWORD should be set accordingly.

Dependencies

System

OS X

Install the Xcode Command Line tools:

$ xcode-select --install

Install all Cortex system-wide dependencies (and the readline Ruby/byebug build dependency) using Homebrew from the Brewfile via $ brew install $(cat Brewfile|grep -v "#")
Install Ruby via rbenv or rvm.
Enable system agents:

$ ln -sfv /usr/local/opt/postgresql/*.plist ~/Library/LaunchAgents
$ ln -sfv /usr/local/opt/elasticsearch/*.plist ~/Library/LaunchAgents
$ ln -sfv /usr/local/opt/redis/*.plist ~/Library/LaunchAgents

and start them with brew services:

$ brew services start postgresql
$ brew services start elasticsearch
$ brew services start redis

or launchctl:

$ launchctl load ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist
$ launchctl load ~/Library/LaunchAgents/homebrew.mxcl.elasticsearch.plist
$ launchctl load ~/Library/LaunchAgents/homebrew.mxcl.redis.plist

Linux

Install all Cortex system-wide dependencies (and the readline Ruby/byebug build dependency) using your distribution's package manager (pacman, apt-get, yum, etc). For example, with Ubuntu's apt-get:

$ apt-get install libreadline6-dev postgresql postgresql-contrib redis-server openjdk-8-jre imagemagick jpegoptim ghostscript

Ubuntu and Redhat/Fedora do not have an official elasticsearch package - you must use Elasticsearch's repository or follow these instructions. The same goes for phantomjs. Build from source or use a PPA. Other Linux distributions likely have these as prebuilt packages in their official or user repositories.

Install Ruby via rbenv or rvm.
Enable system agents using your distribution's service manager frontend, which is likely systemd's frontend, systemctl:

$ systemctl enable postgresql
$ systemctl enable elasticsearch
$ systemctl enable redis

and start them with systemctl:

$ systemctl start postgresql
$ systemctl start elasticsearch
$ systemctl start redis

Application

Install Bundler and its dependencies:

$ gem install bundler && bundle install

Install node, then run Yarn to install frontend dependencies:

$ yarn install

Database

Create databases:

$ bundle exec rake db:create

Initialize the schema:

$ bundle exec rake db:schema:load

Seed database with a top-level tenant, the superuser and Custom Content data, then rebuild the ElasticSearch index:

$ bundle exec rake db:seed
$ bundle exec rake cortex:core:db:reseed
$ bundle exec rake cortex:rebuild_indexes

Server

Start Cortex, Sidekiq and live rebuild/reload via Foreman:

$ gem install foreman
$ foreman start -f Procfile.dev-server

The admin interface should now be accessible locally on port 3000. To access Cortex as superadmin, login as admin@cortexcms.org with password welcome1.

Deployment

Deploying the development environment as a non-local server will require an additional environmental variable be set:

DEPLOYED=true

This will configure various things to behave normally in a deployed scenario.

Running Test Suite

Initialize the test database:

$ RAILS_ENV=test bundle exec rake db:schema:load db:seed cortex:core:db:reseed
$ RAILS_ENV=test bundle exec rake cortex:rebuild_indexes

To run Ruby and JS specs, utilize:

$ RAILS_ENV=test bundle exec rake spec
$ RAILS_ENV=test bundle exec rake spec:javascript

API

Documentation

Cortex's live API documentation is available via Swagger. This contains specific endpoints, parameters, and response models.

SwaggerUI is provided at http://docs.api.cbcortex.com/.

Swagger Endpoints are available at http://api.cbcortex.com/api/v1/swagger_doc.json.

Consuming Cortex

Authorization

Cortex's API utilizes OAuth2 for Authentication and Authorization. Client Credentials and Authorization Code grant types are supported. Want to get up and running quickly with OAuth? Use Cortex's Ruby client or OmniAuth strategy for Client Credentials and Authorization Code grants, respectively.

Before an application can consume any data, OAuth credentials must be created for the consuming application in the 'Applications' section of the Cortex admin interface.

Content

Content can be consumed from a feed or via the resource's endpoint directly. Use the cortex-client gem to easily consume any content resource and use it in your application.

Localizations

Localizations can be consumed via the client or via i18n-backend-cortex, which allows easy localization for Rails applications.

Exceptions

If a consuming or companion application would like to produce Cortex-equivalent exceptions, use the cortex-exceptions gem.

Applications Using Cortex

Advice and Resources - Simple Jobseeker Resources platform built atop the Consumer Web site utilizing Legacy Cortex Posts and Rails. Content will eventually be dynamically dispersed across site (result pages, description pages, etc) Live Site
Employer - Redesigned Employer Marketing platform utilizing Legacy Cortex Webpages/Snippets and Rails. Live Site
CB1 Lander Shell - Platform for hosting lander pages and experiments, utilizing Legacy Cortex Posts and Sinatra. Live Site
CareerBuilder.com - The main Consumer Web site for CB.com uses Legacy Cortex Posts for the Privacy and Terms of Service pages.

Troubleshooting

For OS X / homebrew users: Run which node to ensure node is properly linked. The path shown should match homebrew's default installation path (run which brew to reveal this). If its not, then run brew link node and follow the instructions.

Contributing

Anyone and everyone is encouraged to fork Cortex and submit pull requests, propose new features and create issues.

Review CONTRIBUTING for complete instructions before you submit a pull request or feature proposal.

License

Cortex utilizes the Apache 2.0 License. See LICENSE for details.

vikksr/cortex