Upgrade Go-Live Checklist

This checklist is intended as a best-practice guide to help ensure that you’ve fully tested before you “go live” with your site.

This checklist can be used both when you create a new site with dotCMS, and when you upgrade your site from one dotCMS version to another. This checklist may also help you to set up your own internal testing process when you make large changes to your site, such as when rolling out a major site redesign.

The items in this list are neither complete nor detailed; these are merely guidelines to help you identify areas of your site to test before you switch over to a new site.

Back End #

Authentication: SAML / LDAP / Oauth
1. Verify that authorized users can login to the dotCMS back end.
2. Verify that you can login to the dotCMS back end using a native administrator account (using the ?native=true flag)
3. Verify password reset email works and has correct portal URL
Relationships
1. Verify that relations on content display properly in the back end (when viewing related content in the content editing screen).
2. Verify that all pages containing relationship code display correctly, and display the correct related content.
SMTP
1. Verify client-owned domains are validated in SES, or client-provided SMTP credentials are working correctly
Indexes
1. Verify index is healthy
2. Verify all site search indexes exist and are healthy (if configured)
Editing and UVE Access
1. Ensure all user roles have expected permissions and abilities to update content in both edit-mode and UVE
Log Files
1. Please validate that you still have access to the dotCMS.log file within the maintenance portlet.
dotCMS Site Variables
1. Within the “sites” portlet, if you have added any bespoke “site variables” for any sites, please manually validate that they exist across all environments they are critical for, as site variables are not push publishable.
Site Aliases
1. Ensure all domains that will be DNS addressable are added as “site aliases” under each site in the dotCMS sites portlet. For example, if my site is acme.com and I need my web visitors to visit www.acme.com and acme.com, I will need to add both acme.com and www.acme.com as site aliases under the appropriate host.
  
  This is a critical client-driven piece of the implementation as dotCMS cannot self-verify what DNS entries are required, nor can DNS entries be automatically pointed at the dotCMS server.
Default Site
1. Ensure that there exists some host named “blank-for-security” with no content or objects associated with it
  - Ensure that host is set in the dotCMS “sites” portlet as the “default” site
  - If your current implementation relies on the default site existing on a non-blank host, please contact dotCMS support and/or your upgrade manager for further assistance
Ensure the “No search indexation rule” for X-Robots-Tag in the header for all requests exists on each host that ends in …dotcms.cloud
Only after the production site(s) are completely ready to launch, add the robots.txt file to the root of each site with at least the following recommended settings:

User-agent: *
Disallow: /dotAdmin/
Disallow: /api/
Disallow: /html/
Disallow: /dA/
Disallow: /c/
Disallow: /application/
Disallow: /servlets/
Disallow: /webdav/

# Allow all public content
Allow: /

# Optional: Sitemap location
Sitemap: https://www.yoursite.com/sitemap.xml

Front End #

Authentication
1. If front-end logins are enabled, verify that existing front-end users can login properly.
Page Display
1. If possible, display and verify the operation of every page on the front end of the site.
  - If you have front-end pages that require authentication, perform this run-through twice: Once as an authenticated user, and a second time as an unauthenticated user.
  - Test pages in all additional languages, as applicable
2. If there are too many pages to test all pages, test at least:
  - All top-level pages.
  - All pages directly accessible through navigation menus.
  - Any pages containing custom Velocity or Javascript code.
  - 3 pages of each page type (including 3 pages using each different page Templat, 3 pages of each URL-mapped content type, etc).
  - Any pages or areas of the site with restricted access.
Forms
1. Display and use (submit content through) at least one instance of each front-end form. Verify that:
  - The form can be submitted by all users it should be (anonymous users, authenticated front-end users, etc).
  - When a form is submitted, the content is created within dotCMS properly.
  - The user receives confirmation or redirection as expected after submission.
  - Incorrect/disallowed values in form fields cause appropriate behavior (messages to users, redirection, etc.).
Anonymous and Role Based Front-End Content
1. Validate all content and pages that are protected via login and role-based permissions are not accessible anonymously by attempting access through a private window or incognito browser

Push Publishing #

Due to the nature of Push Publishing, all these validation steps should be performed on each dotCMS environment which acts as a Push Publishing sender. Generally, this means all dotCMS environments except for your production environment. On each Push Publishing sender, check the following for each receiving endpoint:

Endpoint Configuration
1. Verify that the authorized users and Roles set on the Push Publishing endpoint configuration are correct.
Filters
1. Verify that all custom Push Publishing filters on your site display in the Push Publishing popup window.
2. Verify that your Push Publishing default filter is set correctly to your default filter of choice
Integrity
1. Run the Integrity Checker, and verify there are no conflicts.
Pushing Content
1. Separately push a single content item of each content type using the “Only Selected Items” filter — and verify that it pushes without delays and without errors.
2. Create a bundle of several content items of each main content type used, and verify that the bundle pushes without delays and without errors.
GraphQL
1. Display all pages containing GraphQL queries.

Integration Testing #

