From 116dc9592d412c30f6de15f5ebb85e862d93e3d2 Mon Sep 17 00:00:00 2001 From: ClaydeCode Date: Tue, 3 Nov 2026 14:58:09 +0000 Subject: [PATCH 1/2] developer_docs: document the secret() template helper Since shard_core 0.41.2 (FreeshardBase/freeshard#173) compose templates can call secret('') for a generated, app-scoped value. The page had no mention of it. It gets its own section under Variables, not an include table: it is a function with a free-form name argument, so there is no fixed set of rows to list. The complex example now password-protects its redis to show one name shared by two containers. Co-Authored-By: Claude Opus 5.5 --- .../developer_docs/docker_compose_template.md | 58 +++++++++++++++++-- 1 file changed, 52 insertions(+), 6 deletions(-) diff --git a/docs/developer_docs/docker_compose_template.md b/docs/developer_docs/docker_compose_template.md index 7a3b214..d6f0e29 100644 --- a/docs/developer_docs/docker_compose_template.md +++ b/docs/developer_docs/docker_compose_template.md @@ -4,7 +4,8 @@ title: The Docker-Compose Template When starting an app, the shard simply brings up a docker-compose file just like you would with `docker-compose up`. This file is generated during installation of the app from a `docker-compose.yml.template` that you have to provide. -The template is a normal docker-compose file with some special variables that the shard will replace with the correct values. +The template is a normal docker-compose file with some special variables that the shard will replace with the correct values, +and a `secret()` helper that fills in generated passwords. --- @@ -47,7 +48,7 @@ services: ## Complex Example Now let's look at a more complex example. -Here we have an app that depends on a redis database and has some environment variables that need to be set. +Here we have an app that depends on a password-protected redis database and has some environment variables that need to be set. We also want to access the shared part of the filesystem where apps can store data that is shared between them. ```yaml @@ -72,12 +73,14 @@ services: - REDIS_HOST=my-app-redis # (3)! - BASE_URL=https://my-app.{{ portal.domain }} # (4)! - TITLE=My app on {{ portal.short_id }} # (5)! + - REDIS_PASSWORD={{ secret('redis_password') }} # (6)! - my-app-redis: # (6)! + my-app-redis: # (7)! image: redis:6.2 container_name: my-app-redis + command: redis-server --requirepass {{ secret('redis_password') }} # (8)! volumes: - - "{{ fs.app_data }}/redis_data:/redis_data" # (7)! + - "{{ fs.app_data }}/redis_data:/redis_data" # (9)! networks: - portal ``` @@ -90,9 +93,14 @@ services: An app's domain name is always `.`. 5. We can also use the `portal.short_id` variable to get the shard's six-digit unique identifier. This is useful for example to set the title of the app. -6. This app need a redis database, so we add a redis container to the docker-compose file. +6. The app needs the redis password. `secret('redis_password')` generates a random password + the first time the template is rendered and returns the same value on every later render. + Read more in the section on [secrets](#secrets). +7. This app need a redis database, so we add a redis container to the docker-compose file. The naming convention for additional containers is `my-app-`, where `` is the name of the container. -7. We mount a directory for redis to store its data. Note that we use `fs.app_data` just as for the app itself +8. Redis is started with the same secret as its password. + Because both containers reference the name `redis_password`, they get the same value. +9. We mount a directory for redis to store its data. Note that we use `fs.app_data` just as for the app itself so the redis data will be stored in the same directory as the app data. ## Variables @@ -107,6 +115,44 @@ Here is a complete list of all variables that you can use in your template. {!developer_docs/includes/template_vars_fs.md!} +### Secrets + +Some values must not be static or predictable, for example the password of a database that only your app talks to. +For these, call the `secret()` helper with a name of your choice: + +```yaml +environment: +- POSTGRES_PASSWORD={{ secret('db_password') }} +``` + +There is nothing to declare beforehand: the name exists as soon as the template references it. +The shard handles it like this: + +- The first time a template that references a name is rendered, the shard generates a random value + of 32 letters and digits (`[A-Za-z0-9]`) and stores it. +- From then on, `secret()` returns that same value for that name. + It stays the same across app updates, restarts and reinstalls, and it is never rotated. +- Every reference to the same name returns the same value, within one template and across containers. + Different names get different values. +- Secrets are scoped to your app. + Another app that uses the same name gets its own, different value. +- Secrets are kept when the app is uninstalled, just like its data, + so reinstalling the app reuses them. + They are also part of the shard's backup. + +Because the value only contains letters and digits, it can go anywhere in the template without quoting or escaping, +for example inside a connection URL like `postgres://my-app:{{ secret('db_password') }}@my-app-postgres/my-app`. + +Note that a secret is tied to its name. +If a later version of your app references `secret('db_pass')` where it used to say `secret('db_password')`, +it gets a new value, and a database that was set up with the old one will no longer accept it. + +Secrets are stored unencrypted on the shard. +Scoping keeps apps from colliding on names, it is not a security boundary between apps: +a malicious app template could read other apps' secrets. + +The `secret()` helper is available from freeshard version 0.41.2. + ## Limitations Technically, you can use any docker-compose feature in your template. From d6e9cb318b04bf4d2be8fb05a010c571867ce1aa Mon Sep 17 00:00:00 2001 From: ClaydeCode Date: Tue, 3 Nov 2026 15:15:01 +0000 Subject: [PATCH 2/2] developer_docs: drop secrets security caveat, regenerate digest The note that app-scoping is not a boundary against a hostile template is a shard_core design gap, not something app developers act on; it is tracked as an issue in FreeshardBase/freeshard instead. digest.md gets the secret() helper and the password-protected redis example. No other docs changed since its last generation, so this brings it fully current. Co-Authored-By: Claude Opus 5.5 --- digest.md | 27 ++++++++++++++++--- .../developer_docs/docker_compose_template.md | 4 --- 2 files changed, 24 insertions(+), 7 deletions(-) diff --git a/digest.md b/digest.md index 483d353..8a0fe58 100644 --- a/digest.md +++ b/digest.md @@ -4,7 +4,7 @@ > coding agents (e.g. the app-repository `add-app` skill) that build and submit > Freeshard apps. Authoritative copy of `docs.freeshard.net/developer_docs`. > -> Generated: 2026-06-29 +> Generated: 2026-11-03 > Source: github.com/FreeshardBase/documentation > Regenerate with the repo-local `generate-digest` skill (`.claude/skills/generate-digest/`). @@ -47,7 +47,8 @@ forwarded to the container/port named in `app_meta.json` `entrypoints`. ## `docker-compose.yml.template` A normal docker-compose file plus Jinja-style `{{ ... }}` template variables that -the shard substitutes at install time. The shard runs it like `docker-compose up`. +the shard substitutes at install time, and a `secret('')` helper for +generated passwords. The shard runs it like `docker-compose up`. Minimal example: @@ -68,7 +69,7 @@ services: - portal # must join the portal network ``` -Complex example (dependency container + env vars + shared dir): +Complex example (password-protected dependency container + env vars + shared dir): ```yaml version: '3.5' @@ -92,10 +93,12 @@ services: - REDIS_HOST=my-app-redis - BASE_URL=https://my-app.{{ portal.domain }} # app domain = . - TITLE=My app on {{ portal.short_id }} + - REDIS_PASSWORD={{ secret('redis_password') }} # generated once, then reused my-app-redis: # extra containers named my-app- image: redis:6.2 container_name: my-app-redis + command: redis-server --requirepass {{ secret('redis_password') }} # same name = same value volumes: - "{{ fs.app_data }}/redis_data:/redis_data" # use fs.app_data, same dir tree as the app networks: @@ -122,6 +125,24 @@ Filesystem variables: | `fs.shared` | Absolute path to the shared data directory | `/home/user/.freeshard/user_data/shared` | | `fs.installation_dir` | Absolute path to your installation files | `/home/user/.freeshard/core/installed_apps/my-app` | +Secrets (`{{ secret('') }}`, from freeshard 0.41.2): + +- For values that must not be static or predictable, e.g. an internal DB password: + `- POSTGRES_PASSWORD={{ secret('db_password') }}`. +- Name is arbitrary; referencing it declares it. No `app_meta.json` entry. +- First render that references a name generates 32 chars of `[A-Za-z0-9]` and + stores it. Afterwards the same value is returned for that name: across app + updates, restarts and reinstalls. Never rotated. +- Same name → same value everywhere in the template (all containers). Different + names → different values. Scoped per app: another app's `secret('db_password')` + is a different value. +- Kept on uninstall (like app data), so a reinstall reuses it. Included in the + shard backup. +- Alphanumeric only, so safe unquoted in env vars, commands and URLs, e.g. + `postgres://my-app:{{ secret('db_password') }}@my-app-postgres/my-app`. +- Renaming a secret in a later app version yields a new value; a database + initialized with the old one will reject it. Keep names stable. + ### Limitations (enforced on app-store submission) - **Filesystem**: mount only the directories exposed via `fs.*` variables. Have a diff --git a/docs/developer_docs/docker_compose_template.md b/docs/developer_docs/docker_compose_template.md index d6f0e29..1a23413 100644 --- a/docs/developer_docs/docker_compose_template.md +++ b/docs/developer_docs/docker_compose_template.md @@ -147,10 +147,6 @@ Note that a secret is tied to its name. If a later version of your app references `secret('db_pass')` where it used to say `secret('db_password')`, it gets a new value, and a database that was set up with the old one will no longer accept it. -Secrets are stored unencrypted on the shard. -Scoping keeps apps from colliding on names, it is not a security boundary between apps: -a malicious app template could read other apps' secrets. - The `secret()` helper is available from freeshard version 0.41.2. ## Limitations