Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 32 additions & 14 deletions digest.md
Original file line number Diff line number Diff line change
Expand Up @@ -156,11 +156,11 @@ Secrets (`{{ secret('<name>') }}`, 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",
Expand All @@ -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",
Expand All @@ -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.
Expand All @@ -211,8 +212,8 @@ 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).
- `minimum_portal_size` — min shard size required (e.g. `"s"`); omit = all sizes.
- `lifecycle` — pause/stop behavior (see Lifecycle).
- `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
Expand All @@ -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).

Expand Down Expand Up @@ -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

Expand Down
23 changes: 17 additions & 6 deletions docs/developer_docs/app_meta_json.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)!
Expand All @@ -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)!
Expand All @@ -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.
Expand All @@ -71,10 +72,11 @@ 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.
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.
Expand Down Expand Up @@ -119,8 +121,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}.
Expand All @@ -130,14 +134,21 @@ 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
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.
Expand Down
43 changes: 34 additions & 9 deletions docs/developer_docs/lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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`.
Loading