Overview

What is ConnextCMS?

ConnextCMS.com is a front end extension for KeystoneJS. It uses the Backbone.js framework to structure the code and Require.js to modularize it (Here's a great book on both). The client side code interacts with KeystoneJS via a REST API, allowing development and debugging of your Content Management System (CMS) to take place in the browser. The main features include:

  • Local File and Image Hosting
  • Automatic Image Resizing
  • Email routing with Mailgun
  • Debugging & Development in the Browser
  • JavaScript Homogeneity: JavaScript is the only programming language running the website.

This video gives an overview of the major concepts behind ConnextCMS. You can view more videos about ConnextCMS here.

Installation

This page describes the three ways of installing ConnextCMS on your own server:

  1. Clone the Live Demo
  2. Use the Docker image
  3. Build from Source

Cloning the Live Demo

ConnextCMS has been developed for operation on a Digital Ocean Droplet or similar Ubuntu Linux server. A fully operational server with both ConnextCMS and KeystoneJS installed has been prepared for those interested in trying out the software. You'll need to create a Digital Ocean account in order to receive a copy of the Droplet. By singing up with this affiliate link, you will recieve a $10 credit to your account. The $5/month Droplet is more than capable of running a website.

  1. Create a Digital Ocean Account (DO account)
  2. Request a ConnextCMS Droplet Image
  3. You'll be sent an email when the image is transferred to your DO account.
  4. Log into DO and Create a new Droplet from the image transfered into your account.
  5. Thats it! You're new server will automatically boot up with ConnextCMS running on port 80 and port 3000. To customize your site, edit the files in ~/docker-connextcms/theme/site-template-connextcms. Read more about [the site-template here](https://github.com/skagitpublishing/site-template-connextcms).

The demo droplet is pre-configured to launch the Docker container at boot up. Nginx is also installed and pre-configured to serve the site on port 80. You can follow the instructions here to learn how to configure Nginx with an free SSL certificate from Let's Encrypt.

Use the Docker Image

Because the installation of KeystoneJS and ConnextCMS is so complex for beginners, the project has focused on using Docker containers to manage the complexity and provide a consistent installation experience. A Docker Compose file has been created that allows installation with a few simple commands. Please read the installation instructions in the docker-connextcms GitHub repository. This is the same Docker image used to generate the demo droplet.

Build from Source (Advanced)

Before installing ConnextCMS, you will need an operational copy of KeystoneJS. You can follow the KeystoneJS Getting Started Guide or the instructions on the KeystoneJS GitHub Page.

After you get KeystoneJS running successfully, installing ConnextCMS consists of the following steps. It's assumed that you are running on Ubuntu or similar *nix flavor of operating system:

  1. Rename the directory with the KeystoneJS installation to keystone4.
  2. Clone the ConnextCMS repository with the command git clone https://github.com/skagitpublishing/ConnextCMS and rename the newly created directory ConnextCMS to connextCMS.
  3. Execute the two script files in the ConnextCMS directory with the commands ./copy-keystone and then ./merge-connextcms-keystone. This will create a new directory called myCMS that contains the combined code of KeystoneJS and ConnextCMS.
  4. Change directory to myCMS. Install the node dependencies for ConnextCMS by running npm install.
  5. Start KeystoneJS with node keystone.js &

Run on Port 80

Port 80 is the normal http port used to serve webpages. Calling http://ConnextCMS.com is the same thing as calling http://ConnextCMS.com:80. If you clone the demo droplet, your installation will already be configured to use Port 80. If you build from source, you'll need to follow these instructions.

By default KeystoneJS runs on Port 3000. The Docker container assumes you will use Nginx to proxy port 80 to port 3000. If you do not want to use Nginx, node will need special permissions to run keystone.js on port 80. The instructions below assume you are running the software on a Digital Ocean Droplet running Ubuntu Linux OS.

The instructions below are modified from this Digital Ocean tutorial on using PM2.

  • First, ensure you have a non-root user with sudo privileges. For the purposes of this example, we'll use the default 'demouser' that comes with the ConnextCMS clone.
  • Second, install PM2 with the following command sudo npm install -g pm2. PM2 will restart your application as a service when the server reboots or if your software crashes.
  • Give node permission to run applications on port 80 by running the following commands:
    • sudo apt-get install libcap2-bin
    • sudo setcap cap_net_bind_service=+ep /usr/bin/nodejs
  • Now setup PM2 to run as a startup service by executing this command:
    • sudo env PATH=$PATH:/usr/bin pm2 startup -u demouser
  • Modify connextCMS/keystone-files/keystone.js and add the line 'port': 80 to the end of keystone.init() to tell KeystoneJS to operate on port 80 instead of port 3000.
  • Start KeystoneJS with PM2:
    • cd ~/connextCMS
    • ./merge-connextcms-keystone
    • cd ~/myCMS
    • pm2 start keystone.js
  • Instruct PM2 to run these applications should the server reboot: pm2 save

Installation Best Practice

Weather you start your installation from a clone or build from source, it's best to follow the Droplet File Structure and keep your software installations and operational website software in separate directories. In the Docker container, you'll notice that KeystoneJS lives in its own directory keystone4 and ConnextCMS lives in its own directory connextCMS. A third directory, myCMS is created by running the ./copy-keystone and ./merge-connextcms-keystone scripts in the connextCMS directory. These two scripts combine the two software projects.

When creating and customizing your own site, it is best to mimic this setup by creating your own directory. For example, let's call this directory theme. By copying the various files you need to modify from the keystone4 and connextCMS directory and putting them in the theme directory, you can keep the (now) three software projects separate. Copy and modify the ./merge-connextcms-keystone script file to overwrite the files in the myCMS directory with your modified files stored in theme.

By following this scheme, you'll be able to independently update the ConnextCMS and KeystoneJS software and easily merge those updates into your website. You can also create your own git repository in the theme directory that only contains your modified code. No need to copy redundant code from ConnextCMS or KeystoneJS. Copy the site template or plugin template to better isolate your code projects from one another.

File Structure

There are a lot of JavaScript files in a lot of different locations that do a lot of different things. This section maps out the file structure that you'll need to know in order to customize ConnextCMS for you own use. You can also watch this video that shows how to customize the Content Management System.

There are two primary directories:

  • keystone4 contains the KeystoneJS files
  • connextCMS contains the ConnextCMS files (this repository)
Both directories are combined into the myCMS directory, which is the functional directory where code is executed.

Droplet File Structure

Weather you clone the Demo Droplet or build from source, it is recommended that you follow the same file structure scheme used on the Demo Droplet and described in this video. This allows the individual software projects that make up a functional website to each co-exist on their own and be easily combined to make a functional, custom web site or web app.

|--keystone4
|  This is where the KeystoneJS files live.
|  |--node_modules/keystone/
|  |  Executing `git pull` and `npm install` will update KeystoneJS with the latest code from their 'master' branch.
|--connextCMS
|  This is a local copy of the ConnextCMS repo. Execute 'git pull' to get the latest code from the repo.
|  |--copy-keystone
|  |  This script file will delete the myCMS directory, then replace it with a copy of the keystone4 directory
|  |--merge-connextcms-keystone
|  |  This script file will overwrite the KeystoneJS files in the myCMS directory with files from the ConnextCMS repo, resulting in a working copy of ConnextCMS.
|--myCMS
|  This directory contains the working code.
|  |--keystone.js
|  |  This is the file you execute to get ConnextCMS up and running with the command `node keystone.js`
            

Instead of changing the files in the keystone4 or the connextCMS directory directly, the script files in the connextCMS directory combine the files into the myCMS directory. You then run the ConnextCMS software by executing the command node keystone.js in the myCMS directory.

When creating and customizing code for your own website, it is recommended to create a new directory for your own code. You can then create a script file similar to the merge-connextcms-keystone script in the connextCMS directory to merge your code into the myCMS directory. That way all three code repositories (KeystoneJS, ConnextCMS, and your code) can co-exist and are easy to update by executing git pull in their respective directories.

In this scenario, the order of operation (which scripts get run in which order) matters.

KeystoneJS File Structure

Below is a modified version of the file layout structure depicted in the KeystoneJS Getting Started Guide:

|--models
|  Your application's database models
|--public
|  Static files (css, js, images, etc.) that are publicly available`
|--routes
|  |--api
|  |  Your application's api controllers
|  |--views
|  |  Your application's view controllers
|  |--index.js
|  |  Initialises your application's routes and views
|  |--middleware.js
|  |  Custom middleware for your routes
|--templates
|  |--views
|  |  Your application's view templates
|--updates
|  Data population and migration scripts
|--package.json
|  Project configuration for npm
|--keystone.js
|  Main script that starts your application
            

ConnextCMS File Structure

The KeystoneJS file system above is heavily modified to support new models and API routes for ConnextCMS. The models directory contains all of the same default models that come with KeystoneJS. It also includes several new models like FileUploads.js, ImageUploads.js, Page.js, and PageSection.js. The routes/index.js file has also been heavily modified to open up API access to these models. The API interface for each individual model is stored in routes/api.

Because ConnextCMS is a front end Backbone.js application, it also contains an extensive file structure independent of KeystoneJS. The files below make up the ConnextCMS back end. You'll find the files controlling this part of the application as follows:

|--public
|  |--js
|  |  |--cms_common.js
|  |  |  The primary require.js file that is called when the templates/views/dashboard.hbs view is loaded
|  |  |--lib
|  |  |  JavaScript libraries loaded by Require.js and used by ConnextCMS.
|  |  |--app
|  |  |  |--main_dashboard_app.js
|  |  |  |  The main application file that gets loaded and executed first. All other files are loaded after this one.
|  |  |  |--model
|  |  |  |  The Backbone.js models.
|  |  |  |--templates
|  |  |  |  The HTML templates that gets loaded by each Backbone.js view.
|  |  |  |--views
|  |  |  |  The JavaScript files that make up the Backbone.js views.
|  |  |  |--controller
|  |  |  |  Not implemented yet. This is directory may be deleted.