Where Mura is Installed

As a Mura theme developer, you're going to be working with the file system. So, it's important to have an understanding of where Mura is located, and how you can reference this information programmatically, via code. Because at some point, you're going to need this kind of information when generating links to, and from, your own template files.

{context}

The location on your file system of where Mura is actually installed, is referred to as the {context}.

While the vast majority of Mura installations occur at the webroot, some organizations may have Mura installed in a subdirectory of the webroot. It doesn't matter if it's only one level deep, or ten levels deep. Mura is able to ascertain its installation directory, and can help you obtain the information with a simple code snippet.

For example, on a typical Windows server, it might be installed in the following directory:

C:\inetpub\wwwroot\

We can easily reference this information with a simple code snippet in Mura:

m.globalConfig('context')

Listed below are examples of what the m.globalConfig('context') Mura code snippet would return, based on where Mura is installed on the file system.

Install Location Return Value
C:\inetpub\wwwroot\ Empty string
C:\inetpub\wwwroot\muraplatform\ /muraplatform
C:\inetpub\wwwroot\somedirectory\muraplatform\ /somedirectory/muraplatform

The usage of this Mura code snippet, and many others, will be covered much more in depth, as well as how to use them, in another section. At this point, it's important to just keep the {context} in mind, and that there's a way to find out what it is.

 

Mura Directory Structure

There are a few primary directories and files you'll want to be aware of in Mura. The image below displays the directory structure of Mura, highlighting its required directories and files. The directories and files highlighted in red may be updated when updating Mura.

Note: Unless explicitly stated to the contrary, none of the directories or files listed below should be modified.

Directory or File Editable Description
{context}/admin/ No These files should never be modified. The files located here comprise the view and much of the functionality used for the administrative features of Mura.
{context}/config/ Yes This directory contains configuration files. See The "config" Directory section for more information.
{context}/core/ No These file should never be modified. The files located here are essentially the beating heart of Mura. We'll discuss a few files specific to Theme Developers in other sections. That said, it's best to simply leave the files in this directory alone.
{context}/sites/ Yes* The directory itself is required, however the contents may be edited and will not be overwritten when updating Mura. This directory will be covered in the "Site Files" section.
{context}/themes/ Yes* The directory itself is required, however the contents may be edited and will not be overwritten when updating Mura. This directory will be covered in the "Theme Layout Templates" section.
{context}/modules/ Yes* The directory itself is required, however the contents may be edited and will not be overwritten when updating Mura.
{context}/resource_bundles/ Yes* The directory itself is required, however the contents may be edited and will not be overwritten when updating Mura.
{context}/plugins/ Yes* The directory itself is required, however the contents may be edited and will not be overwritten when updating Mura. This directory is used by experienced developers when creating Mura plugins.
{context}/.git No The Mura team uses Git for distributed version control. This directory is created and used specifically by Git. You can safely ignore this directory.
{context}/.gitignore No The Mura Team uses Git for distributed version control, and this is the root .gitignore file used to specify intentionally untracked files.
{context}/.travis.yml No This file is used by Travis CI for automated testing.
{context}/Application.cfc No This file contains Mura's application-specific variables and settings.
{context}/box.json No This file is used by the Mura Team to run various tests using CommandBox and TestBox.
{context}/index.cfm No This is Mura's "start" file, and should not be modified.
{context}/installation.txt No This file outlines the basic steps to get up and running with Mura CMS.
{context}/license.txt No This is the GNU General Public License, Version 2, with exceptions.
{context}/Mura_CMS_
contribution_agreement.pdf
No* This file shouldn't be modified per se, but rather completed. For developers or development teams who wish to contribute to Mura, please complete this document and return it to matt.levine@blueriver.com.
{context}/README.md No A simple README file. When viewed on Github, a badge from Travis CI will display whether or not the current build is passing its required tests.
{context}/robots.txt Yes This file is used to give instructions about their site to web robots. You can safely modify this file.
{context}/htaccess.txt No This is a sample .htaccess file for experienced web server administrators using Apache HTTP Server, and are looking for an example of how to eliminate the "index.cfm" from the URL.
{context}/web.config.txt No This is a sample web.config file for experienced web server administrators using Microsoft IIS, and are looking for an example of how to eliminate the "index.cfm" from the URL.
{context}/web.config Yes This file is used by Microsoft IIS. You can safely modify this file. However, it is recommended that only experienced web server administrators do so.

 

The "config" Directory

This directory contains Mura's configuration files. The files and their purpose are listed below.

