by David Snopek on August 9, 2017 - 9:06pm

Last week, I published a super long article called Drupal 8 has left small non-profits behind... How can we fix that? which details the many issues Drupal 8 is having and their chilling affect on usage among nonprofit organizations.

It also proposes a possible path for fixing it: building an Open Source platform for nonprofit websites built on Drupal 8 and CiviCRM, available as a SaaS with hosting and support included.

We're looking for 10 nonprofits who are willing to participate in the BETA and help build it (in exchange for a FREE migration to Drupal 8 & CiviCRM).

Next week, we're planning to talk more details about how that BETA process will work! (That article is up now too!)

However, this week, I wanted to take a little break from that, and talk more about CiviCRM in Drupal 8.

So, in this article, we're goning to:

  1. Walk through how to install CiviCRM on Drupal 8. It's quite complicated now, but we're helping to improve that.
  2. Talk about why we're betting on CiviCRM and not a CRM built in Drupal. There's a couple of great, pure Drupal solutions to CRM, like RedHen or CRM Core - but we've chosen to go with CiviCRM. Why?

Read more to find out!

CiviCRM works on Drupal 8!

Contrary to popular belief, CiviCRM mostly just works on Drupal 8 :-)

The CiviCRM team did a push (with the help of some fundraising) to do most of the big work needed. However, there are a couple of small (but very hard) problems remaining around installation. But once you get it installed, you're golden!

The main problematic piece of this is handling composer.

Composer is tool for installing PHP code into applications, like Drupal. It handles the difficult problem of getting all the dependencies (and their dependencies) at a mix of versions that will work together. It's becoming adopted pretty widely in the PHP world, but is still relatively new. Drupal 8 is built on it.

Both Drupal 8 and CiviCRM use Symfony and a couple other shared dependencies. So, the core CiviCRM code needs to be installed into your Drupal 8 site with composer, in order to combine everything together in a way that works. CiviCRM does use composer, but it's pretty early days.

Over the last several weeks, we've been helping to improve CiviCRM's composer support so it could be correctly installed into a Drupal 8.3 or 8.4 site.

Not much of this work has been merged yet, but we have a reproducible set of steps for getting CiviCRM installed that you can use today!

Getting started the easy way

In the next section, we're going to describe the manual process to add CiviCRM to an existing Drupal site.

However, if you just want to launch a new site with all the CiviCRM stuff already there, we have an "easy way" for you!

We made a project on GitLab with all the composer stuff already done and the Drupal module included and patched! Here's the process:

  1. Download the ZIP or TAR.BZ2 file (linked version is Drupal 8.3.7 + CiviCRM 4.7.22)
  2. Install just like vanilla Drupal 8
  3. Go to the "Extend" page (at /admin/modules) and install the CiviCRM module
  4. Log out and log back in again per CRM-19878

I don't know how long we'll maintain this specific repo, but I'll try to keep it up-to-date until we have some code publicly available from the BETA of our Drupal 8 & CiviCRM platform which will replace this.

The full, manual process

If you want to add CiviCRM to an existing Drupal 8 site, you'll have to follow the manual process.

(Note: Currently, CiviCRM won't work with the 'vendor' directory outside of the web root. So, if you have a 'web' and 'vendor' directory that are siblings rather than 'vendor' being inside of the top-level web root, it won't work. CiviCRM issue pending!)

Once all these little (but very hard!) problems are fixed, and the fixes are merged into CiviCRM and related libraries, it'll be a single composer command to get CiviCRM added to your existing Drupal 8 site.

However, right now, the manual process is not so easy.

