From 1e4bfe31e5bcc1d18c320f71cf35120beec124b7 Mon Sep 17 00:00:00 2001 From: ClaydeCode Date: Tue, 3 Nov 2026 21:06:30 +0000 Subject: [PATCH 1/2] developer_docs: update app_meta.json format to version 1.3 shard_core 0.40.0 made 1.3 the current format. It replaced the single lifecycle.idle_time_for_shutdown with idle_for_pause, idle_for_stop and skip_pause, and the docs still described the old field and its 60s stop, which no longer matches what shards do. The lifecycle page now covers pausing, the memory-pressure and low-disk behaviour, and the field rules from the Lifecycle model. The published JSON schema is still the 1.2 one, so the page says so. Co-Authored-By: Claude Opus 5.5 --- digest.md | 44 ++++++++++++++++++++-------- docs/developer_docs/app_meta_json.md | 22 ++++++++++---- docs/developer_docs/lifecycle.md | 43 +++++++++++++++++++++------ 3 files changed, 81 insertions(+), 28 deletions(-) diff --git a/digest.md b/digest.md index 4e45f69..6c95703 100644 --- a/digest.md +++ b/digest.md @@ -156,11 +156,11 @@ Secrets (`{{ secret('') }}`, needs freeshard 0.41.3, so declare ## `app_meta.json` Tells the shard how to run and present the app. Current format version `v` = -`"1.2"`. Full example: +`"1.3"`. Full example: ```json { - "v": "1.2", + "v": "1.3", "app_version": "0.1.1", "name": "my-app", "pretty_name": "My App", @@ -181,7 +181,8 @@ Tells the shard how to run and present the app. Current format version `v` = }, "lifecycle": { "always_on": false, - "idle_time_for_shutdown": 3600 + "idle_for_pause": 300, + "idle_for_stop": 3600 }, "minimum_portal_size": "s", "minimum_freeshard_version": ">=0.41.3", @@ -199,7 +200,7 @@ Tells the shard how to run and present the app. Current format version `v` = Field reference: -- `v` — `app_meta.json` format version, should be `"1.2"`. +- `v` — `app_meta.json` format version, should be `"1.3"`. - `app_version` — your app's version; used for update detection. Match your own scheme. - `name` — URL name, **unique across the app store**, lowercase letters/numbers/dashes only. - `pretty_name` — display name (app store + home screen); may have uppercase/spaces. @@ -211,7 +212,7 @@ Field reference: - `container_port` — port the app listens on inside the container. - `entrypoint_port` — `http` (→443) or `mqtt` (→8883). - `paths` — access control by path prefix (see below). Must include `""` default. -- `lifecycle` — start/stop behavior (see Lifecycle). +- `lifecycle` — pause/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 @@ -225,8 +226,11 @@ Field reference: JSON schema (add to IDE for autocompletion/validation): `https://storageaccountportab0da.blob.core.windows.net/json-schema/0-30-2/schema_app_meta_1.2.json` +(still describes 1.2: no 1.3 lifecycle fields, no `minimum_freeshard_version`; no 1.3 schema is published) -Version history: **1.2** added `homepage` + `upstream_repo`; **1.1** added +Version history: **1.3** replaced `lifecycle.idle_time_for_shutdown` with +`idle_for_pause`/`idle_for_stop`/`skip_pause` (old field is read as `idle_for_pause`; +shards older than 0.40.0 cannot read 1.3 files); **1.2** added `homepage` + `upstream_repo`; **1.1** added `pretty_name`. New versions aim to be backwards compatible (older files are translated to current). @@ -306,20 +310,34 @@ The shard starts/stops apps on demand to conserve resources. - **Start**: triggered by incoming HTTP traffic; the shard core starts the app and shows a self-refreshing splash screen meanwhile (provided by the shard, no work for you). -- **Stop**: after idle time with no HTTP traffic, `docker-compose stop` (containers - stopped, not removed). +- **Pause**: after `idle_for_pause` with no HTTP traffic, containers are frozen and + their memory moved to swap; resumes quickly on the next request. +- **Stop**: after `idle_for_stop`, `docker-compose stop` (containers stopped, not + removed); started again on the next request. +- Low memory: shard pauses/stops least-recently-used apps early, one per cycle. + Low disk: every app is stopped, `always_on` included. -Configure via `lifecycle` in `app_meta.json`: +Configure via `lifecycle` in `app_meta.json` (all optional, seconds): ```json "lifecycle": { - "always_on": false, - "idle_time_for_shutdown": 60 + "idle_for_pause": 300, + "idle_for_stop": 3600 } ``` -- `always_on: true` → never stopped; then `idle_time_for_shutdown` is **forbidden**. -- `idle_time_for_shutdown` (seconds, default `60`) → requires `always_on` unset/false. +| field | meaning | default | +|------------------|-------------------------------------------------|----------------| +| `idle_for_pause` | idle time until pause | `60` | +| `idle_for_stop` | idle time until stop | `10800` (3h) | +| `skip_pause` | never pause, only stop after `idle_for_stop` | `false` | +| `always_on` | never pause or stop | `false` | + +- Both idle times ≥ `5`; `idle_for_pause` < `idle_for_stop`. +- `skip_pause` (for apps that don't tolerate freezing) forbids `idle_for_pause`. +- `always_on: true` forbids every other lifecycle field. +- Pausing can be switched off per shard; then apps are only stopped after `idle_for_stop`. +- Format ≤1.2 used a single `idle_time_for_shutdown`; still read, as `idle_for_pause`. ## Shard internal services diff --git a/docs/developer_docs/app_meta_json.md b/docs/developer_docs/app_meta_json.md index 9827938..dc5df64 100644 --- a/docs/developer_docs/app_meta_json.md +++ b/docs/developer_docs/app_meta_json.md @@ -17,7 +17,7 @@ Click on the plus buttons for a description of each field. ```json { - "v": "1.2", // (1)! + "v": "1.3", // (1)! "app_version": "0.1.1", // (2)! "name": "my-app", // (3)! "pretty_name": "My App", // (10)! @@ -38,7 +38,8 @@ Click on the plus buttons for a description of each field. }, "lifecycle": { // (7)! "always_on": false, - "idle_time_for_shutdown": 3600 + "idle_for_pause": 300, + "idle_for_stop": 3600 }, "minimum_portal_size": "s", // (8)! "minimum_freeshard_version": ">=0.41.3", // (13)! @@ -54,7 +55,7 @@ Click on the plus buttons for a description of each field. } ``` -1. The version of the `app_meta.json` format. Should be "1.2". +1. The version of the `app_meta.json` format. Should be "1.3". 2. The version of your app. This is used to determine if an update is available. It is recommended to match with your own versioning scheme. 3. The name of your app as seen in the URL. @@ -71,7 +72,7 @@ Click on the plus buttons for a description of each field. It is a mapping of path prefixes to access control settings. The empty string `""` is the default and will be used for all paths that are not explicitly configured. Read more about access control [here](routing_and_ac.md). -7. Most freeshard apps do not run continuously but are started on demand and stopped after an idle period. +7. Most freeshard apps do not run continuously but are started on demand, and paused and stopped after an idle period. This is where you can configure this behavior. Read more about it [here](lifecycle.md). 8. This is the minimum size of a managed shard that is required to run your app and should be set according to your app's CPU and memory requirements. @@ -119,8 +120,10 @@ Older shards do not know the field and ignore it. ## Schema -To help you write your `app_meta.json` file,we publish a JSON schema that describes the format +To help you write your `app_meta.json` file, we publish a JSON schema that describes the format [here](https://storageaccountportab0da.blob.core.windows.net/json-schema/0-30-2/schema_app_meta_1.2.json). +Note that this schema still describes version 1.2, so it does not know the version 1.3 lifecycle fields +or `minimum_freeshard_version`. Add it to your IDE to get auto-completion and validation. Here is a guide for [Visual Studio Code](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings){target=blank} and one for [PyCharm](https://www.jetbrains.com/help/pycharm/json.html#ws_json_schema_add_custom){target=blank}. @@ -130,7 +133,7 @@ and one for [PyCharm](https://www.jetbrains.com/help/pycharm/json.html#ws_json_s Since the format of the `app_meta.json` evolves over time, it is important to include the version of the format in which it is written. It is contained in the `v` attribute. -The current version is `1.2`. +The current version is `1.3`. When new versions are released, we will attempt to make them backwards compatible. That means that freeshard still can process the previous version @@ -138,6 +141,13 @@ and translate it to the current one. ### Past Updates +#### Version 1.3 + +* Replaced `idle_time_for_shutdown` in `lifecycle` with `idle_for_pause`, `idle_for_stop` and `skip_pause`. + See [The App Lifecycle](lifecycle.md#configuration). + When freeshard translates an older file, `idle_time_for_shutdown` becomes `idle_for_pause`. +* Shards older than freeshard 0.40.0 cannot read version 1.3 files. + #### Version 1.2 * Added the `homepage` and `upstream_repo` fields. diff --git a/docs/developer_docs/lifecycle.md b/docs/developer_docs/lifecycle.md index db04f76..ff13eb9 100644 --- a/docs/developer_docs/lifecycle.md +++ b/docs/developer_docs/lifecycle.md @@ -27,10 +27,19 @@ During the time it takes for the app to start, a splash screen is displayed and This splash screen is provided by the shard core and as an app developer, you do not have to do anything to make it work. -## Stop +## Pause and Stop -After some idle time - i.e. a time period without http traffic to an app - the shard core stops the app. +After some idle time - i.e. a time period without http traffic to an app - the shard core pauses the app. +Its containers are frozen and their memory is moved to swap, so a paused app uses almost no memory +but resumes quickly on the next request. + +After a longer idle time, a paused app is stopped. The container is only stopped, but not removed. Essentially, the `docker-compose stop` command is issued. +A stopped app is started again on the next request, as described above. + +When the shard runs low on memory, it pauses or stops the least recently used apps before their idle time is reached, +one app at a time until enough memory is free. +When the shard runs low on disk space, it stops all apps. ## Configuration @@ -39,14 +48,30 @@ For example: ```json "lifecycle": { - "always_on": false, - "idle_time_for_shutdown": 60 + "idle_for_pause": 300, + "idle_for_stop": 3600 }, ``` -You may set `always_on` to `true` causing your app to never be stopped. -In this case, providing an `idle_time_for_shutdown` is forbidden. +All fields are optional. Times are given in seconds. + +| field | description | default | +|------------------|--------------------------------------------------------------------|-----------------| +| `idle_for_pause` | Idle time after which the app is paused | `60` | +| `idle_for_stop` | Idle time after which the app is stopped | `10800` (3 hours) | +| `skip_pause` | If `true`, the app is never paused, only stopped after `idle_for_stop` | `false` | +| `always_on` | If `true`, the app is never paused or stopped | `false` | + +Some rules apply to their combination: + +- Both idle times must be at least `5`, and `idle_for_pause` must be less than `idle_for_stop`. +- Set `skip_pause` for apps that do not tolerate being frozen. + Providing an `idle_for_pause` together with it is forbidden. +- If `always_on` is `true`, providing any other lifecycle field is forbidden. + An always-on app is still stopped when the shard runs low on disk space. + +Note that pausing can be switched off on a shard. +In that case, apps are not paused but only stopped after `idle_for_stop`. -Or you may set an `idle_time_for_shutdown` in seconds. -The default is `60`. -In this case, `always_on` must not be set or set to `false`. +In version 1.2 of the `app_meta.json` format and earlier, this section had a single `idle_time_for_shutdown` field. +Freeshard still reads it from files in those versions and treats it as `idle_for_pause`. From 1ffcdc6f7d99148d636566be5b56ef4889396301 Mon Sep 17 00:00:00 2001 From: ClaydeCode Date: Tue, 3 Nov 2026 21:07:57 +0000 Subject: [PATCH 2/2] developer_docs: list the minimum_portal_size values Co-Authored-By: Claude Opus 5.5 --- digest.md | 2 +- docs/developer_docs/app_meta_json.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/digest.md b/digest.md index 6c95703..1e87415 100644 --- a/digest.md +++ b/digest.md @@ -213,7 +213,7 @@ Field reference: - `entrypoint_port` — `http` (→443) or `mqtt` (→8883). - `paths` — access control by path prefix (see below). Must include `""` default. - `lifecycle` — pause/stop behavior (see Lifecycle). -- `minimum_portal_size` — min shard size required (e.g. `"s"`); omit = all sizes. +- `minimum_portal_size` — min shard size required: `xs` `s` `m` `l` `xl`; 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 diff --git a/docs/developer_docs/app_meta_json.md b/docs/developer_docs/app_meta_json.md index dc5df64..559620d 100644 --- a/docs/developer_docs/app_meta_json.md +++ b/docs/developer_docs/app_meta_json.md @@ -76,6 +76,7 @@ Click on the plus buttons for a description of each field. This is where you can configure this behavior. Read more about it [here](lifecycle.md). 8. This is the minimum size of a managed shard that is required to run your app and should be set according to your app's CPU and memory requirements. + Possible values are `xs`, `s`, `m`, `l` and `xl`. If you do not specify this, your app will be available on all VM sizes. 9. This is where you can configure the information that is displayed in the app store. See [Submitting to the App Store](submitting.md) for more information.