Directory Editable Description
{context}/config/Application.cfc No This file prevents site visitors from navigating directly to any of the .CFM files contained within this directory.
{context}/config/cfapplication.cfm Yes Experienced developers may add custom Application.cfc variables and/or ColdFusion/CFML mappings here.
{context}/config/README.md No This file contains information about the files contained in this directory.
{context}/config/settings.ini.cfm Yes This is an extremely important file, and contains many of the default settings for Mura. A detailed reference is available in the Mura Developer Guide.

The "core" Directory

Once you've determined where Mura has been installed, you'll want to be able to identify Mura's "core" files. This is important to know, because the last thing you want to do is modify a file you shouldn't have touched to begin with.

As you'll see later, Mura offers an easy way to keep your installation of Mura up-to-date, and if you're modifying "core" files, there's a very good chance your changes would be overwritten. So, in this section, we'll cover where "core" files reside, and which ones you can safely modify, to stay on the upgrade path.

Mura Directory Structure

There are a few primary directories and files you'll want to be aware of in Mura. The image below displays the "core" directory structure.

Directory or File Editable Description
{context}/core/appcfc/ No The files contained in this directory are included in Mura's main Application.cfc file. See The "appcfc" Directory section for details.
{context}/core/docker/ No This directory contains files related to running Mura on Docker
{context}/core/modules/ No The directories and files located here represent the default display objects and modules used by Mura. This is covered more extensively in the Mura Developer section.
{context}/core/mura/ No The files located here are essentially the beating heart of Mura. We'll take a deeper look at some of its directories and files later.
{context}/core/setup/ No This directory contains files required during the installation process.
{context}/core/templates/ No This directory contains "templates" used to create core files such as the settings.ini.cfmrobots.txt, and some site files such as the SitecontentRenderer.cfc, and Site eventHandler.cfc. These files are typically only used during the installation process.
{context}/core/tests/ No This directory contains files for conducting unit tests.
{context}/core/vendor/ No This directory contains third-party code which Mura relies on for various parts of its functionality such as CKEditor.
{context}/core/.gitignore No The Mura Team uses Git for distributed version control, and this is the site .gitignore file used to specify intentionally untracked files.
{context}/core/Application.cfc No This particular file merely prevents users from navigating to any of the .cfm or .cfc files directly via the browser.

 

The "sites" Directory

You can host multiple websites under one installation of Mura. Each website can have its own, unique domain, assets, groups, users, etc. That said, one important thing to keep in mind when working with theme development in Mura is to make sure you're working with the right directory.

{context}/sites/

Every Mura installation has a directory labeled "sites", located directly under the Mura root or context. This directory name should never be modified, under any circumstances. It contains one file, labeled the Application.cfc (see table below), and a minimum of one sub-directory.

Directory or File Editable Description
{context}/sites/Application.cfc Yes Required. This file is used by experienced ColdFusion/CFML developers, and is covered in the Mura Developer Guide.
{context}/sites/default/ Yes Required. Each Mura installation also has a minimum of one site, labeled the "default" directory. The "default" directory name itself should not be modified, nor should any other Mura-generated directory name located under the "sites" directory. Doing so will break functionality. See below for more information on the "default" directory.

{context}/sites/default/

Every Mura installation has a directory labeled "default." This directory name should never be modified, under any circumstances. The directories and files located under the "default" directory comprise the "site" files for the "Default" site.

In addition to holding all of the "site" files for the "Default" site, the directory label is also the "Site ID," also referred to as the  "SiteID" (no space). To verify a site's SiteID, follow the steps below.

  1. From the back-end administration area of Mura, select Site Settings, then click Edit Settings.
  2. On the Site Settings screen, the first field located under the Basic tab is labeled "Site ID."
  3. The "Site ID" field is a "read only" field, and cannot be modified. This is intentionally designed to work this way.
  4. When creating a new site in Mura, you specify the Site ID. This is important, because whatever you enter into that field will become the directory name. So, do not use any punctuation, special characters, etc. when doing so. See the "How to Add a New Site" section for more information on creating a new site.

The key to remember here is each site in Mura has a unique SiteID which also matches the directory name. So, the path to any particular site you desire to work with can be notated as {context}/sites/{SiteID}/.

Note: Whenever you create a new site in Mura, all of the files located under the "default" directory are copied over to the newly created site's directory.

{context}/sites/{SiteID}/

As a Mura theme developer, you'll be spending most of your time working with files located within your theme. The directory structure of a Mura site is detailed below.

