Unfortunately in my experience unless your building a local development environment, in which everything can be started and stopped at once, and it all runs on the same machine, container linking is effectively useless.
I think Docker Swarm has fixing this on the roadmap, but for now I think Kubernetes is the only thing to take into account the fact you'll probably want to have more than one node in a Docket cluster.
Please refer to https://github.com/docker/docker/issues/9983. The Networking concepts are completely revamped using this proposal. Links are being replaced with concepts like Network and endpoints. State Distribution and Service Discovery can also be used by the Network plugins to provide an effective multi-host networking solution.
Ports inside a container aren't exposed publicly unless explicitly done.
Container linking lets containers connect to each other without exposing ports via docker.
The "linking" is exposed to the container via an /etc/hosts entry, so e.g. --link test-db:db adds "a.b.c.d db" to /etc/hosts which can be used by anything that needs it.
As mentioned by jon-wood, the simple linking approach only works with containers on the same machine unfortunately.
The concepts of Linking are being revisited via the network revamp proposal with the help of Network Plugins :
https://github.com/docker/docker/issues/9983. With the plugins providing State Distribution and Service Discovery the containers can be effectively linked across multi-host network.
Have you managed to get this setup to continue working after one of the containers restarts? That is a problem with container linking I have yet to find an answer for.
Also, the network model is being revamped via https://github.com/docker/docker/issues/9983 to provide a more flexible plugins based Networking system which can also provide multi-host solution that is more powerful than the existing single-host multi-container linking system.
Very good question, sorry I don't have a good enough answer for that right now. I only needed this setup for testing and not really a production environment, so data persistence wasn't a requirement.
Once I have a satisfactory approach, I'll post a solution.
I think Docker Swarm has fixing this on the roadmap, but for now I think Kubernetes is the only thing to take into account the fact you'll probably want to have more than one node in a Docket cluster.