Instructions to run the devcontainer locally

Author: encukou

getting-started/setup-building.rst

@@ -1186,7 +1186,45 @@ select the option ``Open in VS Code``. You will still be working on the remote
 codespace instance, thus using the remote instance's compute power. The compute
 power may be a much higher spec than your local machine which can be helpful.
 
-.. TODO: add docker instructions
+
+Building the container locally
+------------------------------
+
+If you want more control over the environment, or to work offline,
+you can build the container locally.
+This is meant for users who have (or want to get) some experience
+with containers.
+The following instructions are a starting point for
+your own customizations.
+They assume a Unix-like environment, and Docker or Podman installed.
+
+In a clone of the `cpython-devcontainers repo <https://github.com/python/cpython-devcontainers>`_,
+build the container and name it ``cpython-dev``:
+
+.. code-block:: bash
+
+   docker build devcontainer/ --tag cpython-dev
+
+(Substitute ``podman`` for ``docker`` if you use Podman.)
+
+The same command will update any existing ``cpython-dev`` container.
+Run it again from time to time -- especially if the container stops
+working for you.
+
+To run the container, run one of the following commands in a clone of the
+CPython repository.
+
+.. code-block:: bash
+
+   docker run -it --rm --volume $PWD:/workspace --workdir /workspace cpython-dev
+
+.. code-block:: bash
+
+   podman run -it --rm --volume $PWD:/workspace:Z --workdir /workspace cpython-dev
+
+Note that the container has read/write access to the working directory.
+You may want to use a separate clone of CPython, or run ``git clean -fxd``
+to remove caches and build output generated for your host OS.
 
 .. c_codespaces_end