Directory or File Editable Description
{context}/sites/{SiteID}/assets/ Yes* Required. The "assets" directory stores any files uploaded through Mura's web file manager, currently CKFinder, when editing content via the user interface. It's best to simply use the web file manager itself to manage these files. However, we understand you may want, or need, to perform a bulk upload of files to a specific directory. When doing so, please be sure not to alter the primary directory structure, as you could potentially break links to files referenced here.
{context}/sites/{SiteID}/cache/ No Required. You should not touch this directory. Any images, files, etc. uploaded as actual content or primary associated files are renamed and stored here. References to all files are also stored in Mura's database.
{context}/sites/{SiteID}/modules/ Yes Optional. This directory contains the files Mura uses to render display objects in the browser. See The "modules" Directory section for more information.
{context}/sites/{SiteID}/resource_bundles/ Yes Optional. This directory contains ".properties" files containing locale-specific data as a way of internationalising Mura. See The "resource_bundles" Directory section for more information.
{context}/sites/{SiteID}/themes/ Yes Optional. This directory contains a site's themes. Themes stored under this directory are not accessible to any other site, unless the sites are using the same "Display Object Pool" as defined under Site Settings > Edit Settings > Share Resources tab. See The "themes" Directory section for more information.
{context}/sites/{SiteID}/.gitignore No Optional. The Mura Team uses Git for distributed version control, and this is the site .gitignore file used to specify intentionally untracked files.
{context}/sites/{SiteID}/contentRenderer.cfc Yes Optional. This is the Site contentRenderer.cfc file. You can add site-specific methods here. This is covered in the Mura Developer Guide.
{context}/sites/{SiteID}/eventHandler.cfc Yes Optional. This is the Site eventHandler.cfc file. You can add site-specific event handlers/listeners here. This is covered in the Mura Developer Guide.
{context}/sites/{SiteID}/index.cfm No Required. This is the site's "start" file, and should not be modified.

 

The "themes" Directory

As a Mura Theme Developer, you will obviously be spending quite a bit of time working with themes. Themes may be located under one of the following locations:

  • Global Themes
    • {context}/themes/
    • Themes located under the "Global" themes directory will automatically be available as a theme option for all sites under the same Mura instance.
  • Site Themes
    • {context}/sites/{SiteID}/themes/
    • Themes located under a site's "themes" directory are available to the specified site, and/or any other sites sharing the same "Display Object Pool" as defined under Site Settings > Edit Settings > Shared Resources tab.

Mura automatically checks these "themes" directories for any subdirectories. If Mura discovers any subdirectories, it assumes it is a theme, and uses the name of each directory as the "Theme Name". The "Theme Name" will then be listed as an option for authorized administrators to apply as a theme to their site. You may have as many themes as you wish under a "themes" directory.

When Mura is first installed, if a theme does not exist under either of these directories, Mura will attempt to download a theme using the "defaultthemeurl" setting found in the {context}/config/settings.ini.cfm file.

We'll cover the files and directories that comprise a theme under the Creating Layout Templates section.

 

How to Select a Theme From the Admin UI

Only members of the "Admin" group, and "Super Admin Users" are able to select a theme from the Mura administrator. Follow the steps below to select a theme.

  1. From the back-end administrator of Mura, select Site Settings from the main navigation, and click Edit Settings.
  2. You should see the Site Settings screen, and make sure the Basic tab is selected.
  3. Scroll down the screen, and locate the select menu labeled Theme.
  4. Select your desired theme from the list of available Theme options, then click the Save Settings button.
  5. The selected theme should now be applied to your site.
  6. To apply a theme's layout templates to the various sections and pages of your site, please visit the Layout Templates section of the Content Manager's Guide.

Managing Multiple Sites

Mura can host multiple websites under a single installation. Each website can be a subdomain, or even its own unique domain entirely. In addition, each site can have multiple aliases, allowing you to choose whether or not you want users who visit your site to have their URL redirect to your "primary" domain. Beyond that, Mura offers a number of other powerful features that makes managing multiple websites a breeze.

Only users granted "Super Admin User" privileges are able to access most of the areas and features described in this section. So, if you're trying to follow along, and you don't see the links or screens described here, you will most likely have to coordinate with another member of your team who has been granted the proper credentials.

Global Settings

In the back-end administrator area of Mura, there's a special area labeled Global Settings. Here you can perform various tasks such as creating and/or managing sites, installing and/or managing plugins, and keeping your "core" up-to-date.

  • Sites
    • This area lists all websites currently managed by Mura.
  • Add Site
  • Copy Site
    • This feature allows you to copy all site files, and its content from one site, to another.
  • Plugins
    • This area lists any installed plugins, and allows you to install new plugins and/or manage and/ore delete any existing plugins. This feature is covered in the Mura Developer Guide.
  • Update Mura Core
    • Mura offers a way to keep your "core" directories and files up-to-date, with the click of a button. See the Update the Mura "Core" section for more information.
  • Reload Application
    • This feature is used when a developer makes a change to any files that require the ColdFusion/CFML server to reload and start the application lifecycle again.

