docs: add container usage documentation

docs/README.md

@@ -13,6 +13,8 @@ Welcome to the Disco documentation!
 - [Getting started guide](./get_started.md): a short guide to using Disco.
   New users should start here.
 
+- [Container usage](./container.md): tutorial for using Disco inside a Linux container.
+
 - [System](./system.md): system architecture and behavior.
 
 - [Roles](./roles.md): role-based access control features.

docs/container.md

@@ -0,0 +1,51 @@
+# Container usage
+
+Running Disco inside a container is recommended for increased security. It allows storing the encryption key as a secret, which protects against exposing it to the shell history and other running host processes.
+
+The following are instructions for setting up this workflow.
+
+1. Install [Podman](https://podman.io/docs/installation) and [podman-compose](https://github.com/containers/podman-compose).
+
+> [!NOTE]
+> While this workflow can be done with Docker, we recommend using Podman instead.
+> The secret functionality in Docker requires enabling Swarm mode, which is not
+> required (or supported) in Podman. Podman can also be used without root
+> permissions, though running it as root is an additional layer of security,
+> since it requires typing the sudo password.
+
+2. Pull the image of the latest stable version of Disco:
+   ```sh
+   podman pull docker.io/hackfixme/disco:latest
+   ```
+
+3. Initialize Disco, creating a Podman volume so that the data is persisted between runs, and at the same time create a Podman secret from the output:
+   ```sh
+   podman run --rm -it --volume disco:/opt/disco hackfixme/disco:latest init \
+   | tee /dev/tty | head -1 | sed 's:.* ::' | podman secret create disco_key -
+   ```
+
+   You can also manually copy the key and create a secret, but this way avoids storing
+   the key in your clipboard, or risking the key being stored in your shell history,
+   as explained in the warning [here](./get_started.md#setting-the-encryption-key).
+
+4. Clone the Disco repository, or copy the [`docker-compose.yml` file](https://github.com/hackfixme/disco/blob/main/docker-compose.yml) locally, and run:
+   ```sh
+   podman-compose up
+   ```
+
+   This will create the pod needed for subsequent commands. This only needs to be run once.
+
+5. Run Disco commands as usual, e.g.:
+   ```sh
+   podman-compose run --rm disco set key value
+   ```
+
+   You can set this as an alias for convenience:
+   ```sh
+   alias discon='podman-compose run --rm disco'
+   ```
+
+   Note that if you want to run the web server, you might want to pass the `--service-ports` option to `podman-compose`, in order to expose the server ports to the host network. So the full command should be:
+   ```sh
+   podman-compose run --rm --service-ports disco serve
+   ```

docs/get_started.md

@@ -48,7 +48,7 @@ Most Disco commands require the encryption key to read and write data. You can p
 > Be aware that on Linux the CLI arguments and process environment can be read by any
 > other process run by the same user via the `/proc` filesystem, which means another
 > process could read the Disco encryption key. If this is a concern for your use
-> case, consider [running Disco inside a container instead](https://hub.docker.com/r/hackfixme/disco),
+> case, consider [running Disco inside a container instead](./container.md),
 > or using another isolation mechanism (e.g. a virtual machine).
 >
 > Also, be careful with your shell history. Depending on your shell configuration,