In this section you will deploy ContentBox so it can run on any running Adobe or Lucee CFML engine. The first step is to use CommandBox and our contentbox-cli package so we can install and configure ContentBox for usage in any CFML Engine. We won't be using CommandBox as our server, just as a package manager and CLI.

Install CommandBox

​

​CommandBox 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.

Requirements

• MacOS, Windows or Linux

• JDK 8+

• A clean, empty directory on your machine

Download CommandBox

You can download CommandBox from the official site: http://www.ortussolutions.com/products/commandbox#download and install it in your preferred Operating System (Windows, Mac, Unix).

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

Install ContentBox-CLI

We can now install the contentbox-cli package:

install contentbox-cli

Once installed you can always run contentbox help to get the list of available commands and help information.

Creating Your Database

Create a database in your RDBMS of choice. Make sure you note the name of the database, the connection details and the credentials for it.

Creating Your Datasource

Now go to your CFML engine administrator and register the contentbox datasource that points to the database you just created.

Resources

• https://docs.lucee.org/guides/cookbooks/datasource-define-datasource.html

• https://helpx.adobe.com/coldfusion/configuring-administering/data-source-management-for-coldfusion.html

Creating A ContentBox Site

Now that we have our CLI installed, database and datasource created, go or create a new directory where we will create our site. Most likely this folder will be your web root in your CFML engine installation or a sub-folder within that web root. Let's assume it's the web root of your current CFML Engine installation.

# Create a new directory and go into it.
mkdir mysite --cd
# Run the installer wizard
contentbox install-wizard

The wizard will take you by the hand and ask you all the relevant questions about your installation:

1. Name of your site

2. Which CFML Engine you will be running ContentBox on (Lucee5, Adobe 2018+)

3. Password for the ColdBox HMVC Reinits

4. Database of choice (MySQL5+, MSSQL, PostgreSQL, Oracle)

5. Database credentials

6. Development or production site

7. Latest ContentBox version, specific or be bleeding edge

8. Deploy a CommandBox server or not. This should be false, as we are only deploying our code to the CFML engine we have already installed.

Confirm your settings and the installer will configure the entire site for you including ORM dialects, environment variables and much much more.

Web Installer

Now that we have installed ContentBox on disk and configured your CLI to connect to your database for delivering database migrations, we can finalize the installation via the web installer. Now open the installer by navigating to the root of the project. Let's assume you are running your CFML engine on port 8500:

http://localhost:8500

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!

Let's get started with some system requirements for running ContentBox sites on all deployable options

Java

You need Java 8+ to run ContentBox.

CommandBox

You will need to have CommandBox for installation, upgrading and optionally for running your ContentBox sites. Please see our CommandBox Installation section.

ColdFusion (CFML) Engine

ContentBox can be deployed to the following CFML Engines:

• Adobe ColdFusion

  • 2016 (End of life is December 2021)

  • 2018

  • 2021

• Lucee 5+

Databases

Here are the supported databases for ContentBox:

• MySQL 5.7 (InnoDB ONLY!)

• MySQL 8+ (InnoDB ONLY!)

• Microsoft SQL Server 2012+

• HypersonicSQL

• Apache Derby

• PostgreSQL

• Oracle 11g+

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

Microsoft SQL Caveats

We have 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.

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 (Default)

• 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 Routing Full Rewrite Support

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 );
}

File Permissions

ContentBox needs some files/folders to be writable at runtime.

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

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:

install contentbox,contentbox-installer-module

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

// LOCATION MAPPINGS
this.mappings[ "/contentbox" ] = COLDBOX_APP_ROOT_PATH & "modules/contentbox";
// THE LOCATION OF THE ORM MODULE
this.mappings[ "/cborm" ] = this.mappings[ "/contentbox" ] & "/modules/contentbox-deps/modules/cborm";

ORM Settings

// ORM SETTINGS
this.ormEnabled = true;
this.ormSettings = {
    // ENTITY LOCATIONS, ADD MORE LOCATIONS AS YOU SEE FIT
    cfclocation=[ "models", "modules", "modules_app" ],
    // DO NOT REMOVE THE FOLLOWING LINE OR AUTO-UPDATES MIGHT FAIL.
    dbcreate = "update",
    // FILL OUT: IF YOU WANT CHANGE SECONDARY CACHE, PLEASE UPDATE HERE
    secondarycacheenabled      = false,
    cacheprovider        = "ehCache",
    // ORM SESSION MANAGEMENT SETTINGS, DO NOT CHANGE
    logSQL             = false,
    flushAtRequestEnd             = false,
    autoManageSession            = false,
    // ORM EVENTS MUST BE TURNED ON FOR CONTENTBOX TO WORK
    eventHandling         = true,
    eventHandler        = "cborm.models.EventHandler",
    // THIS IS ADDED SO OTHER CFML ENGINES CAN WORK WITH CONTENTBOX
    skipCFCWithError    = true
};