How to Add a New Site

Mura can host multiple websites under a single installation. This makes it easy to host both a public-facing website, and a company-facing intranet, and/or additional web properties owned and managed by your organization.

To add a new Mura site, follow the instructions below.

  1. From the back-end administration area of Mura, select Global Settings from the main navigation, and click Add New Site.
  2. The only required form field is the "Site ID" field. Please keep in mind the text you enter here will become the directory name under Mura's {context}/sites/{SiteID}, and as such, you should not use any spaces, punctuation, dots, or file delimiters here.
  3. At a minimum, you'll probably also want to enter a "Site Name" and "Primary Domain" in order to identify, and access the site.
  4. Remember, when adding a new site, all directories and files located under {context}/sites/default/ will be copied and placed into the new SiteID directory.
  5. Additional information about adding a new site can be found in the forthcoming Installation and Setup Guide.
  6. When you're finished, click the Add button, to create your new site.
  7. You should now see your new site in the listing of sites on the Global Settings screen.

Switching Between Sites

When you're working with multiple websites managed under the same instance of Mura, you'll need to know how to switch between each site, as well as easily identify which site you're currently working with.

The most simple way to identify the website you're currently working with from the back-end administrator area of Mura is to look at the top-left area of the administrator screen. You should see a button with a down arrow icon.

In the example above, you'll see we're working with the "Default" site. As you may already know, if you click the button itself, Mura will launch a new tab or browser window, and load the home page of the current site. 

If you wish to switch to another site, simply click the down arrow next to the button, and select your desired site from the list.

Once you've made your selection, you should be able to work with your selected site.

Another Way to Switch Between Sites

Super Admin Users can also switch between sites in the back-end administrator area of Mura by selecting Global Settings from the main navigation, and clicking Sites.

In the example above, you'll see we're currently working with the "Default" site. As soon as you select another site from the listing of sites under the Current Sites tab, Mura will automatically switch you to the selected site. For example, if we select My Awesome Site from the list, you'll be taken to the Site Settings screen, and the site name in the button at the top of your screen will be updated to reflect your selected site.

 

How to Delete a Site

Super Admin Users are able to delete sites from Mura, by following the steps outlined below.

  1. From the back-end administration area of Mura, select Global Settings, then click Sites.
  2. On the Global Settings screen, the Current Sites tab contains a listing of all sites currently being managed by Mura.
  3. Locate the desired site, and click the three-dot menu, then select Delete.
  4. An Alert dialog window should open with a warning which informs you that a deleted site and all of its files and content cannot be recovered after performing this operation. If you wish to proceed, click the "OK" button. If you wish to abort this process, click the "Cancel" button.
  5. If you click OK, the site files and all of its content will be deleted, and an updated listing of sites should appear.

Site Bundles

Site Bundles are a convenient way to create backups and migrate your site(s) from on instance of Mura to another. Mura gathers all of your site's assets, including uploaded files, themes, and content to create a "Site Bundle" exported as a .ZIP file. The file can then be stored on an offsite hard drive as a backup, or handed off to a client as a completed project that can then be imported into another instance of Mura.

As you can see, site bundles can also be a great way to distribute your theme. Imagine how awesome it would be to have your theme files done, as well as a fully functional website, with sample content, and everything else so that anyone who uses your theme, will be able to see it exactly the way you intended it to be.

 

How to Create/Export a Site Bundle

When you create a site bundle with Mura, a .ZIP file will be generated. There's no need to unzip it. The file will contain data that has been exported from the database, as well as all of the assets used for the site such as images, CSS, JavaScript, and of course, any layout templates used by the originating site.

Note: Depending on the size of your site, as well as the size of your assets, site bundle files can get quite large, rather quickly. If your bundles are in the 2Gb+ range, we highly encourage you to use more traditional backup and deployment strategies.

