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:
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.
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.
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.