From 38c6647539b447087943114ad49ca0fa9a171841 Mon Sep 17 00:00:00 2001
From: Martin Tomazic <martin.tomazic97@gmail.com>
Date: Wed, 15 Jul 2026 11:53:48 +0200
Subject: [PATCH] docs/rofl/features: Document public variables

---
 docs/rofl/features/public_var.md | 63 ++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 docs/rofl/features/public_var.md

diff --git a/docs/rofl/features/public_var.md b/docs/rofl/features/public_var.md
new file mode 100644
index 0000000000..618e976d05
--- /dev/null
+++ b/docs/rofl/features/public_var.md
@@ -0,0 +1,63 @@
+# Public Variables
+
+Sometimes containers need access to non-sensitive configuration, for example
+API endpoints or public feature flags. This data can be passed to containers
+running in ROFL via _public variables_. Public variables are arbitrary key-value
+pairs that are exposed to containers as environment variables. Use them
+for values that can (or should be) transparent to anyone.
+
+Public variables can be easily managed via the Oasis CLI, for example to create
+a public variable called `API_URL` you can use:
+
+```sh
+echo -n "https://api.example.com" | oasis rofl public-var set API_URL -
+```
+
+:::info Detailed CLI Reference
+
+For comprehensive documentation on public variable management commands including
+importing from `.env` files, removing public variables, and other advanced
+features, consult the [Oasis CLI] documentation.
+
+:::
+
+Note that this only updates the local app manifest file, but the public variable
+is not propagated to the app just yet. This allows you to easily configure as
+many public variables as you want without the need to constantly update the
+on-chain app configuration.
+
+:::info
+
+Public variables are stored unencrypted in the local app manifest and in
+on-chain app metadata. This means that they can be read by anyone who can access
+the manifest or inspect the on-chain app configuration.
+
+For confidential values, use [Secrets] instead.
+
+:::
+
+Updating the on-chain configuration can be performed via the usual `update`
+command as follows:
+
+```sh
+oasis rofl update
+```
+
+Inside containers public variables can be passed via environment variables.
+
+## Environment Variables
+
+Each public variable is automatically exposed in the Compose environment and can
+be trivially used in the Compose file.
+
+```yaml
+services:
+  test:
+    image: docker.io/library/alpine:3.21.2@sha256:f3240395711384fc3c07daa46cbc8d73aa5ba25ad1deb97424992760f8cb2b94
+    command: echo "API URL is $API_URL"
+    environment:
+      - API_URL=${API_URL}
+```
+
+[Secrets]: ./secrets.md
+[Oasis CLI]: https://github.com/oasisprotocol/cli/blob/master/docs/rofl.md#public-var