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:
acquia-files -> /mnt/gfs/yoursitedev
acquia-utils/
docroot/
authorize.php
CHANGELOG.txt
COPYRIGHT.txt
cron.php
files -> /mnt/gfs/yoursitedev/files/
includes/
index.php
INSTALL.mysql.txt
INSTALL.pqsql.txt
install.php
INSTALL.sqlite.txt
INSTALL.txt
LICENSE.txt
MAINTAINERS.txt
misc/
modules/
PATCHES.txt
profiles/
README.txt
robots.txt
scripts/
sites/
all
default/
files -> /mnt/gfs/yoursitedev/sites/defaults/files
settings.php
example.sites.php
themes/
update.php
UPGRADE.txt
web.config
xmlrpc.php
hooks/
library/
README.acquia
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.