Step 3 : ColdBox.cfc Settings

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

// ORM Module Configuration
orm = {
    // Enable Injection
    injection = {
        enabled = true
    }
};

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:

// Register all the custom named caches you like here
caches = {
    // Named cache for all coldbox event and view template caching
    template = {
        provider = "coldbox.system.cache.providers.CacheBoxColdBoxProvider",
        properties = {
            objectDefaultTimeout = 120,
            objectDefaultLastAccessTimeout = 30,
            useLastAccessTimeouts = true,
            freeMemoryPercentageThreshold = 0,
            reapFrequency = 2,
            evictionPolicy = "LRU",
            evictCount = 5,
            maxObjects = 5000,
            objectStore = "ConcurrentSoftReferenceStore" //memory sensitive
        }
    },
    // ContentBox Sessions
    sessions = 	{
        provider = "coldbox.system.cache.providers.CacheBoxColdBoxProvider",
        properties = {
            objectDefaultTimeout = 60,
            objectDefaultLastAccessTimeout = 0,
            useLastAccessTimeouts = false,
            freeMemoryPercentageThreshold = 0,
            reapFrequency = 2,
            evictionPolicy = "LRU",
            evictCount = 5,
            maxObjects = 1000, // Can support up to 1000 user sessions concurrently.  Modify if needed. 0 = unlimited
            objectStore = "ConcurrentStore"
        }
    }
}

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:

// YOUR SES URL ENTRY POINT FOR CONTENTBOX, IF EMPTY IT WILL TAKE OVER THE ENTIRE APPLICATION
// IF YOU WANT TO SECTION OFF CONTENTBOX THEN FILL OUT AN SES ENTRY POINT LIKE /site OR /content
// BY DEFAULT IT TAKES OVER THE ENTIRE APPLICATION
this.entryPoint    = "";

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

The express version of ContentBox is a fully embedded running server powered by Lucee, 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:

java -version

You should see something like this:

java version "1.8.0_40"
Java(TM) SE Runtime Environment (build 1.8.0_40-b27)
Java HotSpot(TM) 64-Bit Server VM (build 25.40-b25, mixed mode)

Just make sure what it is Java 1.7+.

Step 1: Download Express

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

# stable no-jre
wget https://www.ortussolutions.com/parent/download/contentbox?type=express
# stable with jre for windows
wget https://www.ortussolutions.com/parent/download/contentbox?type=express-win
# stable with jre for mac
wget https://www.ortussolutions.com/parent/download/contentbox?type=express-mac
# stable with jre for linux
wget https://www.ortussolutions.com/parent/download/contentbox?type=express-linux

# bleeding edge no-jre
wget https://www.ortussolutions.com/parent/download/contentbox?type=express&version=be
# bleeding edge with jre for windows
wget https://www.ortussolutions.com/parent/download/contentbox?type=express-win&version=be
# bleeding edge with jre for mac
wget https://www.ortussolutions.com/parent/download/contentbox?type=express-mac&version=be
# bleeding edge with jre for linux
wget https://www.ortussolutions.com/parent/download/contentbox?type=express-linux&version=be

Once downloaded expand the archive

unzip contentbox-express-{version}.zip

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:

chmod -R 777 bin

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

Step 3: Run it

Go into the bin folder 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 set up a server and web application password for the underlying engines:

# server password
http://localhost:8085/lucee/admin/server.cfm
# web password
http://localhost:8085/lucee/admin/web.cfm

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:

<Connector port="8085" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443" />

Just update the port to whatever you desire.

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. We strongly recommend using our contentbox-cli to install ContentBox as it is the easiest way to get started.

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

Requirements

• MacOS, Windows or Linux

• JDK 8+

• A clean, empty directory on your machine

Download CommandBox

You can download CommandBox from the official site: http://www.ortussolutions.com/products/commandbox#download and install it in your preferred Operating System (Windows, Mac, Unix).

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

Install ContentBox-CLI

The first step in our adventure is to install the contentbox-cli package that will handle installation, scaffolding, and management of ContentBox sites.

install contentbox-cli

Once installed you can always run contentbox help to get the list of available commands and help information.

Creating Your Database

Create a database in your RDBMS of choice. Make sure you note the name of the database, the connection details and the credentials for it. You will need them in the next step.

Creating A ContentBox Site

Now that we have our cli installed, go or create a new directory where we will create our site.

# Create a new directory and go into it.
mkdir mysite --cd
# Run the installer wizard
contentbox install-wizard

The wizard will take you by the hand and ask you all the relevant questions about your installation:

1. Name of your site

2. Which CFML Engine you want to run it on (Lucee5, Adobe 2018+)

3. Password of the CFML engine administrator

4. Password for the ColdBox HMVC Reinits

