From 2d92a86ead04270a73f8a9685db0e33311f78523 Mon Sep 17 00:00:00 2001 From: ClaydeCode Date: Tue, 3 Nov 2026 18:16:14 +0000 Subject: [PATCH 1/2] developer_docs: secret() is available from 0.41.3 0.41.2 contains the code but its image was never published (a flaky CI test blocked the build; fixed in FreeshardBase/freeshard#263), so 0.41.3 is the first version a shard can run. Co-Authored-By: Claude Opus 5.5 --- digest.md | 2 +- docs/developer_docs/docker_compose_template.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/digest.md b/digest.md index 8a0fe58..6f6f11b 100644 --- a/digest.md +++ b/digest.md @@ -125,7 +125,7 @@ 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): +Secrets (`{{ secret('') }}`, from freeshard 0.41.3): - For values that must not be static or predictable, e.g. an internal DB password: `- POSTGRES_PASSWORD={{ secret('db_password') }}`. diff --git a/docs/developer_docs/docker_compose_template.md b/docs/developer_docs/docker_compose_template.md index 1a23413..9d5ab9e 100644 --- a/docs/developer_docs/docker_compose_template.md +++ b/docs/developer_docs/docker_compose_template.md @@ -147,7 +147,7 @@ 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. -The `secret()` helper is available from freeshard version 0.41.2. +The `secret()` helper is available from freeshard version 0.41.3. ## Limitations From 4b16f87d6949dd4918e6135d55309eec71d169a5 Mon Sep 17 00:00:00 2001 From: ClaydeCode Date: Tue, 3 Nov 2026 18:21:43 +0000 Subject: [PATCH 2/2] developer_docs: document minimum_freeshard_version Apps can declare the freeshard version they need since shard_core 0.41.3 (FreeshardBase/freeshard#246). The Secrets section now points at it, since secret() is the first template feature that needs it. Store-side hiding of too-new apps is marked as upcoming: the Sundial gate (sundial#34) is merged but not in any release, and web-terminal does not implement it. Co-Authored-By: Claude Opus 5.5 --- digest.md | 12 ++++++- docs/developer_docs/app_meta_json.md | 32 +++++++++++++++++++ .../developer_docs/docker_compose_template.md | 8 +++-- 3 files changed, 49 insertions(+), 3 deletions(-) diff --git a/digest.md b/digest.md index 6f6f11b..4e45f69 100644 --- a/digest.md +++ b/digest.md @@ -125,7 +125,8 @@ 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.3): +Secrets (`{{ secret('') }}`, needs freeshard 0.41.3, so declare +`"minimum_freeshard_version": ">=0.41.3"` in `app_meta.json`): - For values that must not be static or predictable, e.g. an internal DB password: `- POSTGRES_PASSWORD={{ secret('db_password') }}`. @@ -183,6 +184,7 @@ Tells the shard how to run and present the app. Current format version `v` = "idle_time_for_shutdown": 3600 }, "minimum_portal_size": "s", + "minimum_freeshard_version": ">=0.41.3", "store_info": { "description_short": "This is a very good app.", "description_long": [ @@ -211,6 +213,14 @@ Field reference: - `paths` — access control by path prefix (see below). Must include `""` default. - `lifecycle` — start/stop behavior (see Lifecycle). - `minimum_portal_size` — min shard size required (e.g. `"s"`); omit = all sizes. +- `minimum_freeshard_version` — *(optional)* PEP 440 specifier the shard version must + satisfy, e.g. `">=0.41.3"`. Needs an operator: `"0.41.3"` is invalid and makes the + app uninstallable. Omit = all versions. Set it whenever the app uses a feature that + only newer shards have (e.g. `secret()` → `">=0.41.3"`). Effect on a shard that + does not satisfy it: installed app is not started ("Shard too old" page) until the + shard is updated. Shards older than 0.41.3 do not know the field and ignore it. + (status: upcoming) Hiding not-installed apps in the app store from shards that do + not satisfy it; today the store shows every app on every shard. - `store_info` — app-store display metadata (see Submitting). JSON schema (add to IDE for autocompletion/validation): diff --git a/docs/developer_docs/app_meta_json.md b/docs/developer_docs/app_meta_json.md index f4a1e39..9827938 100644 --- a/docs/developer_docs/app_meta_json.md +++ b/docs/developer_docs/app_meta_json.md @@ -41,6 +41,7 @@ Click on the plus buttons for a description of each field. "idle_time_for_shutdown": 3600 }, "minimum_portal_size": "s", // (8)! + "minimum_freeshard_version": ">=0.41.3", // (13)! "store_info": { // (9)! "description_short": "This is a very good app.", "description_long": [ @@ -84,6 +85,37 @@ Click on the plus buttons for a description of each field. It only works with GitHub repositories which use the "Release" feature. 12. (Optional) The URL of the homepage of your app. This is where users can find more information about your app. +13. (Optional) The freeshard version your app needs. + Read more in the section on [the minimum freeshard version](#minimum-freeshard-version). + +## Minimum Freeshard Version + +Some template features and platform behavior only exist from a certain freeshard version on, +for example the [`secret()` helper](docker_compose_template.md#secrets), which needs 0.41.3. +If your app depends on such a feature, declare it with `minimum_freeshard_version`: + +```json +"minimum_freeshard_version": ">=0.41.3" +``` + +The value is a [PEP 440 version specifier](https://packaging.python.org/en/latest/specifications/version-specifiers/){target=blank}, +so it needs an operator: write `">=0.41.3"`, not `"0.41.3"`. +A value that is not a valid specifier makes the `app_meta.json` invalid, and the app cannot be installed. +If you do not specify this, your app is available on all freeshard versions. + +The shard compares the requirement against the freeshard version it is running. +An installed app on a shard that does not satisfy the requirement is not started. +Instead of the app, the owner sees a "Shard too old" page naming the required version. +As soon as the shard is updated to a matching version, the app starts normally. + +Note that this check only exists from freeshard 0.41.3 on. +Older shards do not know the field and ignore it. + +!!! warning "Upcoming Feature" + Hiding apps in the app store is not yet implemented. + Once it is, the app store will not show an app to owners whose shard does not satisfy its requirement, + so they cannot install it in the first place. + Until then, the app store shows every app on every shard. ## Schema diff --git a/docs/developer_docs/docker_compose_template.md b/docs/developer_docs/docker_compose_template.md index 9d5ab9e..20e50b1 100644 --- a/docs/developer_docs/docker_compose_template.md +++ b/docs/developer_docs/docker_compose_template.md @@ -117,6 +117,12 @@ Here is a complete list of all variables that you can use in your template. ### Secrets +!!! info "Requires freeshard 0.41.3" + `secret()` is available from freeshard version 0.41.3. + On older shards, a template that uses it cannot be rendered. + Declare `"minimum_freeshard_version": ">=0.41.3"` in your `app_meta.json` to state this requirement. + Read more in the section on [the minimum freeshard version](app_meta_json.md#minimum-freeshard-version). + 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: @@ -147,8 +153,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. -The `secret()` helper is available from freeshard version 0.41.3. - ## Limitations Technically, you can use any docker-compose feature in your template.