Skip to content

2. Installation

Jump to bottom
Chris Troutner edited this page May 22, 2017 · 17 revisions

Update 5/22/17

The documentation here is no longer being maintained. Documentation has been incorporated into the repository under the /public/documentation directory. You can view it online here.

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

  1. Clone the Live Demo
  2. Build from Source

Table of Contents

Cloning the Live Demo

ConnextCMS has been developed for operation on a Digital Ocean Droplet. 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

  2. Request a ConnextCMS Droplet Image

  3. Change directory into the connextCMS directory and update the repository by executing git pull.

  4. Execute the two scripts with these commands:

  5. ./copy-keystone

  6. ./merge-connextcms-keystone

  7. Start ConnextCMS with these commands:

  8. cd ~/myCMS

  9. npm install

  10. node keystone.js &

You will receive a message on the command line informing you that KeystoneJS has started. You can now navigate to the IP address of your Droplet with a web browser and view you live version of ConnextCMS/KeystoneJS!

Building From Source

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 this 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 &

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. On the clone, 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 plugin template to better isolate your code projects from one another.

Customizing Your Installation

The instructions below provide tips for further customizing ConnextCMS to your needs.

Configuring the Superuser Account

ConnextCMS and KeystoneJS now have different schemes for setting up administrators. KeystoneJS uses an isAdmin field in the user model. ConnextCMS assigns SuperUser and Admin roles by copying the GUID associated with a user account into the Site Settings view.

When you first log into KeystoneJS on your cloned copy of ConnextCMS using the default user@keystonejs.com/admin login, ConnextCMS won't be able to identify you yet as a superuser. By default that account only has 'admin' permissions and the system will send you to the ConnextCMS dashboard.

After the ConnextCMS dashboard comes up, open a developer console in your web browser. Get your user ID by typing userdata into the console and hit enter. Locate the _id property. Here is a screenshot illustrating how to pull up a developer console in Chrome and look up this data.

Superuser config

The string of characters assigned to the '_id' is called a GUID. Open the file /public/js/publicsettings.json. Near the bottom you'll see the field superUsers. Add your GUID to the array. Here is an example:

{
  "keyNames": ["privatePagesSection", "superUsers", "adminUsers"],
  "keyDisplay": ["Private Page Section ID", "Super User IDs (CSV)", "Admin User IDs (CSV)"],
  
  "privatePagesSection": "",
  "superUsers": ["58472dda8783bc56570f090f"],
  "adminUsers": []
}

You can now restart the keystone.js program and the system will identify the user@keystonejs.com/admin login as a superuser. Once the system knows the GUID, you can change the name, login, and password of that user and ConnextCMS will still identify that user account as a superuser.

The Site Settings View

Version 0.00.07 introduced the Site Settings view, as shown below. Two menu items, Site Settings and the Keystone Admin UI appear only for superusers. The latter will take you to the Keystone Admin UI. The Site Settings link will open the Site Settings view where you can set up Mailgun, assign admin and super user permissions, and add other site-wide settings.

Site Settings View

The input fields in the Site Settings view are generated from two JSON files: /private/privatesettings.json and /public/js/publicsettings.json. Each file generates its respective sections in the Site Settings view. New fields can be added by editing the keyNames and keyDisplay arrays in those files.

As the file names indicate, the publicsettings.json file is publically accessible and is frequently used by front end JavaScript. The data in the privatesettings.json file however is only accessible through the /api/serversettings/getprivate API, which can only be accessed by super users. This private file is the best place to put sensitive information like API security keys.

How to Customize the Home Page

  • As shown in this video, the primary file that controls the home page is /connextCMS/templates/views/index.hbs. Although the the extension of this file is '.hbs' you can treat it like an HTML file. .hbs is the extension for a Handlebars template.

  • There is also the /connextCMS/templates/views/layouts/default.hbs that contains the header and footer, and it wraps all other .hbs files (including index.hbs). This file controls the main navigation menu on the front end and calls the JavaScript file /connextCMS/public/js/navMenu.js which generates the navigation menu, reflecting the Sections and Pages created in ConnextCMS.

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 program will require special permissions within the operating system in order to run 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.

  1. First, ensure you have a user with sudo privileges. For the purposes of this example, we'll use the default 'demouser' that comes with the ConnextCMS clone.

  2. 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.

  3. Give node permission to run applications on port 80 by running the following commands:

  4. sudo apt-get install libcap2-bin

  5. sudo setcap cap_net_bind_service=+ep /usr/bin/nodejs

  6. Now setup PM2 to run as a startup service by executing this command:

  7. sudo env PATH=$PATH:/usr/bin pm2 startup -u demouser

  8. 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.

  9. Start KeystoneJS with PM2:

  10. cd ~/connextCMS

  11. ./merge-connextcms-keystone

  12. cd ~/myCMS

  13. pm2 start keystone.js

  14. Instruct PM2 to run these applications should the server reboot: pm2 save

Clone this wiki locally