docs(dev): provide instructions to setup Polar with DevContainers

CONTRIBUTING.md

@@ -6,7 +6,115 @@ This guide will walk you through setting up your local computer to be able to co
 
 Polar is a desktop application with its code written with web technologies (HTML5, CSS3, Javascript) at the lowest level. At a higher level, we use [Typescript](https://github.com/microsoft/TypeScript), [ReactJS](https://github.com/facebook/react/), [Redux](https://redux.js.org/) via [easy-peasy](https://github.com/ctrlplusb/easy-peasy), and CSS-in-JS via [Emotion](https://emotion.sh/). The web app is hosted in a desktop shell powered by the [Electron](https://www.electronjs.org/) cross-platform application framework.
 
-### Pre-requisites
+### Docker approach (manual)
+
+The development environment for Polar can be setup with docker. First, we
+describe manual setup.
+
+```bash
+tag='polardev'
+docker_gid_host=$(getent group docker | awk --field-separator : '{print $3}')
+docker image build --build-arg="DOCKER_GID=${docker_gid_host}" --tag polardev .devcontainer/
+```
+
+The `docker_gid_host` gets the GID of the docker group in the host machine,
+which is added to the non-root user in the container in build time. This is
+required if we want to use the Polar UI during development, which needs to
+connect to Docker (more on that later). This GID is not fixed but varies
+accross OS: 996 on ArchLinux, 969 on Debian, 999 on Ubuntu.
+
+If you want to use the UI, run the following command to enable forwarding
+graphical applications from the container to the host:
+
+```
+xhost +local:docker
+```
+
+Now that the image is built, we can run it:
+
+```bash
+cd polar/
+docker container run \
+	--volume "$PWD":/app \
+	--volume /tmp/.X11-unix:/tmp/.X11-unix \
+	--volume /var/run/docker.sock:/var/run/docker.sock \
+	--volume "${HOME}/.config/polar":/home/dev/.config/polar \
+	--volume "${HOME}/.polar":/home/dev/.polar \
+	--env "DISPLAY=${DISPLAY}" \
+	--name polar \
+	--detach \
+   --rm \
+	polardev \
+	sleep infinity
+```
+
+The above command runs a container in detached mode, putting it to sleep forever.
+The sleep command does not consume CPU or RAM, so the container is kept alive and
+we can execute commands on it.
+
+Let's see an explanation of the volumes:
+
+- `--volume "$PWD":/app` mounts the Polar application on the container.
+- `--volume /tmp/.X11-unix:/tmp/.X11-unix` allows X11 graphical applications to
+  be forward from the container to the host.
+- `--volume /var/run/docker.sock:/var/run/docker.sock` allows Docker-In-Docker,
+  which is required for the Polar UI to work (it needs to access Docker).
+- `--volume "${HOME}/.config/polar":/home/dev/.config/polar` persists configuration storage.
+- `--volume "${HOME}/.polar":/home/dev/.polar` persists data storage.
+
+Now that the container is running, we can run some commands:
+
+Install the packages:
+
+```bash
+docker container exec polar yarn package
+```
+
+Notice that the first argument after `exec` is the container name (`polar` in our case).
+
+Run linter:
+
+```bash
+docker container exec polar yarn lint
+```
+
+Run tests:
+
+```bash
+docker container exec polar yarn test
+```
+
+Build the app for the current platform (the container platform is Linux):
+
+```bash
+docker container exec polar yarn package
+```
+
+Start a graphical UI for development, which reflects changes in real-time:
+
+```bash
+docker container exec polar yarn dev
+```
+
+The last example requires that the container was properly configured to allow
+X11 forwarding, as it was explained in the first steps.
+
+### Docker approach (Vscode devcontainers)
+
+Install Vscode devcontainers extension and run `Dev Containers: Open Folder in
+Container...` from the command palette. This will open the folder in the
+container and allow running headless commands.
+
+If you also want to run the UI using devcontainers, then go back to the manual
+approach, start the container as instructed in order to map the proper volumes
+and allow X11 forwarding of graphical applications. Then, run `Dev Containers:
+Attach to Running Container...` and select the already running container. This
+will open Vscode on the existing container with UI support. You can then run
+`yarn dev` to launch the UI.
+
+### Local approach
+
+#### Pre-requisites
 
 There is some software that is required to compile and run Polar locally. You'll need to visit the websites to find installation instructions for your operating system.
 
@@ -19,7 +127,7 @@ There is some software that is required to compile and run Polar locally. You'll
 
 Once you have all of the required software installed, you can proceed to setup your local environment
 
-### One-time Environment Setup
+#### One-time Environment Setup
 
 These steps only need to be performed one time on your machine