The app.json File
For Portal to recognize your app, you have to provide an app.json
file containing some metadata and instructions on
how to run your app.
The app.json
contains all metadata about your app.
It tells the Portal what to run by defining a docker image and how to run it.
And it contains information that is important to display in the app store,
like the official name and a description.
Full Example
JSON | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
|
Description of Fields
field | description |
---|---|
v | The version of the app.json format. Should be "1.0". |
name | Your app's name as seen in the app store, on the Portal home screen, and in the URL |
image | The docker image reference of your app; this is what you usually use with docker run |
port | The port at which your app publishes its GUI or API; this port will be forwarded to the user's browser |
data_dirs (optional) | A list of directories inside your image; Portal will create matching directories inside its file system and mount those into them; see Persisting Data for details |
services (optional) | A list of built-in services that your app uses; Portal will prepare them for you and provide access information in the form of template variables; see Portal's Internal Services for details |
env_vars (optional) | A dictionary of environment variables that are set for your app |
paths | An object which you can use to define access control rules for your app by defining how each URL path should be handled; for more details see Routing and Access Control |
lifecycle | An object which defines if and when your app is automatically shut down in order to conserve resources. |
store_info (optional) | Information that is read by the app store and displayed there. |
Templating for environment variables
You can include variables in the values of the env_vars
section that are substituted during install time.
They help you include values that are specific to each individual Portal.
Use Jinja-like double curly brackets for this.
Example
With this snippet, you can tell your app the actual full domain at which it is published.
JSON | |
---|---|
1 2 3 |
|
Variables
variable | description | example |
---|---|---|
portal.domain |
The fully qualified domain name of the Portal | 8271dd.p.getportal.org |
portal.id |
The full-length hash-ID of the Portal | 8271ddlqxa5fcp7a5l0s61pbqqtglba31d65jg2fqhdwdw2kkr7l94b2q54hfdl2zfn5s5g1nkjy1z1a3f02tl8yln14050l8s598f2 |
More variables are provided by Portal's built-in services if your app defines them as dependencies. See Portal's Internal Services for details.
Versioning
Since the format of the app.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 2.0
.
When new versions are released, we will attempt to make them backwards compatible. That means that Portal still can process the previous version and translate it to the current one.
Past Updates
version 3.0
to version 3.1
- Added the
lifecycle
section.
version 2.0
to version 3.0
- Changed the way, variables of internal services are addressed by
env_vars
templates. Example before:{{ apps[\"myapp\"].postgres.connection_string }}
vs. example after:{{ postgres.connection_string }}
.
version 1.0
to version 2.0
- Removed the
description
field and instead added thestore_info
section.
version 0.0
to version 1.0
- Removed the
authentication
section and instead added thepaths
section. - Added the
v
attribute to indication the schema version - anapp.json
withoutv
is assumed to be version0.0
.