Upgrading From v4.x

ContentBox v5.x is a major version update and will require the following instructions to update your v4.x installations. Please follow this guide or contact us at [email protected] so we can assist you during your upgrade process.
If you are in version 3.x then you will need to upgrade to version 4.x before upgrading to the 5.x series https://contentbox.ortusbooks.com/v/v4.x/intro/introduction/upgrading-from-v3.x​
1. Requirements
All Upgrades to ContentBox should be done with the assistance of CommandBox CLI. So make sure you have CommandBox installed in the server/machine you will be upgrading.
Install CommandBox Dependencies
Once you have CommandBox installed, let's make sure we have some global dependencies installed so CommandBox can work with ContentBox automated upgrades:
1
# install env controls and db migrations
2
box install commandbox-dotenv,commandbox-migrations
Copied!
This will install the environment module and the database migrations module that will be used to provide upgrades in the future.  This is only done once. ContentBox 5 already ships with these dependencies once you install it.
Environment (.env)
The upgrade process and the database migrations rely on environment variables/secrets in order to connect to your database and migrate it.  Create an .env file in the root of the ContentBox installation and add in the configuration according to your database and configuration preferences.
To generate a JWT secret key you can use CommandBox and run the following in the command prompt: #generatesecretkey "blowfish" 256
1
#################################################################
2
# App Name and Environment
3
#################################################################
4
APPNAME=ContentBox Modular CMS
5
# This can be development, staging, production or custom.
6
ENVIRONMENT=development
7
# The password for the CFML Engine Administrator
8
CFCONFIG_ADMINPASSWORD=contentbox
9
# The ColdBox Reinit password
10
COLDBOX_REINITPASSWORD=
11
# How long do admin sessions last (In Minutes)
12
COLDBOX_SESSION_TIMEOUT=60
13
# Development CBDebugger
14
CBDEBUGGER_ENABLED=false
15
​
16
#################################################################
17
# ContentBox ORM Settings
18
# --------------------------------
19
# This is used to configure the ORM via env settings usually for
20
# different RDBMS settings or options
21
#################################################################
22
# Dialect choices:
23
# 	MySQL, Hypersonic 	=> org.hibernate.dialect.MySQL5InnoDBDialect,
24
# 	PostgreSQL 			=> PostgreSQL
25
# 	Microsoft SQL 		=> org.hibernate.dialect.SQLServer2008Dialect
26
# 	Oracle 				=> Oracle10g
27
# 	Derby 				=> Derby
28
ORM_DIALECT=org.hibernate.dialect.MySQL5InnoDBDialect
29
# Log sql to the console or not
30
ORM_LOGSQL=true
31
# Sql Script to execute after ORM is initialized
32
ORM_SQL_SCRIPT=
33
# Activate secondary cache or disable it
34
ORM_SECONDARY_CACHE=false
35
ORM_SECONDARY_CACHE_PROVIDER=ehcache
36
​
37
#################################################################
38
# ContentBox Datsource and Migrations Variables
39
# ----------------------------------------------------------------
40
# These settings configure the datasource connection to your database
41
# Please make sure you read the comments as there are differences
42
# between Adobe and Lucee. Uncomment your rdbms of choice, the options are:
43
# - MySQL 5.7
44
# - MySQL 5.8
45
# - PostgreSQL
46
# - Microsoft SQL
47
# - Custom Database
48
#################################################################
49
​
50
######################################################
51
# MySQL 5.7 DB Driver
52
######################################################
53
DB_DRIVER=MySQL
54
# Lucee Class
55
DB_CLASS=com.mysql.jdbc.Driver
56
# Adobe Class
57
#DB_CLASS=com.mysql.cj.jdbc.Driver
58
# Lucee Bundle Info: 5.1.40 IS THE ONLY ONE THAT WORKS FOR HIBERNATE + MySQL 5.7
59
DB_BUNDLEVERSION=5.1.40
60
DB_BUNDLENAME=com.mysql.jdbc
61
# DB Location
62
DB_HOST=127.0.0.1
63
DB_PORT=3306
64
DB_CONNECTIONSTRING=jdbc:mysql://127.0.0.1:3306/contentbox?useSSL=false&useUnicode=true&characterEncoding=UTF-8&serverTimezone=UTC&useLegacyDatetimeCode=true
65
# DB Credentials
66
DB_DATABASE=contentbox
67
DB_USER=root
68
DB_PASSWORD=mysql
69
​
70
######################################################
71
# MySQL 8 DB Driver
72
######################################################
73
#DB_CLASS=com.mysql.cj.jdbc.Driver
74
#DB_DRIVER=MySQL
75
#DB_BUNDLEVERSION=8.0.19
76
#DB_BUNDLENAME=com.mysql.cj
77
## DB Location
78
#DB_HOST=127.0.0.1
79
#DB_PORT=4306
80
#DB_CONNECTIONSTRING=jdbc:mysql://127.0.0.1:4306/contentbox?allowPublicKeyRetrieval=true&useSSL=false&useUnicode=true&characterEncoding=UTF-8&serverTimezone=UTC&useLegacyDatetimeCode=true
81
## DB Credentials
82
#DB_DATABASE=contentbox
83
#DB_USER=root
84
#DB_PASSWORD=contentbox
85
​
86
######################################################
87
# PostgreSQL DB Driver #
88
######################################################
89
#DB_CLASS=org.postgresql.Driver
90
#DB_DRIVER=PostgreSQL
91
#DB_BUNDLEVERSION=9.4.1212
92
#DB_BUNDLENAME=org.postgresql.jdbc42
93
## DB Location
94
#DB_HOST=127.0.0.1
95
#DB_PORT=5432
96
#DB_CONNECTIONSTRING=jdbc:postgresql://localhost:5432/contentbox
97
## DB Credentials
98
#DB_DATABASE=contentbox
99
#DB_USER=contentbox
100
#DB_PASSWORD=contentbox
101
​
102
######################################################
103
# Microsoft SQL DB Driver #
104
######################################################
105
#DB_DRIVER=mssql
106
#DB_CLASS=com.microsoft.sqlserver.jdbc.SQLServerDriver
107
#DB_BUNDLEVERSION=7.2.2.jre8
108
#DB_BUNDLENAME=org.lucee.mssql
109
## DB Location
110
#DB_HOST=127.0.0.1
111
#DB_PORT=1433
112
#DB_CONNECTIONSTRING=jdbc:sqlserver://localhost:1433;DATABASENAME=contentbox;sendStringParametersAsUnicode=true;SelectMethod=direct
113
## DB Credentials
114
#DB_DATABASE=contentbox
115
#DB_USER=sa
116
#DB_PASSWORD=ContentB0x!
117
​
118
#################################################################
119
# JWT Information
120
# --------------------------------
121
# You can seed the JWT secret below or you can also leave it empty
122
# and ContentBox will auto-generate one for you that rotates
123
# everytime the application restarts or expires
124
#################################################################
125
JWT_SECRET=
126
​
127
#################################################################
128
# AWS S3 or Digital Ocean Spaces
129
# --------------------------------
130
# If you are using any of our S3/Spaces compatible storages, you
131
# will have to seed your credentials and information below
132
#################################################################
133
S3_ACCESS_KEY=
134
S3_SECRET_KEY=
135
S3_REGION=us-east-1
136
S3_DOMAIN=amazonaws.com
137
S3_BUCKET=
138
​
Copied!
Please note that once you are on ContentBox 5 none of these steps will be necessary anymore. Since it is part of the default installation.
Please note that this .env file should NEVER be in source control and NEVER be web accessible
If you are running CommandBox as your server of choice, then you can update your .cfconfig.json in the root of your application to the following:
.cfconfig.json
1
{
2
	"systemErr":"System",
3
	"systemOut":"System",
4
	"componentCacheEnabled":false,
5
	"robustExceptionEnabled":true,
6
	"debuggingEnabled" : true,
7
	"debuggingReportExecutionTimes": false,
8
	"saveClassFiles":false,
9
	"thistimezone":"UTC",
10
	"whitespaceManagement":"white-space-pref",
11
	"postParametersLimit" : 200,
12
	"cacheDefaultObject":"contentbox",
13
        "caches":{
14
          "contentbox":{
15
            "storage":"true",
16
            "type":"RAM",
17
            "custom":{
18
                "timeToIdleSeconds":"1800",
19
                "timeToLiveSeconds":"3600"
20
            },
21
            "class":"lucee.runtime.cache.ram.RamCache",
22
            "readOnly":"false"
23
		}
24
        },
25
	"datasources" : {
26
		"contentbox":{
27
            "allowAlter":true,
28
            "allowCreate":true,
29
            "allowDelete":true,
30
            "allowDrop":true,
31
            "allowGrant":true,
32
            "allowInsert":true,
33
            "allowRevoke":true,
34
            "allowSelect":true,
35
            "allowUpdate":true,
36
            "blob":"true",
37
			      "bundleName": "${DB_BUNDLENAME}",
38
			      "bundleVersion": "${DB_BUNDLEVERSION}",
39
            "class":"${DB_CLASS}",
40
            "clob":"true",
41
            "connectionLimit":"100",
42
            "connectionTimeout":"1",
43
            "custom":"useUnicode=true&characterEncoding=UTF8&serverTimezone=UTC&useLegacyDatetimeCode=true&autoReconnect=true&useSSL=false&allowPublicKeyRetrieval=true",
44
            "database":"${DB_DATABASE:contentbox}",
45
            "dbdriver":"${DB_DRIVER}",
46
            "host":"${DB_HOST:127.0.0.1}",
47
            "metaCacheTimeout":"60000",
48
            "password":"${DB_PASSWORD}",
49
            "port":"${DB_PORT:3306}",
50
            "storage":"false",
51
            "username":"${DB_USER}",
52
			"validate":"false"
53
		}
54
	}
55
}
Copied!
Once your environment file is seeded open the box.json of the ContentBox 4 and add the following configuration. 
Most likely you will already have a scripts key in the box.json so just add the listed scripts below:
1
...
2
​
3
"scripts" : {
4
   "contentbox:migrate":"migrate up migrationsDirectory=modules/contentbox/migrations",
5
   "contentbox:migrate:up":"run-script contentbox:migrate",
6
   "contentbox:migrate:down":"migrate down migrationsDirectory=modules/contentbox/migrations"
7
},
8
​
9
"cfmigrations":{
10
    "schema":"${DB_DATABASE}",
11
    "connectionInfo":{
12
        "bundleName":"${DB_BUNDLENAME}",
13
        "bundleVersion":"${DB_BUNDLEVERSION}",
14
        "class":"${DB_CLASS}",
15
        "connectionString":"${DB_CONNECTIONSTRING}",
16
        "password":"${DB_PASSWORD}",
17
        "username":"${DB_USER}"
18
    },
19
    "defaultGrammar":"[email protected]"
20
}
21
​
22
...
Copied!
PLEASE MAKE SURE TO SAVE THE FILE!
This will tell CommandBox migrations how to connect to your database in preparation for upgrades.  Please note that the contentbox:migrate scripts are to execute migrations for ContentBox. You can have app migrations as well, following the normal migrations approach.
Once this is done we can reload the CommandBox shell with the command reload and it's time to make sure migrations can connect to your database with the variables and connection information:
1
# Run the migration table installation
2
$ migrate install
3
 Migration table installed!
