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
12 changes: 11 additions & 1 deletion digest.md
Original file line number Diff line number Diff line change
Expand Up @@ -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('<name>') }}`, from freeshard 0.41.2):
Secrets (`{{ secret('<name>') }}`, 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') }}`.
Expand Down Expand Up @@ -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": [
Expand Down Expand Up @@ -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):
Expand Down
32 changes: 32 additions & 0 deletions docs/developer_docs/app_meta_json.md
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand Down Expand Up @@ -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

Expand Down
8 changes: 6 additions & 2 deletions docs/developer_docs/docker_compose_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

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

## Limitations

Technically, you can use any docker-compose feature in your template.
Expand Down
Loading