---
title: "Structure Your Drupal Repository"
date: "2022-04-22T15:27:59+00:00"
summary:
image:
type: "article"
url: "/acquia-cloud-platform/help/91626-structure-your-drupal-repository"
id: "31a7ed67-7096-4c40-9e14-d665b859cd52"
---

Table of contents will be added

Goal
----

Learn how to properly structure your Drupal repository according to Acquia’s best practices.

1.  The Acquia Way™ to structure your Drupal repository
    ---------------------------------------------------
    
    There are many ways to organize your Drupal repository. At Acquia, we have a preferred structure that will make your development efficient and your application easy to maintain (e.g., with Composer). It will also ensure that your application is fully compatible with all Acquia products.
    
    If you’re starting a new project, we recommend using one of our starting templates. Our best practices (e.g., Composer configuration, `.gitignore` values, etc.) are already baked-in.
    
    Otherwise, follow the guidelines listed below to ensure that your existing application is structured according to our recommendations.
    
2.  To be hostable on Acquia Cloud Platform
    ---------------------------------------
    
    There are a few “bare minimum” requirements for your Drupal application to function on the Acquia Cloud Platform:
    
    *   Your Drupal root (where Drupal Core’s index.php is located) must be located in a directory named `docroot`.
    *   Your `settings.php` file must include an [Acquia require line](/node/56321)
    
    \[info block\] if you’re using [Acquia BLT](https://github.com/acquia/blt/), this is done for you automatically.
    
3.  To be manageable with Composer
    ------------------------------
    
    When Drupal 8 was released in 2015, Composer became the way to manage dependencies for your Drupal applications (or _any_ PHP application for that matter).
    
    As with any framework, there are some framework-specific conventions that should be followed. Drupal is no different in that regard. In the Drupal community, we sometimes call those “Drupalisms.”
    
    In order to make your application easy to manage via Composer, you should follow [these conventions](https://github.com/acquia/drupal-recommended-project/blob/master/composer.json):
    
    *   Your `composer.json` and `composer.lock` files must be in the root directory. I.e., not in a subdirectory like `docroot`.
    *   Your `composer.json` and `composer.lock` files should be committed via git (not gitignored). [This is a well established best practice for Composer.](https://getcomposer.org/doc/01-basic-usage.md#commit-your-composer-lock-file-to-version-control)
    *   Your composer file should include Drupal specific configuration. At a minimum, it should:
        *   List drupal.org as a source of packagist repository. See [`acquia/drupal-recommended-project` for example configuration](https://github.com/acquia/drupal-recommended-project/blob/master/composer.json).
        *   Place Drupal projects in the correct directories. See [`acquia/drupal-recommended-project` for example configuration](https://github.com/acquia/drupal-recommended-project/blob/master/composer.json).
        *   Define the Drupal’s root directory as `docroot`.
            
            See [`acquia/drupal-recommended-project` for example configuration](https://github.com/acquia/drupal-recommended-project/blob/master/composer.json).
            
4.  To be compatible with Acquia Code Studio
    ----------------------------------------
    
    [Acquia Code Studio](https://www.acquia.com/products/drupal-cloud/code-studio) is a Drupal optimized version of GitLab hosted by Acquia. One of its most powerful features is AutoDevOps—a “Zero configuration required” CI/CD pipeline that is optimized specifically for Drupal.
    
    To take advantage of AutoDevOps:
    
    *   Composer dependencies should NOT be committed. See [acquia/drupal-recommended-project for example `.gitignore` file.](https://github.com/acquia/drupal-recommended-project/blob/1f8f74c5f0945e8c590ba998721fdd2693a397f4/.gitignore#L6-L18) E.g.,
        *   `/docroot/core`
        *   `/docroot/libraries`
        *   `/docroot/modules/contrib`
        *   `/docroot/profiles/contrib`
        *   `/docroot/themes/contrib`
    
    For long-time Drupal developers, this may seem like a strange convention. But, it’s a [well established best practice for Composer](https://getcomposer.org/doc/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md#:~:text=The%20general%20recommendation%20is%20no,Composer%20to%20install%20the%20dependencies.) and for software more generally.
    
    For a deeper discussion of this concept, see [Tutorial: Deploying a Composer Managed Drupal application](#).
    
5.  Related Resources
    -----------------
    
    *   Tutorial: Creating a new Drupal application with Composer (dev.acquia.com)
    *   Tutorial: Deploying a Composer Managed Drupal application (dev.acquia.com)
    *   [Should I commit the dependencies in my vendor directory?](https://getcomposer.org/doc/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md#:~:text=The%20general%20recommendation%20is%20no,Composer%20to%20install%20the%20dependencies.) (getcomposer.org)
    *   [Using Composer to Install Drupal and Manage Dependencies](https://www.drupal.org/docs/develop/using-composer/using-composer-to-install-drupal-and-manage-dependencies) (drupal.org)
    *   [Recommended Drupal project for use on Acquia Cloud](https://github.com/acquia/drupal-recommended-project) (github.com)
        
    *   [Minimal Drupal project for use on Acquia Cloud](https://github.com/acquia/drupal-minimal-project) (github.com)