# 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](https://github.com/cortex-cms/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:

```bash
$ git clone git@github.com:cortex-cms/cortex-starter.git && cd cortex-starter
```

## 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 `$ 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.

## Dependencies

### System

#### macOS

* Install the Xcode Command Line tools:

```bash
$ xcode-select --install
```

* Install all Cortex system-wide dependencies (and the `readline` Ruby/`byebug` build dependency) using [Homebrew](http://brew.sh/) from the `Brewfile` via `$ brew install $(cat Brewfile|grep -v "#")`
* Install Ruby via [rbenv](https://github.com/sstephenson/rbenv) or [rvm](https://rvm.io/).
* Enable system agents:

```bash
$ 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`:

```bash
$ brew services start postgresql
$ brew services start elasticsearch
$ brew services start redis
```

or `launchctl`:

```bash
$ 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`:

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

{% hint style="info" %}
Ubuntu and Redhat/Fedora do not have an official `elasticsearch` package - you must use Elasticsearch's repositories for [APT](https://www.elastic.co/guide/en/elasticsearch/reference/current/deb.html) or [RPM](https://www.elastic.co/guide/en/elasticsearch/reference/current/rpm.html) or follow these [manual instructions](https://www.elastic.co/guide/en/elasticsearch/reference/current/_installation.html). The same goes for `phantomjs`. Build from [source](http://phantomjs.org/download.html) or use a [PPA](https://launchpad.net/ubuntu/+ppas?name_filter=phantomjs). Additionally, `yarn` will need its repository added for these distributions. Follow these [instructions](https://yarnpkg.com/lang/en/docs/install). Other Linux distributions likely have these as prebuilt packages in their official or user repositories.
{% endhint %}

* Install Ruby via [rbenv](https://github.com/sstephenson/rbenv) or [rvm](https://rvm.io/).
* Enable & start system agents using your distribution's service manager frontend, which is likely `systemd`'s frontend, `systemctl`:

```bash
$ systemctl enable --now postgresql elasticsearch redis
```

### Application

* Install Bundler and its dependencies:

```bash
$ gem install bundler && bin/bundle install
```

* Install `node` dependencies using `yarn`:

```bash
$ bin/yarn install
```

## Data Provisioning

### Quick

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

```bash
$ bin/setup
```

### Manual

* Create databases:

```bash
$ bin/rails db:create
```

* Initialize the schema:

```bash
$ bin/rails db:schema:load
```

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

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

## Server

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

```bash
$ bin/dev-server
```

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cortexcms.org/basics/setup/manual-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.