Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Let's get started with some system requirements for running ContentBox sites:
ContentBox will run in any Java 1.7+ enabled servlet container as a WAR or self-contained express edition.
ContentBox source can be also be deployed to the following ColdFusion CFML engines:
Adobe ColdFusion 11+
Lucee 4.5+
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
PostgreSQL
Hypersonic
H2
Apache Derby
If you have another database engine that needs ContentBox support, please let us know and we will be able to help you (http://www.ortussolutions.com/contact).
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
Dialects We Support
Derby
PostgreSQL
MySQL
MySQLwithInnoDB
MySQLwithMyISAM
Oracle10g
MicrosoftSQLServer
Tip If you are using the H2 or Hypersonic Databases, just leave the dialect empty or use the MySQL dialects for compatibility purposes.
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:
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.
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"
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.
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:
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.
Edit config/Router.cfc and set setFullRewrites to true. That's it!
Edit config/routes.cfm and remove any reference to index.cfm. That's it!
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:
Here are the folders for the core engine to work accordingly
Danger If you will not be using any ForgeBox download deployments then you do not need to enable write permissions for
themes, modules_user, and widgets.
The express version of ContentBox is a fully integrated 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.
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+.
The first step is for you to download ContentBox (http://www.ortussolutions.com/products/contentbox) or you can use the command below:
Once downloaded expand the archive
This will expand into the folder of your liking.
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.
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.
Make sure you visit the following URLs and setup a server and web application password for the underlying engines:
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.
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!
Caution We recommend that after you install ContentBox that you remove the installer and datsource wizard modules from disk. You can do so manually or via the Dashboard once you log in.
{Root}/modules/contentbox-installer and {Root}/modules/contentbox-dsncreator
Go to the conf/server.xml and look for the following:
Just update the port to whatever you desire.
There are several ways to install ContentBox. You can:
Deploy the source to any modern ColdFusion (CFML) server, leveraging CommandBox CLI for embedded deployment
Leverage the ContentBox.war to any Java enabled server
Run an express self-contained version
Run as a docker container
So let's get started.
If you already have a ColdBox application and you wish to install ContentBox into it, you most definitely can.
Please note that ContentBox requires ColdBox 4.3+.
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 folder and update your box.json with the appropriate dependency. That's it, next step!
If you need to execute the ContentBox installer for the first time, you will have to download the installer package from our download page. Extract the zip and copy over the modules/contentbox-installer folder into your modules folder.
Note We will create another installer approach in the future for this portion.
Application.cfc UpdatesNow open your Application.cfc and you will add the following updates:
ColdBox.cfc SettingsWe now move to the last step, 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
Danger Make sure you have the datasource created in your ColdFusion administrator or inline in your
Application.cfc
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!
In this section you will install ContentBox by using the war download option and deploying it to any Java 1.7+ servlet container.
The first step is for you to download ContentBox (http://www.ortussolutions.com/products/contentbox) or you can use the command below:
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.
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.
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:
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!
Caution We recommend that after you install ContentBox that you remove the installer and datsource wizard modules from disk. You can do so manually or via the Dashboard once you log in.
{Root}/modules/contentbox-installer and {Root}/modules/contentbox-dsncreator
In this section you will install ContentBox by using the source download option.
The first step is for you to download the ContentBox installer (http://www.ortussolutions.com/products/contentbox) or you can use the command below:
Expand the archive into your web root or a sub folder of your favorite CFML engine.
Caution Due to a bug in some CFML engines, DO NOT use the subfolder name
contentbox, use cbox or site or whatever you like if you will be deploying under a subfolder.
Please also note that you can also download two more types:
Module - The ContentBox module so you can deploy into any existing ColdBox application
Site - A pre-configured site like the installer but with no DSN Creator and ContentBox Installer
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.
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.
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.
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!
Caution We recommend that after you install ContentBox that you remove the installer and datsource wizard modules from disk. You can do so manually or via the Dashboard once you log in.
{Root}/modules/contentbox-installer and {Root}/modules/contentbox-dsncreator
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. The full CommandBox installation instructions can be found here: http://commandbox.ortusbooks.com/content/setup/installation.html. We will do the short version.
You can download CommandBox from the official site: http://www.ortussolutions.com/products/commandbox#download and install in your preferred Operating System (Windows, Mac, *unix). CommandBox comes in two flavors:
No Java Runtime (30mb)
Embedded Runtime (80mb)
So make sure you choose your desired installation path and follow the instructions here: http://commandbox.ortusbooks.com/content/setup/installation.html
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.
Now that we have CommandBox we can use it to install and startup a ContentBox site using the embedded server (Lucee 4.5). You can use an embedded database or connect the embedded server to any database server as well. 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:
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.
Note You can install the bleeding edge of ContentBox by using the
contentbox-install@beidentifier in the install command. Basically, you can add any@beto any ID and CommandBox will try to retrieve the latest bleeding edge.
This will install the latest stable ContentBox and run an embedded server (Lucee 4.5) for it. After this you will get the ContenBox installer. Just follow it through.
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:
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 web admin and go into the datasources section and create one.
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:
contentbox - Installs ContentBox as a module into any existing ColdBox application.
contentbox-site - Installs a new ColdBox site enabled for ContentBox with a dependency on contentbox for its module but no installer or DSN creator.
contentbox-installer - Same as above but with our DSN Creator and Installer Module.
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.
The image is packaged with a self-contained express version, which uses an in-memory H2 database. To stand up an image for testing purposes, using an unconfigured express edition, simply run:
Note The command above is using
&&to concatenate the two commands which will work under *unix. If you are in windows, replace&&with;in Powershell, replace&&with&in Cmd, or run the two commands separately
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.
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 user-uploaded assets. 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 default storage location for the CMS user media assets is set to /app/includes/shared/media. Let's mount both of those volume points, so that our database and user-uploaded 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.
Because the express flag produces a ContentBox installation which runs on a file-based, in-memory H2 database, it's really suitable only for testing or low-traffic containers. For scalability, we would want to connect to an database server, which would allow us to connect from multiple containers in a distributed fasion (MySQL, Oracle, MSSQL, etc)
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 file containing your engine configuration, including datasources.
By convention, the datasource name expected is simply named contentbox.
To programatically configure the database on container start, environment variables which represent your datasource configuration should be provided. There are two patterns supported:
DB_DRIVER configuration - which may be used for Adobe Coldfusion servers
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:
As you can see, these commands can become quite long. As such, using Docker Compose or CFConfig may provide a more manageable alternative.
A number of environment variables, specific to the ContentBox image, are availabe 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 assit in configuring your installation. You would omit this from your run command, once your database has been configured
$HEALTHCHECK_URI - Specifies the URI endpoint for container health checks. By default, this is set http://127.0.0.1:${PORT}/ at 1 minute intervals with 5 retries and a timeout of 30s
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_* - 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.
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.
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.
By default, our image configures a jdbc CacheBox cache region that will be used to distribute settings, 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
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 1 minute intervals with 5 retries and a timeout of 30s.
Playing around with the image is great, but what does this mean for you as a developer? Effectively it means that you can develop and deploy customized CMS applications with only a single theme directory (and, possibly, a customized config/Coldbox.cfc file).
The image location for the themes directory in ContentBox is /app/modules/contentbox/themes. Any theme mounted in to this directory can be configured in the run of the container, which means you no longer have to commit an entire ContentBox installation to your repository. You can mount only those files and folders ( e.g. - custom modules ) necessary for your application to do its thing. In addition, you also have power to reconfigure ContentBox settings on-the-fly using environment variables prefixed with contentbox_{site}_{setting}={value}.
Let's start an image with a custom theme, and a ColdBox module, persisting our assets, while using a MySQL database with the installer:
Please note the following customizable paths for custom assets.
/app/includes/shared/media - ContentBox Media Manager
/app/modules - CommandBox managed modules
/app/modules_app - Custom ColdBox modules
/app/modules/contentbox/themes - Custom ContentBox Themes
/app/modules/contentbox/widgets - Custom ContentBox Widgets
/app/modules/contentbox/modules_user - Custom ContentBox Modules
There are more geek settings and paths that we have time to go in to in this post but, suffice it to say, you will be able to control nearly every aspect of your site settings on the startup of your Docker container.
For a list open source themes, readily available for your customization, visit Forgebox.
Note that the
Application.cfcand theconfigdirectory of the ContentBox Docker image have some customizations specific to their purpose. If you wish to customize those, please see the Docker build repository files to ensure those customizations are present in yours.
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.
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.
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.
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:
Or you can visit www.ortussolutions.com/products/contentbox for all the available download patches.
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
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.
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!
If you are using the contentbox module approach via CommandBox, you can easily upgrade by doing two things:
Issue an update command: box update contentbox. This will update the module to its latest version
Apply the db-only patch in your administrator
Then restart your engine.
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!
