TL;DR: If you get Symbolic link not allowed or link target not accessible errors, use relative symlinks to avoid permissions issues with absolute symlinks, and generate nested symlinks relative to their actual directories.

I ran into some trouble setting up Deployer on Media Temple’s Grid service, and it took me awhile to find out the answer, so I figured I’d share it here.

I kept running into problems when trying to symlink Apache’s DocumentRoot directory to the latest deployment release. The site would just show a generic error template generated by Media Temple, and Apache’s error log would say:

Symbolic link not allowed or link target not accessible

It turned out that there were two problems going on.

The First Problem: Permissions

If a symlink uses an absolute path, then accessing it requires permissions on all the directories above it, all the way up to /. In a shared environment, your user is usually chroot’ed into your home directory, so you won’t be able to do that.

To avoid that, you can use relative symlinks instead.

If you’re also setting up Deployer, you can watch #503 for a permanent fix, or try to use the fix I came up with for my use case.

The Second Problem: Relative Symlink Confusion

When creating relative symlinks inside a directory that itself is a symlink, you introduce the possibility for another problem, though. In order to work, symlinks have to be created to point to their target, relative to their actual location, rather than the linked location. That isn’t obvious, because Bash keeps track of all that for you when navigating the filesystem.

The easiest way to do that is to just cd to the actual location, and create the symlink from there.

General Lessons

A few general lessons that would have saved me some time and frustration:

1. Instead of trying to setup a lot of pieces at once, break things into small steps, and get 1 thing working at a time. If there are too many things going on at once, you might introduce additional problems because of the interactions between the different pieces. That can also cause you to not notice when one of the problems is partially fixed, because the other problems are still breaking things.
2. Create a minimal test case, to remove irrelevant pieces that complicate the problem. It would have been much easier to figure out the exact way to get the links working if I manually setup a matching folder structure and played around with it.