But if you wanted to do it, we have a reproducible process that you can follow!

  1. Download and install Drupal 8.3.6 (or the latest dev of Drupal 8.4.x!)
  2. Go into the root directory in the shell and run these commands to install CiviCRM via composer (one day this will just be composer require civicrm/civicrm-core). Assuming you have composer, bower, git and wget, you should be able to just copy-and-paste those commands into the command-line.
  3. If you use Apache, remove the 'vendor/.htacess' file. This is a security measure from Drupal, which prevents resources like CSS/JS being loaded. This will need some collaboration with the Drupal project to figure out a proper solution for because removing this file altogether is a bad idea on production. See:
  4. Go into the /modules directory and do: git clone --branch roundearth
  5. Go to the "Extend" page (at /admin/modules) and install the CiviCRM module
  6. Log out and log back in again per CRM-19878
  7. CiviCRM works!

As we've been making progress on the changes for CiviCRM to better support composer, I've been removing commands from the Gist with the special process in step #2, which I plan to continue doing until it's not necessary.

If you have problems (or succeed), I'd really appreciate the feedback!

(And if you post those problems or successes on the PR on GitHub, it'll help move forward the process of committing those changes!)

Why CiviCRM and not RedHen (or other pure Drupal solution)

So, with all that trouble to get CiviCRM working, why even use it?

Drupal is a powerful framework for building awesome things. Why not make some new entity types for CRM-y things like Contacts and Activities, throw some fields on there and make a pure Drupal CRM? There's even some great pre-existing Drupal modules like RedHen and CRM Core to build on.

Drupal can do anything, why not a do a CRM? ;-)

We fell into CiviCRM sort of by accident. A strong plurality of our customers are nonprofits and many of them use CiviCRM, so, we had to start supporting it!

We found that, for many of them, their CiviCRM was actually more important to their daily lives and the operation of their organization than the website.

After spending some time with CiviCRM, we're doubling down on it for our new nonprofit Drupal 8 platform. Here's why...

CiviCRM community is larger than any Drupal CRM module

The CiviCRM community is much smaller than the Drupal community, but much larger than the community around any of the Drupal CRM modules.

