The below is a follow-up to Niels' blog about Composer and why we decided to fully embrace it for Open Social. In this blog I will explain how to install and manage your Open Social sites using Composer. For this blog I'm going to assume you already have GIT, Drush and Composer installed and are familiar with GIT and Drush.
How to install Open Social with Composer locally
Before you can start with your installation you need to decide how you'd like to host your site. You can use the following templates to bootstrap your Open Social site:
You can find Open Social on Packagist. The above templates will help you download open_social and any necessary dependencies in the correct folder structure. In this example I will use the default Open Social template which can be used for any web server. All you have to do is make the webroot is configured correctly in the composer.json and the .gitignore file.
To start you have to create a fork of your goalgorilla/social_template. Have a look at the fork I’ve created of the goalgorilla/social_template here. This contains a composer.json which will help you manage all your dependencies, including any additional contributed modules, themes or libraries.
The next thing you’ll want to do is clone the fork to your local development machine, download Open Social with Composer and install your site with Drush. The below videos explain how you can do this.
Downloading Open Social with Composer
Installing your Open Social site with Drush
Run your local web-server and test your site
Congratulations! You now have a fully working Open Social installation on your local machine!
So now what? Let’s add a Google Analytics module so we know where your traffic is coming from. Composer makes it super easy to add this module:
composer require drupal/google_analytics
You will see the composer.json is updated and the module is downloaded automatically:
Your GIT status will probably look like this:
Let's push all of this to your GIT repository. Before you do, make sure to check the .gitignore thoroughly and make any necessary changes. It's a best practice to not include any database settings in a GIT repository. Because of this you might want to add public_html/sites/default/settings.php to the .gitignore file. If you are satisfied commit and push your changes to origin.
Install on production using GIT, Composer and Drush
Now that the repository is up-to-date we can use GIT to retrieve the files on production, use Composer to get the dependencies on production and use Drush to install the website.
It’s important that you use GIT to clone your repository in the correct directory. This is usually one directory above your webroot. For example:
- DirectAdmin: /home/<username>/domains/<domainname> (webroot = public_html)
- Plesk: /home/httpd/vhosts/yourdomain.com (webroot = httpdocs)
- Ubuntu 14.04 or later and Apache: /var/www (webroot = html)
Now ssh to the web-server and make sure you are in the correct folder and clone your application.
git clone my-url my-destination composer install --no-dev cd webroot drush site-install social --db-url=mysql://root:pass@localhost:port/dbname
Update to the latest version of Open Social
Making sure you’re always running the latest version of Open Social is easy! Whenever there’s a new update available on drupal.org/project/social just go to your local environment and run:
composer update --with-dependencies
That command will automatically update all packages and their dependencies to the latest version. It will change the composer.lock file.
cd webroot drush cache-rebuild drush updb drush entup drush -y fra --bundle=social
Make sure you test the site locally, verify that everything works and commit and push the changes to origin repository.
Now ssh to your production web-server and update your application.
git pull origin master composer install --no-dev cd webroot drush cache-rebuild drush updb drush entup drush -y fra --bundle=social
You can find instructions on how to update Open Social on our Documentation Guide as well.
This blog isn’t a 100% inclusive. You could also use a core configuration management workflow, push the files to production via SFTP, set the vendor directory in the public_html folder, use Docker to install your local site, use Pantheon or Platform.sh to build and update the site automatically, etc.
That said this should give you an idea on how to manage your Open Social installation with Composer. In our opinion this comes closest to a best practice for individual installations.
- GIT: use it to put your files in version control and retrieve the latest files on all environments (development, test, acceptance, production)
- Composer: use it to manage all your dependencies, including Open Social, Drupal contributions and their versions (composer.lock)
- Drush: use it to install your site, enable/ disable modules, run database updates, revert configuration via Features
If you have any additions or questions about this workflow please let me know in the comments. If you have an alternative that works even better for you I’d love to hear more about that as well!