new borg2 demo screencast, recorded in a container, fixes #6303

docs/misc/asciinema/Containerfile

@@ -0,0 +1,48 @@
+# Environment for recording the borg2 demo screencast, see README.rst.
+#
+# Do NOT run the demo scripts outside of this container (or a VM): they install
+# borg, create users, mount filesystems and write to /media.
+#
+# Build and run it via ./record.sh - it exports the borg sources from git and
+# puts them into the build context as borg-src.tar.
+
+FROM debian:trixie-slim
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      expect asciinema \
+      python3 python3-dev python3-venv \
+      build-essential pkg-config \
+      libssl-dev libacl1-dev liblz4-dev libzstd-dev libxxhash-dev \
+      libfuse3-dev fuse3 \
+      ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# We build borg from the sources of this checkout (and not from a release
+# binary), so the screencast always shows the CLI of the borg version we are
+# about to release.
+COPY borg-src.tar /tmp/
+# the exported sources have no .git, so setuptools-scm needs to be told the version
+ARG BORG_VERSION
+ENV SETUPTOOLS_SCM_PRETEND_VERSION_FOR_BORGBACKUP=${BORG_VERSION}
+RUN tar -xf /tmp/borg-src.tar -C /tmp \
+    && python3 -m venv /opt/borg \
+    && /opt/borg/bin/pip install --no-cache-dir /tmp/borg pyfuse3 \
+    && ln -s /opt/borg/bin/borg /usr/local/bin/borg \
+    && rm -rf /tmp/borg
+
+# The demo is recorded as a normal user, so the archives contain sane paths.
+RUN useradd --create-home --shell /bin/sh user \
+    && mkdir -p /media/backup \
+    && chown user:user /media/backup
+
+COPY demo-data.py demo.tcl record.exp entrypoint.sh /demo/
+
+# Generating the demo data takes a while, so we do it at build time and only
+# copy it into place when recording (which makes re-recording quick).
+RUN python3 /demo/demo-data.py /opt/demo-data \
+    && tar -xf /tmp/borg-src.tar -C /opt/demo-data --transform 's,^borg,projects/borg,' \
+    && rm -f /tmp/borg-src.tar
+
+ENTRYPOINT ["/demo/entrypoint.sh"]

docs/misc/asciinema/README.rst

@@ -0,0 +1,59 @@
+The borg2 demo screencast
+=========================
+
+The screencast linked from our README and website is not recorded by hand:
+``demo.tcl`` is "typed" into a shell by expect_, while asciinema_ records the
+result. So, when borg's output changes, we just record it again.
+
+Do **not** run these scripts directly on your machine: they create users,
+mount filesystems and write to ``/media``. They are meant to run inside the
+container defined by ``Containerfile``.
+
+Recording
+---------
+
+::
+
+    ./record.sh [output directory]     # uses podman, set ENGINE=docker for docker
+
+This exports the borg sources of the git tag given by ``BORG_VERSION`` at the
+top of ``record.sh``, builds borg from them in a container, generates the demo
+data and records the screencast to ``borg2-demo.cast``. So, for a new release,
+set ``BORG_VERSION`` to its tag (after tagging it) and record again.
+
+While working on the demo itself, you can also record from your work tree::
+
+    BORG_VERSION=HEAD ./record.sh
+
+Then have a look at it and upload it::
+
+    asciinema play borg2-demo.cast
+    asciinema upload borg2-demo.cast
+
+Afterwards, update the links in ``README.rst`` (in the repository root) and on
+borgbackup.org to point to the new screencast.
+
+Editing the demo
+----------------
+
+``demo.tcl`` contains the commands and comments that get typed, in the order
+they appear in the screencast. Keep the typed lines below ~95 characters, the
+recording uses a 100x30 terminal (see ``record.exp``).
+
+The lines we type are colored by ``type_line`` (comments, commands, options),
+see the ``color`` array at the top of ``demo.tcl`` if you want other colors.
+The output of the commands is not touched, it looks like in your terminal.
+
+``demo-data.py`` generates the data that gets backed up: compressible, but not
+trivially repetitive, so that both compression and deduplication show
+realistic numbers (see #6303).
+
+Known quirks
+------------
+
+``borg extract`` runs with ``--noxattrs``: when recording with rootless podman
+on a SELinux host, restoring the ``security.selinux`` xattrs of the demo data
+is not permitted, and the warnings about it would show up in the screencast.
+
+.. _expect: https://core.tcl-lang.org/expect/index
+.. _asciinema: https://asciinema.org/