The core CiviCRM team is only 4 people, but they work on CiviCRM full-time. (And they don't do CiviCRM installations or paid support or anything like that - they only work on core issues that benefit the whole community.)

There are regional CiviCon's and CiviCamps and monthly meetups - all over the world.

There are multiple books written about CiviCRM.

There are 67 partner/contributor organizations listed on, who provide any number of services: setting up CiviCRM installations, doing trainings, providing support & maintenance, SaaS hosted versions of CiviCRM, etc. And there's probably even more commercial companies out there!

While it would be really cool, I can't really imagine there being four RedHenCon's held in the UK, US, Australia and Germany in a single year, like the 4 CiviCon's scheduled in 2017. :-)

CiviCRM is a complete product

Most Drupal modules are legos, not complete products.

Of course, there are exceptions, but usually you're expected to assemble a set of modules into a thing, rather than a module being a thing.

CRM Core and RedHen are a set of tools in order to build a CRM. They are not complete CRM's on their own.

We could certainly make a CRM as complete as CiviCRM by combining Drupal modules. But none that are out there are quite as complete as CiviCRM, especially, with regard to nonprofits...

CiviCRM is really well suited to nonprofits

The best CRM is one built specifcally to the needs of your organization. For this reason, all CRM's are customizable to some degree, but most CRM's are closer to the needs of certain organizations.

For example, at myDropWizard, we use HubSpot for our CRM. We're a commercial support & maintenance company, so the most useful feature in HubSpot for us is configurable "deal workflows" and seeing all active deals in a workflow-specific kanban board.

We wouldn't be able to use CiviCRM because it's completely missing this feature. But nonprofits don't miss it because their businesses don't depend on deal flow. By the same token, a nonprofit would be missing the pledge, fundraising, grant and volunteer management features that are present in CiviCRM if they tried to use HubSpot.

By focusing only on the needs of nonprofits, CiviCRM has been able to grow into a really killer piece of software for nonprofits.

RedHen and CRM Core are also slanted to towards nonprofits, but seem to leave the door open to being more general, and haven't grown to support as many use cases that are important to nonprofits.

CiviCRM has less "vendor lock-in"

Since Drupal is Open Source, there really isn't true "vendor lock-in" - there are loads of Drupal shops who can help you and you're free to switch.

But we've seen how hard it can be to move from Drupal 6 or 7 to Drupal 8, where people can get stranded in an old version.

The same version of CiviCRM can work in Wordpress, Joomla, Backdrop or Drupal 6, 7 & 8.

If you have a Drupal 6 site using the latest CiviCRM, you can move the core CRM piece to either Wordpress or Drupal 8, basically unchanged. CiviCRM has it's own extension system, which allows the same extension to be used in any supported CMS.

Of course, if you're using Drupal modules that interact with CiviCRM, those would need to be ported just like any Drupal module.

But I think just knowing there is this extra freedom to migrate is good for users who may be concerned about the long-term prospects of Drupal 8.

Join our BETA!

Like I said in the intro we're building an Open Source platform for nonprofit websites built on Drupal 8 and CiviCRM, and looking for nonprofits to be a part of the BETA.

If you're interested, please click the big green button below to...

Join the BETA or get progress updates

We're going to be announcing more details about the BETA next week, but you can read what we're already said about it in last week's article. (The next article is up now too!)

Have any experience with CiviCRM? Good or bad? Tried installing it in Drupal 8? Please leave a comment below!


Want to read more articles like this? blog Subscribe to the blog and recieve e-mail updates when new articles are published!


Thank you!

Yep thanks for pushing on with this work, and to the others in the CiviCRM community who pushed on with this work after Fuzion took it through the first few rounds. When we started with CiviCRM and Drupal, around 10 years ago, we were advised by several Drupal shops to 'just do it with Drupal', but we agree that having a 'complete CRM' that works with Drupal, and actually gets better with Drupal (thanks to the Views, Webform, Entity integrations), is a great combination

Hi - I'm excited about this - I've been waiting to be able to use CiviCRM with D8! I just tried a new site with your "easy way", but when I get to step 3 and go to Install the CiviCRM module, I get a page with an Initialization Error that my database credentials are no good and access is denied. I can't recover from this - can't use any of the D8 site, even outside of CiviCRM functions. I have to delete everything and start over. I've tried 3 times now, getting the same results each time.

Am I missing something in the installation? With D7 I had to install CiviCRM from a separate URL. Do I not do that here in D8? Can you help me understand this better?

Hm. This is not a problem that I've encountered! I tried following the directions with the tarball before publishing the blog post. :-)

Can you share the exact error message? Is there anything interesting in the logs? What version of PHP are you using? Does the civicrm.settings.php get created? Are the database credentials in civicrm.settings.php and settings.php correct? Is there anything weird in either file after installation?

With D7 I had to install CiviCRM from a separate URL. Do I not do that here in D8? Can you help me understand this better?

Yeah, that's the CiviCRM installer - there isn't one for Drupal 8 yet, it just installs when you enable the module (into the same database as Drupal with all default settings).

Hi David, and thanks for the prompt reply! I solved that problem with a little more digging. Turns out that I had a symbol (quotation mark) in my database password which was being escaped in civicdm.settings.php. Un-escaping it (as it was in settings.php) solved the problem.

But now I've got a new one. I enabled CiviCRM Views and was immediately greeted with this fatal error message:

Fatal error: Call to undefined function civicrm_api3_create_error() in /home/concordcomm/public_html/vendor/civicrm/civicrm-core/Civi/API/Kernel.php on line 413

Any insight for me on that one? Normally I'd just use composer to remove the module and re-install it, but I'm reluctant to do that with the custom code. For now, maybe I'll start over one more time and just not enable that module, so I can test drive CiviCRM core.

Thanks again.

Aha! Glad you worked it out :-)

The civicrm_views thing is another small bug - I made a PR to fix it a couple weeks ago but it hasn't been merged yet:

I'll get that patch merged into our Git repo in a little bit..

You should be able to disable the civicrm_views module via Drush, though, and at least get your site back to working!

I added all our patches to the Drupal module in the Git repo and made a new release:

So, this has the fix for civicrm_views and our port of civicrmtheme too :-)

