From 4cd257dedc4a7a061af06c9497db7a16ae982b84 Mon Sep 17 00:00:00 2001
From: ivanlele <ivanlele402@gmail.com>
Date: Fri, 6 Nov 2026 18:07:03 +0200
Subject: [PATCH] update documentation to include Docker usage instructions for
 running the service

---
 README.md         | 79 +++++++++++++++++++++++++++++++++++++++++++++++
 service/README.md |  4 +++
 2 files changed, 83 insertions(+)

diff --git a/README.md b/README.md
index 7b0c9f8..e81b232 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,85 @@ The primary target is **Bitcoin**, using `bitcoin-policy-v1`, with confidential
 
 See [core/README.md](core/README.md) for the unchained model, Taproot tree structure and policy co-signing flow.
 
+## Run your own SU service
+
+The [published image](https://github.com/BlockstreamResearch/simplicity-unchained/pkgs/container/simplicity-unchained)
+runs the policy co-signer, not a Bitcoin or Liquid full node. You need Docker
+Engine (or Docker Desktop) and `curl`; no Rust build or repository checkout is
+required. This release targets `linux/amd64`; ARM hosts need amd64 emulation.
+Use testnet keys and coins only.
+
+### 1. Provision the signing key
+
+Run once in a POSIX shell. The configuration is stored in a Docker volume with a
+fresh random key, readable only by the container's service user (UID 1000).
+The command refuses to overwrite an existing configuration.
+For an existing funded service, reuse its private configuration instead of
+generating a replacement key.
+
+```sh
+IMAGE=ghcr.io/blockstreamresearch/simplicity-unchained:v0.1.0-alpha.0
+docker pull --platform linux/amd64 "$IMAGE"
+docker volume create su-config
+
+docker run --rm --platform linux/amd64 --user 0:0 \
+  --entrypoint /bin/sh \
+  --mount type=volume,src=su-config,dst=/config \
+  "$IMAGE" -euc '
+    set -C
+    umask 077
+    if [ -e /config/config.toml ]; then
+      echo "Configuration exists; reuse it." >&2
+      exit 1
+    fi
+    key=$(od -vAn -N32 -tx1 /dev/urandom | tr -d " \n")
+    [ "${#key}" -eq 64 ]
+    printf "%s\n" \
+      "[service]" \
+      "port = 30431" \
+      "private_key = \"$key\"" \
+      "bitcoin_network = \"testnet4\"" \
+      "liquid_network = \"liquidtestnet\"" \
+      > /config/config.toml
+    chown 1000:1000 /config/config.toml
+  '
+```
+
+### 2. Start the service
+
+In the same shell:
+
+```sh
+docker run -d --name simplicity-unchained \
+  --platform linux/amd64 \
+  --restart unless-stopped \
+  --publish 127.0.0.1:30431:30431 \
+  --mount type=volume,src=su-config,dst=/app/config,readonly \
+  "$IMAGE" start --config /app/config/config.toml
+```
+
+The service runs as UID 1000 and reads its configuration from a read-only mount.
+The API is available only on the Docker host. For remote clients, put it behind
+an HTTPS reverse proxy; the service itself does not provide TLS.
+
+### 3. Check the API
+
+```sh
+curl -fsS http://127.0.0.1:30431/simplicity-unchained/version
+curl -fsS http://127.0.0.1:30431/simplicity-unchained/policy/bitcoin/capabilities
+curl -fsS http://127.0.0.1:30431/simplicity-unchained/policy/liquid/capabilities
+```
+
+The version response is `{"version":"0.1.0"}`. Capabilities report each profile,
+network and `base_public_key_hex`; pin that public key in clients before funding.
+Use `docker logs simplicity-unchained` to diagnose startup failures.
+
+Stop with `docker stop simplicity-unchained` and start again with
+`docker start simplicity-unchained`. Keep a secure backup of the private
+configuration in `su-config`; deleting the volume or changing its key changes
+the signer identity and can make cooperative spending impossible.
+See the [service documentation](service/README.md) for configuration and API schemas.
+
 ## Project Structure
 
 - [`core`](core/README.md): Executes Simplicity policies and provides cryptographic, Taproot and transaction-environment utilities.
diff --git a/service/README.md b/service/README.md
index 3559b0d..8eb235e 100644
--- a/service/README.md
+++ b/service/README.md
@@ -54,6 +54,10 @@ Liquid Testnet. Requests must match the configured network for their profile.
 
 ### Docker
 
+To run the prebuilt release image without compiling, follow
+[Run your own SU service](../README.md#run-your-own-su-service).
+The instructions below build an image from the local checkout.
+
 The image contains the service binary but no active configuration or signing key.
 Provision a configuration outside the build context using the example above,
 then mount it read-only: