File permissions on both Cloud Platform and other Acquia offerings require careful handling when you are changing code or other files on your website. For security reasons, write permissions are disabled in both the live website and in the website repository, which prevents malicious individuals from attacking either of them.

Your website has the following three major areas:

• docroot: Where the website is actually served from.
• repository: Where a duplicate of your codebase and PHP files are stored.
• files area

The docroot directory is not writable. Any folder with an active settings.php file (often found in sites/default/files) will add a symlink to the files area. With the symlink in place, files placed in the file system appear located in the file directories where Drupal expects them to be, without requiring write access to the code repository files in the docroot.

Anatomy of your website

The following diagram indicates the directory structure of a generic website, from the repository to the docroot directory, and where the symlinks exist in that docroot directory:

Understanding how this works is important because without the right permissions, your website may fail to work. This can be a problem when you expect things to stay the way that you set them in version control. Git, for example, does not store any permissions (aside from the executable bit). Read and write, sticky, or Access Control List (ACL) bits are lost when you commit changes. For more information, see What does git do to files that are a symbolic link.

If you are experiencing a problem with permissions, Cloud Platform may display error messages similar to the following example:

file system: The selected file /mnt/tmp/mystg/filemyfile could not be uploaded, because the destination sites/default/files/js/myjsfile.js could not be found, or because its permissions do not allow the file to be written.

Multisite installations can be a bit trickier, because all websites in a subscription can share the same codebase and the same symlinks.

The best practice is to symlink only the directory that needs write access. As an example, to create the correct links for a module that needs its own cache directory, you would use commands similar to the following (where [email protected]:yoursitename.git is your Git URL, which can be found on the Cloud > Workflow page):

git clone [email protected]:yoursitename.git
cd yoursitename/docroot/sites/all/modules/examplemodule
rm -rf cache ln -s ../../../default/files/cache cache
git add cache
git commit -m "creating symlink for examplemodule cache"
git push origin master

After pushing the code, you must access the infrastructure and create the new cache directory in your files directory. If you do not, when the code deploys, the symlink will point at a non-existent target. After you have created the directory, use either SCP (Secure Copy) or SFTP (Secure File Transfer Protocol) to transfer any files you had temporarily stored and need to replace.

Known problem modules

Several contributed modules available on Drupal.org should be used with caution with websites hosted on Cloud Platform because the modules expect the module’s folder to be writable. For a list of modules with known problems, see Modules to use with caution on Cloud Platform.

File permissions and symlinks while using Cloud Platform

File permissions on both Cloud Platform and other Acquia offerings require careful handling when you are changing code or other files on your website. For security reasons, write permissions are disabled in both the live website and in the website repository, which prevents malicious individuals from attacking either of them.

Your website has the following three major areas:

• docroot: Where the website is actually served from.
• repository: Where a duplicate of your codebase and PHP files are stored.
• files area

The docroot directory is not writable. Any folder with an active settings.php file (often found in sites/default/files) will add a symlink to the files area. With the symlink in place, files placed in the file system appear located in the file directories where Drupal expects them to be, without requiring write access to the code repository files in the docroot.

Note

To ensure links remain correct across infrastructure environments, Acquia recommends you use relative symlinks with Cloud Platform.

Anatomy of your website

The following diagram indicates the directory structure of a generic website, from the repository to the docroot directory, and where the symlinks exist in that docroot directory:

Understanding how this works is important because without the right permissions, your website may fail to work. This can be a problem when you expect things to stay the way that you set them in version control. Git, for example, does not store any permissions (aside from the executable bit). Read and write, sticky, or Access Control List (ACL) bits are lost when you commit changes. For more information, see What does git do to files that are a symbolic link.

If you are experiencing a problem with permissions, Cloud Platform may display error messages similar to the following example:

copy

file system: The selected file /mnt/tmp/mystg/filemyfile could not be uploaded, because the destination sites/default/files/js/myjsfile.js could not be found, or because its permissions do not allow the file to be written.

Multisite installations can be a bit trickier, because all websites in a subscription can share the same codebase and the same symlinks.

Note

If you have one website directory symlinked to another in Cloud Platform, when a symlink is created it will take on the name of the first website in the directory by alphabet. This means that if you have two websites, docroot/sites/test, and docroot/sites/a-test, regardless of which website the symlink was initially created under, the symlink will use the path docroot/sites/a-test.

The best practice is to symlink only the directory that needs write access. As an example, to create the correct links for a module that needs its own cache directory, you would use commands similar to the following (where [email protected]:yoursitename.git is your Git URL, which can be found on the Cloud > Workflow page):

Important

These instructions delete a directory; before you process the delete (rm -rf), ensure that you have copied the files to the new location or to local storage for later replacement.

copy

git clone [email protected]:yoursitename.git
cd yoursitename/docroot/sites/all/modules/examplemodule
rm -rf cache ln -s ../../../default/files/cache cache
git add cache
git commit -m "creating symlink for examplemodule cache"
git push origin master

After pushing the code, you must access the infrastructure and create the new cache directory in your files directory. If you do not, when the code deploys, the symlink will point at a non-existent target. After you have created the directory, use either SCP (Secure Copy) or SFTP (Secure File Transfer Protocol) to transfer any files you had temporarily stored and need to replace.

Known problem modules

Several contributed modules available on Drupal.org should be used with caution with websites hosted on Cloud Platform because the modules expect the module’s folder to be writable. For a list of modules with known problems, see Modules to use with caution on Cloud Platform.