[Doc] Add tutorial "Cloning the Application Code on Remote Servers"

Author: javiereguiluz

Diff for: README.md

@@ -30,6 +30,7 @@ EasyDeployBundle
 
 * [Creating a Local SSH Configuration File](doc/tutorials/local-ssh-config.md)
 * [Troubleshooting Connection Issues to Remote SSH Servers](doc/tutorials/remote-ssh-config.md)
+* [Cloning the Application Code on Remote Servers](doc/tutorials/remote-code-cloning.md)
 
 > **NOTE**
 > EasyDeploy does not "provision" servers (like installing a web server and the

Diff for: doc/default-deployer.md

@@ -98,6 +98,12 @@ common for all deployers:
   * `->deployDir(string $path = '...')` (the directory in the remote server where
     the application is deployed)
 
+> **NOTE**
+>
+> Depending on your local and remote configuration, cloning the repository code
+> in the remote servers may fail. Read [this tutorial][4] to learn about the
+> most common ways to clone code on remote servers.
+
 ### Symfony Application Options
 
 The Symfony environment must be chosen carefully because, by default, commands
@@ -308,3 +314,4 @@ return new class extends DefaultDeployer
 [1]: http://capistranorb.com/
 [2]: https://github.com/everzet/capifony
 [3]: https://github.com/symfony/symfony-demo
+[4]: tutorials/remote-code-cloning.md

Diff for: doc/tutorials/remote-code-cloning.md

@@ -0,0 +1,89 @@
+Cloning the Application Code on Remote Servers
+==============================================
+
+Some deployment strategies clone on the remote servers the application code
+hosted on an external repository (e.g. GitHub). Depending on your local and
+remote configuration, this process may fail.
+
+This article explains the most common solutions for those problems. The examples
+below use GitHub.com, but you can translate those ideas to other Git services,
+such as BitBucket and GitLab.
+
+SSH Agent Forwarding
+--------------------
+
+**Agent forwarding** is the strategy recommended by this bundle and used by
+default. If enabled, remote servers can use your local SSH keys to access other
+external services. First, execute this command in your local machine, to verify
+that you can access to GitHub web site using SSH:
+
+```bash
+$ ssh -T [email protected]
+
+Hi <your-name-here>! You've successfully authenticated, but GitHub does not
+provide shell access.
+```
+
+Now log in any of your remote servers and execute the same command:
+
+  * If you see the same output, agent forwarding is working and you can use it
+    to deploy the applications. This option is enabled by default and can be
+    changed with the `useSshAgentForwarding` option in your deployer.
+  * If you encounter the error **Permission denied (publickey)**, check that:
+    * The local SSH config file has not disabled agent forwarding for that host
+      (see [this tutorial][1] for more details).
+    * The remote SSH server hasn't disabled agent forwarding (see [this tutorial][2]
+      for more details).
+    * Read [this GitHub guide][3] to troubleshoot agent forwarding issues.
+
+Deploy Keys
+-----------
+
+If you can't or don't want to use SSH agent forwarding, the other simple way to
+clone the code on remote servers is using **deploy keys**. They are SSH keys
+stored on your remote servers and they grant access to a single GitHub
+repository. The key is attached to a given repository instead of to a personal
+user account. Follow these steps:
+
+  1. Log in into one of your remote servers.
+  2. Execute this command to generate a new key:
+
+     ```bash
+     $ ssh-keygen -t rsa -b 4096 -C "[email protected]"
+     ```
+
+     Press `<Enter>` for all questions asked to use the default answers. This
+     makes your key to not have a "passphrase", but don't worry because your
+     key will still be safe.
+  3. The command generates two files, one of the private key and the other one
+     for the public key. The deploy key is the public key. Display its contents
+     so you can copy them. For example: `cat ~/.ssh/id_rsa.pub` (you'll see some
+     random characters that start with `ssh-rsa` and end with your own email).
+  4. Go to the page of your code repository on GitHub and click on the **Settings**
+     option (the URL is `https://github.com/<user-name>/<repo-name>/settings`).
+  5. Click on the **Deploy keys** option on the sidebar menu.
+  6. Click on the **Add deploy key** button, give it a name (e.g. `server-1`)
+     and paste the contents of the public key that you copied earlier.
+  7. Click on the **Add key** button to add the key and your remote server will
+     now be able to clone that specific repository.
+  8. If the same server needs access to other repositories, repeat the process
+     to add the same public key in other repositories.
+  9. If other servers need access to this repository, repeat the process to
+     generate keys on those servers and add them in this repository.
+
+Read this guide if you any problem generating the SSH keys:
+[Connecting to GitHub with SSH][4].
+
+Other Cloning Techniques
+------------------------
+
+If you can't or don't want to use SSH Agent Forwarding or Deploy Keys, you can
+use HTTPS Oauth Tokens and even create Machine Users and add them as
+collaborators in your GitHub repositories. Read [this guide][5] to learn more
+about those techniques.
+
+[1]: local-ssh-config.md
+[2]: remote-ssh-config.md
+[3]: https://developer.github.com/v3/guides/using-ssh-agent-forwarding/
+[4]: https://help.github.com/articles/connecting-to-github-with-ssh/
+[5]: https://developer.github.com/v3/guides/managing-deploy-keys/