Manual Setup

cortex-starter Preparation

As cortex itself is only a Rails Engine, it needs to be mounted within a parent Rails applicaton. cortex-starter serves as a starting point for new users, with cortex and cortex-plugins-core already mounted and configured with several example ContentTypes/Decorators. Start by cloning the repository:

$ git clone && cd cortex-starter


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 $ bin/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.




  • 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


  • 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 repositories for APT or RPM or follow these manual instructions. The same goes for phantomjs. Build from source or use a PPA. Additionally, yarn will need its repository added for these distributions. Follow these instructions. Other Linux distributions likely have these as prebuilt packages in their official or user repositories.

  • Install Ruby via rbenv or rvm.

  • Enable & start system agents using your distribution's service manager frontend, which is likely systemd's frontend, systemctl:

$ systemctl enable --now postgresql elasticsearch redis


  • Install Bundler and its dependencies:

$ gem install bundler && bin/bundle install
  • Install node dependencies using yarn:

$ bin/yarn install

Data Provisioning


cortex-starter ships with an automated setup script. Execute this in lieu of the Manual Setup steps below, if you're comfortable doing so:

$ bin/setup


  • Create databases:

$ bin/rails db:create
  • Initialize the schema:

$ bin/rails db:schema:load
  • Seed database with a top-level tenant, the superuser and Custom Content data, then rebuild the Elasticsearch index:

$ bin/rails db:seed
$ bin/rails cortex_starter:content_types:seed
$ bin/rails cortex:rebuild_indexes


Start Cortex, Sidekiq and live Webpack rebuild via Foreman with the dev-server script:

$ bin/dev-server

The admin interface should now be accessible locally at http://localhost:3000. To access Cortex as superadmin, login as with password welcome1.

Last updated