Improve `make shell`, add instructions for SSH in Docker (#3415)

Make `make shell` connect to the actual server container, add `make shell-root`. Currently, `make shell` spins up a brand new container, which is not particularly useful.

CONTRIBUTING.rst

@@ -29,6 +29,38 @@ If you're not familiar with `Docker <https://docs.docker.com/>`_ and
 `docker-compose <https://docs.docker.com/compose/overview/>`_, it's worth
 reading up on.
 
+Writing to external repositories
+--------------------------------
+
+:doc:`Environment variables <../admin/deployment>` like ``SSH_KEY`` and ``SSH_CONFIG``
+have no effect in a Docker setup.
+
+The `~/.ssh` folder of the host system is mapped automatically to the home
+folder within the container. In order to connect to a remote repository via SSH,
+you need to create a passwordless SSH key, and configure `~/.ssh/config`
+accordingly.
+
+Here's an example for GitHub, assuming the private key file is called
+`id_ed25519` (see also `GitHub's instructions
+<https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account>`_
+to generate a new key):
+
+.. code-block::
+
+   Host github.com
+      User YOUR_USERNAME
+      IdentityFile ~/.ssh/id_ed25519
+      StrictHostKeyChecking no
+
+The project's repository will use the format
+``git@github.com:{ORGANIZATION}/{REPOSITORY}.git`` for the ``URL`` field.
+
+An alternative approach for GitHub is to use a `Personal Access Token (PAT)
+<https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens>`_,
+and set up the project's ``URL`` as `https://` instead of `git@`. In this case,
+the ``URL`` will need to include both the PAT and username, e.g.
+``https://{USER}:{TOKEN}@github.com/{REPOSITORY}``.
+
 
 JavaScript setup
 ================
@@ -75,6 +107,8 @@ you can start an interactive shell inside a Pontoon container:
 
     $ make shell
 
+`make shell-root` is also available to log in as `root`, instead of the
+default `pontoon` user.
 
 Browser Support
 ===============

Makefile

@@ -21,7 +21,8 @@ help:
 	@echo "  setup            Configures a local instance after a fresh build"
 	@echo "  run              Runs the whole stack, served on http://localhost:8000/"
 	@echo "  clean            Forces a rebuild of docker containers"
-	@echo "  shell            Opens a Bash shell in a server docker container"
+	@echo "  shell            Opens a Bash shell in the server docker container"
+	@echo "  shell-root       Opens a Bash shell as root in the server docker container"
 	@echo "  ci               Test and lint all code"
 	@echo "  test             Runs all test suites"
 	@echo "  test-translate   Runs the translate frontend test suite (Jest)"
@@ -76,8 +77,26 @@ run: translate/dist .server-build
 clean:
 	rm -rf translate/dist .server-build
 
-shell:
-	"${DC}" run --rm server //bin/bash
+.run-container:
+	@container=$$(${DOCKER} ps -q --filter ancestor=local/pontoon | head -n 1); \
+	if [ -z "$$container" ]; then \
+  		echo "Trying to start the container" >&2; \
+		"${DC}" up --detach; \
+  		container=$$(${DOCKER} ps -q --filter ancestor=local/pontoon | head -n 1); \
+		if [ -z "$$container" ]; then \
+			echo "Error: No container running based on local/pontoon. Try running 'make build'." >&2; \
+			exit 1; \
+		fi; \
+	fi; \
+	echo $$container > .container_id;
+
+shell: .run-container
+	@container=$$(cat .container_id); \
+	DOCKER_CLI_HINTS="false" ${DOCKER} exec -it $$container /bin/bash;
+
+shell-root: .run-container
+	@container=$$(cat .container_id); \
+  	DOCKER_CLI_HINTS="false" ${DOCKER} exec -u 0 -it $$container /bin/bash;
 
 ci: test lint