Copied!
If this command succeeds, then we are ready to go to the next step.  If it fails, then check your credentials, connection information and that you can actually connect to the database. If not, ask away in our community forum: https://community.ortussolutions.com/c/communities/contentbox/15​
2. Backups
Please make sure you backup your source code and your database. We are not liable for broken installations.
Make sure the database, the tables and columns are using utf8mb4 if you are using MySQLx
3. MySQL UTF8mb4
If you are using MySQL you will need to make sure your database and your tables are all using the following character set: utf8mb4 and NOT just utf8.  ContentBox 5 requires the charset to be utf8mb4. 
We also suggest you use the utf8mb4_general_ci collation for your database, tables and columns as well.
4. Run the Updater
We have prepared a CommandBox task that will upgrade your installation in one easy execution.
*nix/Mac
If you are in a Linux or Mac environment you can execute the task using the following shell commands from the root directory of your application.
1
# Download the updater
2
curl -o Updater.cfc https://raw.githubusercontent.com/Ortus-Solutions/ContentBox/development/build/patches/5.0.0/Updater.cfc
3
# Execute the task
4
box task run Updater.cfc
5
# Clean it up
6
rm Updater.cfc
Copied!
Windows
If you are in windows, download the following task:
​http://raw.githubusercontent.com/Ortus-Solutions/ContentBox/development/build/patches/5.0.0/Updater.cfc​
and place it in the root of your project. Then issue the following CommandBox shell command to execute it.
1
# Run the task
2
box task run Updater.cfc
3
# Clean it up
4
rm Updater.cfc
Copied!
5. Final Steps
The updater will update your installation and run the migration scripts. However, it will also override the following files:
1
.cfconfig.json
2
server.json
3
Application.cfc
4
robots.txt
5
readme.md
6
config/CacheBox.cfc
7
config/Coldbox.cfc
Copied!
It will create .bak files for the originals so you can manually merge in any changes you had before. 
Once you do, go ahead and startup the engines! You are upgraded!
Optional Steps
If you had developed themes, modules, models, or any type of extension based on ContentBox 4, you will most likely have to update your code to match the new interfaces, methods and approaches.
ContentBox Models Namespace
If you had custom models, modules, themes and widgets, please do a search for the old injection namespace of @cb for ContentBox models.  Then replace it with the new namespace @contentbox.
Renamed CBHelper Methods
layoutRoot() => themeRoot()
customHTML() => contentStore()
Renamed Author Object Methods
author.getName() => author.getFullName()
​
​
What's new With 5.0.0
Next - Intro
About This Book
Last modified 1mo ago
Copy link
Edit on GitHub
Contents
1. Requirements
Install CommandBox Dependencies