5. Database of choice (MySQL5+, MSSQL, PostgreSQL, Oracle)

6. Database credentials

7. Development or production site

8. Latest ContentBox version, specific or be bleeding edge

Confirm your settings and the installer will configure the entire site for you including ORM dialects, environment variables and much much more. It will also startup the chosen CFML server so you can continue with the web installer.

Web Installer

The web installer will then take you through adding your first administrator user, email configurations and your production and development site in one box. Once you follow the wizard, ContentBox is up and running! Enjoy!

Starting & Stopping

You can use the CommandBox commands to interact with the embedded server:

• server stop to stop the server

• server start to start the server

• server restart to restart the server

• server log to view the log files

• server help to get help on your server commands

What's Next

You now have a fully functional ContentBox installation with two sites: development and production. You can now start creating your content, themes, modules and much more.

ContentBox sports its very own ContentBox Docker image. As with the CommandBox image, 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

The image is packaged with a self-contained express version, which uses an in-memory H2 database. To stand up an image using an un-configured express edition, simply run:

docker pull ortussolutions/contentbox &&
docker run -p 8080:8080 \
-e EXPRESS=true \
-e INSTALL=true \
ortussolutions/contentbox

A new container will be spun up from the image and, upon opening your browser to http://[docker machine ip]:8080, you will be directed to configure your ContentBox installation using the ContentBox Installer. That easy! Boom!

CommandBox Image Features

The ContentBox image is based on the CommandBox Image, so all features and environment variables are applicable. Please refer to that documentation as well: https://hub.docker.com/r/ortussolutions/commandbox/

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 into 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:

docker run -p 8080:8080 \
-e EXPRESS=true \
-e INSTALL=true \
-v `pwd`/contentbox-db:/data/contentbox/db \
-v `pwd`/contentbox-custom:/app/modules_app/contentbox-custom \
ortussolutions/contentbox

Now, once our image is up, we can walk through the initial configuration. Once the 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.

docker run -p 8080:8080 \
-e EXPRESS=true \
-v `pwd`/contentbox-db:/data/contentbox/db \
-v `pwd`/contentbox-media:/app/includes/shared/media \
ortussolutions/contentbox

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.

The image is configured to allow all ORM-supported JDBC drivers to be configured by specifying the environment variables to connect. Alternately, you may specify a CFCONFIG environment variable which points to a file containing your engine configuration, including data sources.

To programmatically configure the database on container start, environment variables that 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:

docker run -p 8080:8080 \
-e 'INSTALL=true' \
-e 'CFCONFIG_ADMINPASSWORD=myS3cur3P455' \
-e "DB_CONNECTION_STRING=jdbc:mysql://mysqlhost:3306/contentbox_docker?useUnicode=true&characterEncoding=UTF-8&useLegacyDatetimeCode=true" \
-e 'DB_CLASS=org.gjt.mm.mysql.Driver' \
-e 'DB_USER=contentbox_user' \
-e 'DB_PASSWORD=myS3cur3P455' \
-v `pwd`/contentbox-media:/app/includes/shared/media \
ortussolutions/contentbox

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

docker run -p 8080:8080 \
-e 'CFENGINE=adobe@11' \
-e 'INSTALL=true' \
-e 'CFCONFIG_ADMINPASSWORD=myS3cur3P455' \
-e 'DB_DRIVER=MSSQLServer' \
-e 'DB_HOST=sqlserver_host' \
-e 'DB_PORT=1433' \
-e 'DB_NAME=contentbox_docker' \
-e 'DB_USER=sa' \
-e 'DB_PASSWORD=myS3cur3P455' \
-v `pwd`/contentbox-media:/app/includes/shared/media \
ortussolutions/contentbox

As you can see, these commands can become quite long. As such, using Docker Compose or CFConfig may provide a more manageable alternative.

Granular Environmental Control

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

• EXPRESS=true - Uses an H2, in-memory database. Useful for very small sites or for testing the image. See http://www.h2database.com/html/main.html

• 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

• SESSION_STORAGE - Allows the customization of session storage. Allows any valid this.sessionStorage value, available in Application.cfc. By default, it will use the JDBC connection to store your sessions in your database of choice.

• 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

• contentbox_default_* - All Contentbox "Geek Settings" may be provided as environment variables, allowing granular control of your ContentBox settings.

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

In addition, the CommandBox docker image environment variables are also available to use in your container. For additional information on using the CommandBox docker image, see the initial release blog entry.

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.

We have also prepared a docker-compose and distribution example using Redis (more caches to come) and the ContentBox image. This example will allow you to have a stack that can easily distribute your sessions and content via Redis. You can find the repository here: https://github.com/Ortus-Solutions/docker-contentbox-distributed

Healthchecks

The image contains built-in capabilities for health checks 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 make your source code lighter-weight, as well as providing you with a standardized development environment, which matches your production container strategy.