Installing Extensions Manually

Typically, if you've installed something in your Concrete CMS site, you've done so by assigning its license to your project page on marketplace.concretecms.com, then downloading and installing it through your dashboard. It's generally a very seamless process that doesn't even require a user to touch the files they're installing!

However, if your site's hosting environment blocks your site from accessing the Concrete CMS Marketplace directly, you may need to install and update add-ons manually as a workaround. (Additionally, some developers prefer to manage updates manually to allow greater control over what their clients have at their disposal when editing a site.)

Installing a Concrete add-on manually is a little different from the usual routine, but it's still relatively painless. We'll eventually install the add-on through the dashboard as normal, but we'll first need to employ alternate means of downloading the add-on or theme's code and uploading it to your site.

First, you'll need to download a copy of the add-on's source files. On marketaplce.concretecms.com, an add-on or theme's source files are available whenever a license is not assigned to a project. If the license is assigned, you'll need to temporarily release it from your project.

After downloading a copy of the package to your local computer, you can then upload the archive it to your website. After extracting it, you will need to copy the folder to the packages directory of your site. It will then become available to install by visiting Dashboard > Extend Concrete. Here's a step-by-step breakdown:

 

Step 1: Make sure the license is available

  • Log in to marketplace.concretecms.com
  • Visit your Licenses page to view a list of everything you've purchased with your user account.
  • Find your add-on in the list, and make sure at least one instance of the license is not assigned to a project:

dealer_locator_licenses_available.pngHere you can see there are unassigned licenses available, so the "Download Archive" link appears. 

dealer_locator_no_licenses_available.pngWhen you have no licenses available, the "Download Archive" link does not appear. 

Click the "Download Archive" link to download a zip archive that contains all the files included in the package.

If your license is assigned to a project, you'll need to visit the project page that the license is assigned to, locate the license and click the "Release from Project" button.

release_license.pngOnce the add-on has been released, return to your Licenses page and locate the "Download Archive" link as outlined above.

 

Step 2: Upload the archive to your site

We recommend uploading the entire zip archive to your site's /packages directory before extracting it. This ensures that all the files arrive safely. Uploading an extracted folder via SFTP is often problematic due to failed file transfers.

 

Step 3: Extract the zip archive

Once your zip archive is in the /packages folder, log into your hosting control panel's File Manager to extract it. Here's what it would look like if your hosting company uses cPanel:

concrete_cms_extract_extension.gifconcrete_cms_cpanel_extract_screen.png

If your hosting company uses a different control panel software (Plesk, etc), this process will be somewhat different.

Once extracted, the zip archive can be deleted from the /packages folder.

 

Step 4: Complete installation from your site's Dashboard

Go to Dashboard > Extend Concrete. Your add-on should be available as "Downloaded and Ready to Install".

 

Updating add-ons manually

To update an installed package to a new version, follow a similar process. Temporarily un-assign the license as described above and download the add-on from your licenses page. You'll be served the latest version of the add-on, regardless of what version of Concrete you're running on your site.

In the next couple of steps, we are effectively going to replace the old package's folder with the new one. Move the existing ("old version") add-on's folder out of packages/ and put it somewhere else for safekeeping. Now extract the zip archive of the new version you've downloaded into packages/, right where the old one used to be.

Now we need to apply the update from our site's Dashboard. Go to Dashboard > Extend Concrete and you should be notified that a new package has been downloaded and is ready to install.

concrete_cms_addon_available_for_update.png

After updating, it's a good idea to clear your site cache. It should also be noted that while you're moving the old version's files around, any pages that are currently using the add-on may very well be broken -- so if you're performing this task on a "live" / production site, it's best to get the process over with as soon as possible.