We are so excited you are here and ready to get started with ContentBox Modular CMS one of the most modern ColdFusion (CFML) Content Management Platforms. __ There are several ways to install ContentBox, so make sure you explore all the options.

• Deploy the source using the CommandBox Server with a supported modern ColdFusion (CFML) engine.

• Deploy the source to any modern ColdFusion (CFML) engine (Adobe 11+ †, Lucee4.5+)

• Leverage the ContentBox.war and deploy to any Java enabled server

• Run an express self-contained version

• Install into an Existing ColdBox MVC application

• Run as a docker container: https://hub.docker.com/r/ortussolutions/contentbox/

So let's get started.

† There is a known compatibility issue in Adobe ColdFusion 2018 Update 3 which has been raised with Adobe.

Let's get started with some system requirements for running ContentBox sites:

Java

ContentBox will run in any Java 1.7+ enabled servlet container as a WAR or self-contained express edition.

ColdFusion (CFML) Engine

ContentBox source can be also be deployed to the following ColdFusion CFML engines:

• Adobe ColdFusion 11+

• Lucee 4.5+

Databases

ContentBox can run on any database engine that Hibernate ORM supports (https://developer.jboss.org/wiki/SupportedDatabases2), but we officially support the following:

• MySQL 5+ (InnoDB ONLY!)

• Microsoft SQL Server 2008+

• Oracle 11g+

• Hypersonic

• H2

• Apache Derby

• PostgreSQL (Experimental)

If you have another database engine that needs ContentBox support, please let us know and we will be able to help you (https://www.ortussolutions.com/contact).

IMPORTANT: Dialect Choice

We would highly recommend that you choose the dialect of choice for your database via the Application.cfc in ContentBox. This would avoid you pains and headaches as sometimes Hibernate will not detect the database correctly. The available dialects can be found here: https://helpx.adobe.com/coldfusion/developing-applications/coldfusion-orm/configure-orm/orm-settings.html.

Example Code

this.ormsettings = {
    dialect = "MicrosoftSQLServer
};

Dialects We Support

• Derby

• PostgreSQL

• MySQL

• MySQLwithInnoDB

• MySQLwithMyISAM

• Oracle10g

• MicrosoftSQLServer

MSSQL Caveats

If you are running MSSQL server then we would recommend you update the Application.cfc with the ORM dialect for MSSQL. We have seen many weird dialect issues with MSSQL if this is not done:

this.ormsettings = {
    dialect = "MicrosoftSQLServer
};

We have also seen an issue where an error will be reported that cbPermission cannot be inserted. This is an issue where for some reason the JDBC driver will switch context and create the tables in the master schema and not the schema you chose. So please verify that the master schema has tables that start with cb_* and remove them and re-run the installer.

MySQL Caveats

If you are running MySQL server with MyISAM as your default table engine, you will need to either make the default InnoDB or use the InnoDB dialect. You can do this by adding a dialect section to the ORM settings in the Application.cfc: dialect = "MySQLWithInnoDB"

this.ormsettings = {
    dialect = "MySQLWithInnoDB
};

PostgreSQL Caveats

We have seen some issues on some versions of PostgreSQL where Boolean values of numerical 1 and 0 are not been translated correctly. If this is the case in your version of PostgreSQL you will see some cannot cast Boolean to Integer exceptions. If this is the case please contact us and we will show you how to update your installation to allow for these conversions.

URL Rewriting

ContentBox relies on Search Engine Safe (SES) URLs and URL Routing. The majority of CFML engines already allow for these types of URLs out of the box and ContentBox supports it out of the box. However, if you would like to use full URL rewriting (which we recommend, that's where the index.cfm is not showing in the URLs) you will need to use a web server rewriting tool and ContentBox will configure it for you. So before you install Contentbox make sure that you are using one of the supported rewriting engines show below:

• CommandBox Server

• Apache mod_rewrite

• IIS 7 rewrite module

• Tuckey rewrite filter

• Nginx

The ContentBox installer will create rewrite files automatically for you for Apache, IIS7 and express editions. For Nginx or other rewrite engines you will need to add the rewrites yourself and then manually modify the routing file.

ContentBox 4.0+

Edit config/Router.cfc and set setFullRewrites to true. That's it!

function configure(){
    // Configuration
    setValidExtensions( 'xml,json,jsont,rss,html,htm,cfm,print,pdf,doc,txt' );
    // Process Full Rewrites then true, else false and an `index.cfm` will always be included in URLs
    setFullRewrites( true );

    // Mappings
    route( ":handler/:action" ).end();
}

Older Versions of ContentBox

Edit config/routes.cfm and remove any reference to index.cfm. That's it!

// Base URL
if( len(getSetting('AppMapping') ) lte 1){
    // Remove the index.cfm
    setBaseURL("http://#cgi.HTTP_HOST##getContextRoot()#/index.cfm");
} else {
    // Remove the index.cfm
    setBaseURL("http://#cgi.HTTP_HOST##getContextRoot()#/#getSetting('AppMapping')#/index.cfm");
}

File Permissions

ContentBox needs some files/folders to be writable at runtime. We use this for our installer, ForgeBox cloud deployments, auto-updates and more. The following directories need read/write permissions for the installer only to work:

Installer

{Root}/Application.cfc
{Root}/config/ColdBox.cfc
{Root}/coldbox/system/aop/tmp

Engine

Here are the folders for the core engine to work accordingly

# Engine Operation (REQUIRED)
{Root}/coldbox/system/aop/tmp

# Media Manager
{Root}/modules_app/contentbox-custom/content

# Auto-udpates
{Root}/modules/contentbox/updates

# If you want ForgeBox enabled downloads
{Root}/modules_app/contentbox-custom/_modules
{Root}/modules_app/contentbox-custom/_themes
{Root}/modules_app/contentbox-custom/_widgets

You can also deploy ContentBox to any Java enabled servlet container by downloading our ContentBox war file.

Step 1: Download WAR

The first step is for you to download ContentBox (https://www.ortussolutions.com/products/contentbox) or you can use the command below:

# stable
wget https://www.ortussolutions.com/parent/download/contentbox?type=war

# bleeding edge
wget https://www.ortussolutions.com/parent/download/contentbox?type=war&version=be

Step 2: Deploy WAR

Drop the war into the web application folder of your favorite servlet container or use any of their deployment tools to do so. Then startup the engine and let the war be expanded.

Step 3: Create Your Database

Now that the war is deployed in your server, it is time to create your database in your favorite DBMS engine. ContentBox is built with Hibernate ORM technology, so in theory it should work in all major database systems. You can even use an embedded database like Apache or Hypersonic.

Make sure your database supports utf-8 or utf-16 character sets if you will be using multi-lingual or localization support.

Step 4: Create A Datasource

You can now visit your application and will be presented with our datasource wizard. You can either use our datasource wizard or you can create the datasource yourself manually in the CFML administrator by visiting the URL for the administrator:

/{appcontext}/lucee/admin/server.cfm

Step 5: Run ContentBox Installer

That's it! We are now ready to run the ContentBox installer wizard. ContentBox will automagically create all the necessary database tables, indexes and constraints for you. After it does this, it will present you with our ContentBox installer, where you will fill in:

• Administrator Account

• Site Information

• Notification Emails

• Email Information

• URL Rewriting

• Enjoy your ContentBox installation!

In this section you will install ContentBox by using the source download option and deploy it to your favorite ColdFusion (CFML) engine of choice.

Step 1: Download Source

The first step is for you to download the ContentBox installer () or you can use the command below:

Expand the archive into your web root or a sub folder of your favorite CFML engine.

Please also note that you can also download two more types:

1. Module - The ContentBox module so you can deploy into any existing ColdBox application

1. Site - A pre-configured site like the installer but with no DSN Creator and ContentBox Installer

Step 2: Create Your Database

Now that the source is deployed in your webserver, it is time to create your database in your favorite DBMS engine. ContentBox is built with Hibernate ORM technology, so in theory it should work in all major database systems. You can even use an embedded database like Apache or Hypersonic.

Make sure your database supports utf-8 or utf-16 character sets if you will be using multi-lingual or localization support.

Step 3: Create A Datasource

You can now visit your application and will be presented with our datasource wizard. You can either use our datasource wizard or you can create the datasource yourself manually in the CFML administrator.

Datasource Creation Wizard

The datasource wizard requires your CFML Admin Password, or your ( Railo/Lucee ) Web Context Password to create the datasource.

Note: Depending on your CFML Engine Install, the Web Context Password might not be set. To use the Datasource Creator Wizard, you will be required to access the admin, set the password, then continue the installation.

Step 4: Run ContentBox Installer

That's it! We are now ready to run the ContentBox installer wizard. ContentBox will automagically create all the necessary database tables, indexes and constraints for you. After it does this, it will present you with our ContentBox installer, where you will fill in:

• Administrator Account

• Site Information

• Notification Emails

• Email Information

• URL Rewriting

• Enjoy your ContentBox installation!

ContentBox sports automatic updates via the administrator panel Dashboard > Updates. You can connect to the following update channels:

• Stable: Where all our official stable releases go

• Bleeding Edge: This is where we release beta or test versions

Once an auto-update package is detected you can then opt to install it.

As with all automated installers, we recommend you create backups of your source and database before applying or at least testing in a staging or development version of your site.

Database Migrations

ContentBox contains Database migrations for you. It will only do additive migrations, so no remove or dropping ever occurs on patches. We highly advice you to do so and point you in the right direction via the release notes.

Manual Uploading Patches

Once a patch is released in our update sites you can then choose to manually download the patch and apply it manually yourself. We store all patches in our integration server that can be found here:

Patch Types

There are three types of patches you can manually download and apply:

• Full Patch: Includes source, framework and database content updates

• Database Patch: Includes database content updates only

• No ColdBox: Includes source and database content updates only

Patch Structure

Each patch contains the following structure:

• Update.cfc : Contains the code needed for pre and post installation procedures

• deletes.txt : Contains a list of all source files that will be removed from your installation

• patch.zip : Contains all the new or modified source files that need to be deployed

  You can then use the upload patch functionality in our Updates panel to upload the patch and install it.

We do not recommend running the Update.cfc or patch files manually. Let the installer do its job.

Manual Downloading Patches

You can also use the Updates panel to point to a download URL so ContentBox can be patched via a patch URL. This functionality is mostly used by our support customers so we can deliver on-demand patches to their ContentBox instances. You can also use this approach to deliver patches to a local intranet of ContentBox instances. Just type in the download URL and hit update!

CommandBox Updates

If you are using the contentbox module approach via CommandBox, you can easily upgrade by doing two things:

1. Issue an update command: box update contentbox. This will update the module to its latest version

2. Apply the db-only patch in your administrator

Then restart your engine.

Professional Updating

The ContentBox team can also do the heavy lifting for you as we are a professional open source project. So just contact us and we will update or install any ContentBox instances in a secure and fast way!

The express version of ContentBox is a fully embedded running server powered by , an open source CFML engine, and Tomcat. It comes bundled with a JRE for your operating system or one without a JRE can be downloaded as well.

Requirements

Make sure your system has a working Java Runtime 1.7+ environment if you are downloading the express version with no JRE. A quick test to see if your system supports Java is to open a terminal or command prompt and typing:

You should see something like this:

Just make sure what it is Java 1.7+.

Step 1: Download Express

The first step is for you to download ContentBox () or you can use the command below:

Once downloaded expand the archive

This will expand into the folder of your liking.

Step 2: Permissions

On some operating systems like Linux or Mac, you will need to enable run permissions. So drop into a shell or terminal in that folder you expanded and type:

This will add execution and write permissions to the bin folder which is required.

Step 3: Run it

Go into the bin folder and and execute either the startup.bat or startup.sh or startup.app according to your OS. Then visit the site in a browser on port 8085 by default.

Step 4: Setup Server Passwords

Make sure you visit the following URLs and setup a server and web application password for the underlying engines:

Step 5: Create A Datasource

You can now visit your application under http://localhost:8085 and you will be presented with our datasource wizard. Since we are in express edition, just choose the embedded database and follow the instructions.

Step 6: Run ContentBox Installer

That's it! We are now ready to run the ContentBox installer wizard. ContentBox will automagically create all the necessary database tables, indexes and constraints for you. After it does this, it will present you with our ContentBox installer, where you will fill in:

• Administrator Account

• Site Information

• Notification Emails

• Email Information

• URL Rewriting

• Enjoy your ContentBox installation!

Changing the Default Port

Go to the conf/server.xml and look for the following:

Just update the port to whatever you desire.

is a ColdFusion (CFML) Command Line Interface (CLI), REPL, Package Manager and Embedded Server. We will leverage the CLI in CommandBox to install, deploy and configure ContentBox. The full CommandBox installation instructions can be found here: . We will do the short version.

Download CommandBox

1. No Java Runtime (30mb)

2. Embedded Runtime (80mb)

Starting CommandBox

Once you download and expand CommandBox you will have the box.exe or box binary, which you can place in your Windows Path or *Unix /usr/bin folder to have it available system wide. Then just open the binary and CommandBox will unpack itself your user's directory: {User}/.CommandBox. This happens only once and the next thing you know, you are in the CommandBox interactive shell!

We will be able to execute a-la-carte commands from our command line or go into the interactive shell for multiple commands. We recommend the interactive shell as it is faster and can remain open in your project root.

Creating A ContentBox Site

Now that we have CommandBox we can use it to install and startup a ContentBox site using the embedded server (Lucee 5.x). You can use an embedded database or connect the embedded server to any database server as well.

Code Installation

Open a CommandBox shell in your directory of choice by typing box or executing the box binary and after the welcome screen type the following commands:

ORM Dialect (Optional)

Open the Application.cfc and look for the orm settings especially the dialect setting. Uncomment it and update it accordingly:

• Derby

• PostgreSQL

• MySQLwithInnoDB

• Oracle10g

• MicrosoftSQLServer

Start the Server

Go back to the shell where you installed the code and run:

The server will be created and started for you using the latest Lucee version. A browser window should pop up after and you can run the installer.

Setup Admin Password

Once you start the engine make sure you log in to the CFML web admin using the URL below in order to setup the CFML engine password. You will need this password to create the datasource via the wizard.

This will install the latest stable ContentBox and run an embedded server (Lucee 5.x) for it. After this you will get the ContentBox installer. Just follow it through.

ColdFusion Engine of Choice

Since we are leveraging CommandBox, you can replace the server start command to use any version of Lucee or Adobe ColdFusion. Below are some choice for the engines we support:

Custom Datasources

To change the datasource you can go into the CFML engine administrator and change it. Just look in your taskbar for an Ortus Logo like the one below:

Click on open server admin and go into the datasources section and create one.

Installation Slugs

ContentBox is partitioned into three installation slugs from ForgeBox in order to allow for more flexible installation structures. We used the installer above, but you can use the following approaches as well:

1. contentbox - Installs ContentBox as a module into any existing ColdBox application.

2. contentbox-site - Installs a new ColdBox site enabled for ContentBox with a dependency on contentbox for its module but no installer or DSN creator are installed.

3. contentbox-installer - Same as above but with our DSN Creator and Installer Module available.

If you already have a ColdBox application and you wish to install ContentBox into it, you most definitely can.

System Requirements

Please note that ContentBox 4.x requires ColdBox 5.x

Step 1 : Dependencies

Since version 3.5.0, you can now simply issue a command in CommandBox to install the ContentBox module into an existing ColdBox application. Just open a box shell in the root of your ColdBox application and use the following command:

This will install the ContentBox module with all of its dependencies under the /modules/contentbox and the ContentBox installer module under /modules/contentbox-installer.

Step 2 : Application.cfc Updates

Now open your Application.cfc and you will add the following updates:

Mappings

ORM Settings

Step 3 : ColdBox.cfc Settings

Open your application's ColdBox.cfc and you will add the following settings:

That's it! Once all those settings, mappings and module installations are done you can now visit the installer module to continue with the installation process: http://localhost/index.cfm/cbinstaller

Step 4: CacheBox.cfc Settings

Open your CacheBox configuration file: config/CacheBox.cfc and add the following cache declarations:

Once these updates are done, then you can start up the server and visit the installer URL: http://localhost:port/cbInstaller

Step 5 (Optional) : UI Route

By default ContentBox is in take over mode. Meaning that the UI module will intercept all calls made to the application and process them as pages or blog entries. If you DO NOT want this to happen, then you can segregate the UI module into a single entry point URL like blog or site or pages. You can do this by opening the following file: modules/contentbox-ui/ModuleConfig.cfc and looking for the following code:

Now update the this.entryPoint to whatever you like the entry point URL to be. Restart the application and voila!

ContentBox sports its very own . As with the , the [major].[minor].[patch] versioning mirrors the upstream product version, so it's easy to pull deploy a specific version, should your application require it.

Playing around

CommandBox Image Features

Persisting Data Between Restarts

The above run command produces an image which is self-contained, and would be destroyed when the container is stopped. If we wanted to run a version in production, we would need to persist, at the very minimum, the database and your custom assets (widgets, modules, themes and media library). In order to do this we need to mount those resources in to the Docker host file system.

By convention, the express H2 database is stored at /data/contentbox/db inside the container. In addition, the custom content module which contains your custom themes, widgets, modules and media library are stored under /app/modules_app/contentbox-custom.

Mountable Points

Let's mount both of those volume points, so that our database and user assets persists between restarts:

Now, once our image is up, we can walk through the initial configuration. Once configuration is complete, simply stop the container and then start it without the environment variable INSTALL in place. The H2 database and uploads will be persisted and the installer will be removed automatically on container start.

INSTALL Setting Caveats

Please remember that the INSTALL environment variable is ONLY used to go through the ContentBox installer wizard. Once the database is seeded with the installation process, you will no longer use it unless you want to reconfigure the installation.

Custom Database Configuration

If you would like to connect your container to an external database system, you can very easily do so, which would allow us to connect from multiple containers in a distributed fashion (MySQL, Oracle, MSSQL, etc). If not, you run the risk of file locks if multiple container replicas are sharing the same H2 database.

To programmatically configure the database on container start, environment variables which represent your datasource configuration should be provided. There are two patterns supported:

1. DB_DRIVER configuration - which may be used for Adobe Coldfusion servers

2. DB_CLASS configuration - which configures a datasource by JDBC driver and connection string (Both Adobe and Lucee)

An example container run command, configuring a MySQL database would be executed like so:

To use the DB_DRIVER syntax for Adobe Coldfusion, an example run command would be:

Granular Environmental Control

A number of environment variables, specific to the ContentBox image, are availabe for use. They include:

• INSTALL=true (alias: INSTALLER) - Adds the installer module at runtime, to assist in configuring your installation. You would omit this from your run command, once your database has been configured

• BE=true - Uses the bleeding edge snapshot of the ContentBox CMS, else we will defer to the latest stable version of ContentBox.

• HEALTHCHECK_URI - Specifies the URI endpoint for container health checks. By default, this is set http://127.0.0.1:${PORT}/ at 30s intervals with 5 retries and a timeout of 60s

• FWREINIT_PW - Allows you to specify the reinit password for the ColdBox framework

• DISTRIBUTED_CACHE - Allows you to specify a CacheBox cache region for distributing ContentBox content, flash messages, cache storage, RSS feeds, sitemaps and settings. There are only three cache regions defined in this image: default, template and jdbc. jdbc is the default cache that will distribute your data, default and template are in-memory caches. Please see the distributed caching section below to see how to register more caches.

• H2_DIR - Allows you to specify a custom directory path for your H2 database. By convention, this is set to /data/contentbox/db within the container

• ORM_SECONDARY_CACHE - If true it will activate the ORM secondary cash to the ehcache provider. By default it is turned off.

• ORM_DIALECT - You can choose the specific ORM dialect if needed, if not we will try to auto-detect it for you.

• HEADLESS=false - If true then this image will not publish an Admin module, just the core, REST and UI modules.

Automatic Session Distribution

By default, the ContentBox image will use the Lucee Open Source CFML engine for running the application. It will also configure the datasource to store user sessions so you can easily scale the image or send it to Docker Swarm, Kubernetes, etc for scalability.

You can also use the SESSION_STORAGE environment variable to switch the connection to any backend you like.

Distributed Caching

By default, our image configures a jdbc CacheBox cache region that will be used to distribute settings, sessions, flash data, content, RSS feeds, sitemaps, etc. This means that out-of-the-box, your ContentBox containers can use the database to distribute its content within a swarm or set of services. However, if you would like to use your own CacheBox providers or a more sophisticated distributed cache like Redis or Couchbase, you can.

Healthchecks

The image contains built-in capabilities for healthchecks for the running application. You can customize the URL entry point by using the HEALTHCHECK_URI environment variable. By default, this is set http://127.0.0.1:${PORT}/ at 30s intervals with 5 retries and a timeout of 60s.

In Short

The ContentBox image for Docker re-vamps the entire Modular CMS game by de-coupling your customizations and user assets from the underlying framework. It can makes your source code lighter-weight, as well as providing you with a standardized development environment, which matches your production container strategy.