I'll update the main blog post to link that tarball, so other don't hit this problem!

Thanks David - I'll get the patch applied at some point. I've been poking around with the core module, and it's working great!

Hi, some years ago, I was like you convinced that CiviCRM should be the best and easiest solution to get a CRM running for our EU based NGO. But after installing CiviCRM and 2 days of trying to understand and modify CiviCRM to my needs I was somehow wondering about the very American style set up. It looked great to me for an American Political or Civil Society movement but somehow far from our EU-realities. Here an NGO is mainly working with public findings and less with private donors in between CiviCRM is mainly built for private contributions and special attention to VIP donors. The other irritation I had with CiviCRM in comparison to Drupal own buildings were the inflexibility on layout level. I decided then to switch to CRM Core, which was much easier to adapt to my specific EU related needs.
But now as Drupal 8 is out I get again the problem you mentioned: CRM Core is not ready for Drupal 8 and Redhen is only partly usable. Here your argument is very correct: CiviCRM has the bigger community and finances for a core team of developers. It is less flexible, but more long term orientated. Si eventually I have to come back on CiviCRM and try to adapt it this time more to EU related NGO administration, just because there is no better alternative and no resources from my side to develop a whole own Drupal entity CRM. So thanks a lot fr your CiviCRM Drupla8 installation guide

Hey David,

I read your post from last week (which I thought was great) and was glad to see this D8 followup. Just did your 'easy way' install (w/ acquia_dev_desktop on mbp) and it worked great. Thanks for that!

Seems to me like the logical next step is to get ported to D8?

Awesome! Thanks for trying it and following up to let me know :-)

Yeah, I agree about civicrm_entity. I did some experimenting in Drupal 8 and a made a barely working D8 entity type for CiviCRM Events. I'm waiting to figure out where this port work will be done (see CRM-20055), and, of course, kicking off our BETA project, but we're definitely planning on contributing to that port!

I'll create the branch here shortly, just fork my repo, and make a PR, and I'll take a look. I have a lot of things in mind, and some different things I want to do than with the D7 version.

The biggest thing is I want to have properties be fields, so we can have true field formatters and widgets. I want to redo how custom fields are handled as well. Instead of them being properties/fields on the various API entities, I'd like to do a "remote reference" style field and use the CustomValue API, so we can much better support multi-valued field groups. In CiviCRM fields don't have multiple values, its the field groups that its a trick to translate that to the Drupal pattern.

I look forward to working with you!

So actually it may be that CiviCRM Entity, at least the core parts of the main module, will get into CiviCore....
I think the community is close to a decision on that...

David, I've pushed a branch to the civicrm_entity github repos....

You can fork that and issue a merge request for you stuff....

We can develop there and if this gets into core, we'll copy the code to a submodule in the 8.x-master branch

In the mean time I'm happy to get going too....

I have a lot of ideas for the architecture for the D8 module....How can I get in touch with you best? I'd love to have a skype call or something to discuss architecture planning with you. I don't want us double doing work.....I think we team up and get this thing rolling...
Thoughts on that?
All interested parties, contact [email protected]

Thanks, Mark! Sorry for not getting back to you on the various CiviCRM issues/PRs - it's been on my TODO since the weekend, but I've been insanely busy talking to folks interested in our BETA and figuring out the details for that, that I haven't had time to dig into technical stuff all week. Unfortunately, the schedule for next week is shaping up to be quite similar so far. :-/

But civicrm_entity is the next big technical thing that I want to hack on!

I'd be more than happy to do a Skype call. I definitely don't want to do double work either! I'll send you an e-mail and we can figure out a time to chat and plan. But like I said above, I might not be able to do any serious coding for a week or two.

As to the speed, I understand, I work full time too on client projects.
The speed of getting released, is not as important as the quality of which we create the module. Getting a project plan and some working prototypes in the next few weeks would be great, and then with that, we can just rock and roll on it, with the plan, I can say to all current contributors and people of like mind, here's what we're building, help out where you can!