REST API: Verify that any external applications or sites which use dotCMS APIs can retrieve the proper values from dotCMS.
Code Verification: SASS, Velocity, and other code that executes or compiles on the back end
Plugins:
1. Static plugins, if present, are no longer supported; dotCMS uses OSGi plugins.
2. OSGi plugins may require some development against changes in dotCMS.

Site Accessibility #

Vanity URLs, rewrite rules, or other redirect rules
Certificates — are the correct certificates being served if requested (may require local DNS or hosts file changes for effective testing)
Allow lists where applicable
Index pages — i.e. is default index page index.html, index.htm, index.dot, etc.
Home pages — is the customer’s home page not located in the root directory (often found with legacy customers using /home instead)?
Are there any noticeable time issues? Check whether there are any dependencies on a specific time zone within code.
Ensure there are no hardcoded dependencies to old resources that will not migrate — i.e. hardcoded DNS names or IP addresses of old hosts, load balancers, etc.

Certificates #

Amazon Certificate Manager (ACM)#

dotCMS can offer certificates signed by a publicly trusted Certificate Authority (Amazon) at no additional charge. A validation process must be successfully completed for each domain (or subdomain) listed on the certificate(s). This process entails adding CNAME DNS records to validate ownership of the domain(s).

To use ACM, dotCMS will need to know every domain and subdomain to be named in the certificates.

The customer and dotCMS Cloud Engineering team will work together via helpdesk ticket to get these certificates validated. Once the validation process has successfully completed, the certificate(s) will be issued and can be used immediately.

These certificates can only be used with a subset of services native to AWS, their private keys cannot be extracted or accessed by dotCMS, and they will automatically renew each year (provided the DNS validation records remain in place).

Customer-Provided Certificates #

As an alternative, customers can provide their own certificates to dotCMS. The certificate, along with its private key, will need to be securely shared with dotCMS staff so it can be associated with the necessary services. The customer will be responsible for renewing these certificates every year.

DNS Resource Guide #

Overview #

dotCMS will provide subdomains pointing to all environments.

Example:

customer-prod.dotcms.cloud
customer-staging.dotcms.cloud
customer-dev.dotcms.cloud

These subdomains will resolve to respective AWS ALBs for each environment.

During an upgrade, you may be provided with temporary testing URLs such as customer-prod-1.dotcms.cloud. These are intended to be temporary URLs for your testing. The URLs that do not include the “-1” will remain the default and travel with the live environments.

Scenario 1 (Preferred):#

The customer will create CNAME records pointing to the provided subdomains from dotCMS.
1. Examples:
  1. customer.com → customer-prod.dotcms.cloud (CNAME record)
  2. staging.customer.com → customer-staging.dotcms.cloud (CNAME record)
  3. dev.customer.com → customer-dev.dotcms.cloud (CNAME record)
2. This will ensure any updates to the dotCMS infrastructure will not affect appropriate DNS resolution or require the customer to initiate any updates to their DNS records or other infrastructure.

DNS spec prevents the zone apex record (i.e. root record of domain) from being a CNAME type record (as other records are often present on the same level). This can be circumvented with some DNS providers by way of CNAME flattening (some DNS services have other names for this). This functionality may or may not be available from your DNS service.

Scenario 2:#

If the customer does not have the capability to CNAME flatten (or equivalent), we can provide static IP addresses that are associated with their production environment to be used for DNS A records at their zone apex.
Customers typically use some kind of subdomain associated with their own domain for non-production environments, so CNAME records are not a problem here regardless of the DNS service being used.
1. Example:
  1. customer.com → (static IP associated with production environment) (A record)
  2. staging.customer.com → customer-staging.dotcms.cloud (CNAME record)
  3. dev.customer.com → customer-dev.dotcms.cloud (CNAME record)

All information above is relating to ingress traffic to dotCMS cloud environments. If egress traffic (from dotCMS cloud) comes into question, IP addresses are different from the ones used for ingress. Reach out to dotCMS Cloud support if you have questions about our IP space, or about restricting or allowing access to/from dotCMS Cloud servers.

If there are outbound firewall rules in place, your firewall may or may not support rules based on DNS names. If it does not, there may be workarounds available, such as IP lists (that would need to be periodically updated) or we may be able to provide static IP addresses for all environments using the same method as the production environment in scenario 2.

dotCDN Considerations for DNS and Certificates #

If a customer plans to use dotCDN — our managed CDN service — then the process is slightly different for both DNS and certificates.

DNS records will need to resolve to a subdomain provided by dotCMS (different that the ones mentioned above). Free certificates can be issued for this domain (or subdomain), provided it resolves to the subdomain previously mentioned, and are issued by Let’s Encrypt.

Customers can also provide their own certificates to be used at the CDN level as well.

We recommend that the canonical address for your website uses a www (or other) subdomain. This allows all DNS services to resolve to the CDN subdomain via CNAME record without any problems or limitations. dotCMS can provide static IP addresses for your apex domain to resolve to (via A record) that will redirect to the www subdomain variation and ultimately resolve to the CDN endpoint.

Example:

customer.com → x.x.x.x → dotCMS redirect → www.customer.com → CDN endpoint