To create a site bundle, follow the steps below.

  1. From the back-end administration area of Mura, select Site Settings from the main navigation, then click Create Site Bundle.
  2. The Create Site Bundle screen should appear.
    • Include in Site Bundle
      • Items in Trash Bin
        • Select this option if you wish to include deleted items still remaining in the Trash Bin.
      • Content Version Histories
        • Select this option if you wish to include all available version histories.
      • Content Comments and Ratings
        • Select this option if you wish to include comments and ratings submitted by site visitors.
      • Form Response Data
        • Select this option to include any form submissions.
      • Site Members & Administrative Users
        • Select this option if you wish to include the current groups and users associated with your site.
    • Also include selected Plugins:
      • If any plugins are enabled for your site, a listing of those plugins will appear with a checkbox next to each of them. You may select any plugins you wish to be included in the bundle file.
    • Server Directory (Optional)
      • You can choose where you would like the bundled .ZIP file to be stored on the server. If you choose to leave it blank, Mura will package up the .ZIP file, and will prompt you to download the file when its finished.
      • If you wish to use the "Current Working Directory" as listed on the screen, you may simply click the Select Working Directory button, and Mura will auto-populate the text area with the information.
  3. After making your desired selections, click the Create Bundle button.
  4. An Alert dialog window will appear to confirm your decision to create a bundle file. Select Yes to continue, or No to abort the process.
  5. Depending on your choice for Server Directory, you will either be prompted to download the file (if you left it blank), or you will be redirected to the Bundle Created screen, when the file is saved on the server and ready to be retrieved.

How to Deploy/Install a Site Bundle

Mura site bundles are essentially pre-packaged Mura websites. The bundle file includes content, along with the site's assets and theme files. A bundle file is typically named as MuraBundle_{SiteName}_YYYY_MM_DD_HH.zip. As you can probably already decipher, the date and time the bundle was exported is usually attached to the bundle name. This makes it helpful when you're working with bundles that have been created as backups for a particular site.

While you can upload a bundle via the user interface, as you'll see below, when deploying/installing a site bundle, we highly recommend uploading the bundled .zip file to the server. One of the primary reasons for this is because the process will go much smoother and easier for you in the long run since you can eliminate the need to upload a large file via your browser.

Note: Depending on the size of your site, as well as the size of your assets, site bundle files can get quite large, rather quickly. If your bundles are in the 2Gb+ range, we highly encourage you to use more traditional backup and deployment strategies.

Follow the steps below to deploy/install a Mura site bundle.

  1. From the back-end administration area of Mura, select Site Settings from the main navigation, then click Deploy Site Bundle.
  2. You should see the Site Settings screen, and the Deploy Bundle tab should be pre-selected for you.
  3. Review the form options below to assist you in making your desired selections.
    • Are you restoring a site from a backup bundle?
      • No - Assign New Keys to Imported Items
        • This is the default option. Unless you are actually restoring a site from a backup bundle, you should use this option.
      • Yes - Maintain All Keys from Imported Items
        • If, and only if, you are restoring a site from a backup bundle, select this option. However, you MUST be deploying the bundle to the same site. Do NOT attempt to deploy the bundle file with this option to a new site under the same instance of Mura. The main reason is because you would be attempting to overwrite existing records in the database which exist for another site, causing serious issues to occur.
    • Include
      • Site Architecture & Content
        • Select this option to include the content. This is a very common selection, unless you're only attempting to install the theme files. Also be aware that if you select this option, all existing content for the site will be deleted, and replaced with the new content from the bundle.
      • Site Members & Administrative Users
        • Select this option to import groups and users included in the bundle.
      • Form Response Data
        • Select this option to import any form submissions and content ratings from site visitors.
      • All Plugins
        • If the bundle is dependent upon plugins to function properly, you may wish to select this option.
    • Which rendering files would you like to import?
      • All
        • Selecting this option would include all "site" files, as saved in the bundle.
      • Theme Only
        • Selecting this option would leave your "site" files alone, and only import the theme files. This is independent of any selection you made for importing content. If you select this option, the theme will be imported, and the site's theme assignment will be updated as well.
      • None
        • Select this option if you don't wish to import any "site" files, or theme files.
    • Select Bundle File From Server (Preferred)
      • This is the recommended option. First, you must FTP the bundle file to a location under the Mura webroot. For example, ../wwwroot/temp/. Then, click the Browse Server button, and navigate to the location where the file resides, and select it.
    • Upload Bundle File
      • For very small bundle files, this option may work without any issues. However, many browsers and web servers have filesize limitations when submitting a form. Many bundle files exceed the filesize restriction, so it is recommended to use the first option whenever possible.
  4. After you've made your desired selections, and you're ready to deploy/import the bundle, click the Save Settings button.
  5. After your bundle has been imported, you will be taken back to the Global Settings screen.

Summary

Throughout this section, you've learned about Mura's directory structure, the differences between "core files" and "site files," as well as some basics on how to manage multiple sites, and how to use site bundles as a vehicle for distributing themes.