Yep, I'm maintainer for the CiviCRM Entity project, and now development of the D8 version will begin. Its going to be a bit of a job, so we're considering starting a Make it Happen initiative to help fund the efforts. Please contact Skvare, if you want to help with money or code, I'll have the branch setup soon...
main development is being coordinated at

Thanks very much for pushing this forwards. My organisation is currently operating on Drupal 7, and we have kind of established our own CRM structure in Drupal (as you pointed out, adding lots of fields and some personalised code). However, this is rather inconvenient and requires a lot of work and maintenance, and we were thinking of upgrading to a 'proper' CRM (such as CiviCRM) for a long time. However, having worked with D8 for a while, I think there are many improvements that I would really like to take advantage of. Hence, I've been impatiently waiting to see updates on the D8 status of CiviCRM, and I am happy to read your report that this is now operational, even if it's still at an early stage. I will take a look at this soon, and will try to set it up to test whether is will suit our needs.

Thank you very much for this effort. I tried to follow the full manual installation instructions above on Drupal 8.4.0. I had two issues.

First, I got an error when I tried to run this command (something about the version not meeting my requirements):
composer require "civicrm/civicrm-core:dev-roundearth-$CIVICRM_VERSION as $CIVICRM_VERSION"

I used this instead and it seemed to work:
composer require "civicrm/civicrm-core:dev-composer-library-$CIVICRM_VERSION as $CIVICRM_VERSION"

I followed the rest of the directions and then ran into this error when I tried to activate CiviCRM under the Extend Admin tab:
CiviCRM must be downloaded into the libraries folder.

Any idea what I did wrong or what I need to do to get Civi working?

Thanks for giving the instructions a try!

I ran through the instructions again, starting with Drupal 8.4.0 and found some errors in the steps. Namely, we recently switched from using a fork on GitHub on my personal GitHub account, to a shared company repo on the company GitHub and, while I updated the branch name in my Gist, I forgot to update the repo. That's the reason the 'composer require' you tried didn't work. I've updated the Gist and the 'git clone' command in the article for getting the Drupal module, which is affected by the same change.

But after updating that, I was able to enable the CiviCRM module just fine...

Are you starting from the Drupal 8.4.0 release tarball or a composer template (ie. via 'composer create-project ...')? Right now, I don't think CiviCRM can work if the vendor directory is outside of the webroot, but I have some ideas about how to fix that.

The website/project I'm working on started out as a Drupal 8.3 site created with Composer. When 8.4.0 was released, I updated the project via Composer. It was at that point, I started to investigate using Civi for a member system (versus making some custom entity types) and found your instructions. I am not an expert at Composer and would probably best describe myself as a super site builder more so than a developer. I'm really good at following tutorials. :-) So my set-up might be different than what you were anticipating (yet should be compliant with the tutorials on D.O. and

The <folder> structure is as follows:
<project name>
----------<web> (this is the root of the Drupal installation)

Is this different than what you expected? Should I try to start over from scratch? When do you think you'll have Civi fully in the Composer repository?


Aha, yes, you have the 'vendor' and 'web' directories as siblings, whereas currently CiviCRM will only work if the 'vendor' directory is inside the web root. I'm going to update my article to say that this doesn't work yet, and open an issue to get it working. I have some ideas and it should be possible, but we have to work around some assumptions that the CiviCRM code is making.

If you want to get CiviCRM working right now, yes, unfortunately, you'll have to start over with a different directory structure. However, if you can wait a bit (days or weeks?) then we can probably get this problem fixed.

Ok. From what I've researched, best practice for security reasons seems to be putting the vendor folder outside the web folder since it would not be accessible from the web. I'm guessing this is why that is the default setup with Composer?

Yes, that absolutely is the best practice in the wider PHP community, but still isn't the default way of running Drupal 8 or CiviCRM. If you used or BLT, it would put the 'vendor' folder outside of the web root per best practice, but that isn't yet supported in CiviCRM due to a number of assumptions it makes.

Add comment