OlaresManifest Specification

Every Olares Application Chart should include a OlaresManifest.yaml file in the root directory. OlaresManifest.yaml provides all the essential information about an Olares App. Both the Olares Market protocol and the Olares depend on this information to distribute and install applications.

Here's an example of what a OlaresManifest.yaml file might look like:

OlaresManifest.yaml Example

olaresManifest.version: '0.7.0'
olaresManifest.type: app
metadata:
  name: helloworld
  title: Hello World
  description: app helloworld
  icon: https://file.bttcdn.com/appstore/default/defaulticon.webp
  version: 0.0.1
  categories:
  - Utilities
entrances:
- name: helloworld
  port: 8080
  title: Hello World
  host: helloworld
  icon: https://file.bttcdn.com/appstore/default/defaulticon.webp
  authLevel: private
permission:
  appCache: true
  appData: true
  userData:
  - Home/Documents/
  - Home/Pictures/
  - Home/Downloads/BTDownloads/
spec:
  versionName: '0.0.1'
  featuredImage: https://link.to/featured_image.webp
  promoteImage:
  - https://link.to/promote_image1.webp
  - https://link.to/promote_image2.webp
  fullDescription: |
    A full description of your app.
  upgradeDescription: |
    Describe what is new in this upgraded version.
  developer: Developer's Name
  website: https://link.to.your.website
  sourceCode: https://link.to.sourceCode
  submitter: Submitter's Name
  language:
  - en
  doc: https://link.to.documents
  supportArch:
  - amd64
  limitedCpu: 1000m
  limitedMemory: 1000Mi
  requiredCpu: 50m
  requiredDisk: 50Mi
  requiredMemory: 12Mi

options:
  dependencies:
  - name: olares
    type: system
    version: '>=0.1.0'

NOTE

Olares Manifest Version: 0.7.1

Changelog:

• Add new authLevel value internal
• Change spec>language to spec>locale and support i18n

olaresManifest.type

• Type: string
• Accepted Value: app, recommend, model, middleware

Olares currently supports four types of applications, each requiring different fields. This document uses app as an example to explain each field. For information on other types, please refer to the corresponding configuration guide.

• Recommend Configuration Guide
• Model Configuration Guide

Example

olaresManifest.type: app

olaresManifest.version

• Type: string

As Olares evolves, the configuration specification of OlaresManifest.yaml may change. You can identify whether these changes will affect your application by checking the olaresManifest.version. The olaresManifest.version consists of three integers separated by periods.

• An increase in the first digit indicates the introduction of incompatible configuration items. Applications that haven't updated their OlaresManifest.yaml will be unable to distribute or install.
• An increase in the second digit signifies changes in the mandatory fields for distribution and installation. However, the Olares remains compatible with the application distribution and installation of previous configuration versions. We recommend developers to promptly update and upgrade the application's OlaresManifest.yaml file.
• A change in the third digit does not affect the application's distribution and installation.

Developers can use 1-3 digit version numbers to indicate the application's configuration version. Here are some examples of valid versions:

OlaresManifest.yaml.version: 1
OlaresManifest.yaml.version: 1.1.0
OlaresManifest.yaml.version: '2.2'
OlaresManifest.yaml.version: "3.0.122"

Metadata

Example

metadata:
  name: nextcloud
  title: Nextcloud
  description: The productivity platform that keeps you in control
  icon: https://file.bttcdn.com/appstore/nextcloud/icon.png
  version: 0.0.2
  categories:
  - Utilities
  - Productivity

name

• Type: string
• Accepted Value: [a-z][a-z0-9]?

App’s namespace in Olares, lowercase alphanumeric characters only. It can be up to 30 characters, and needs to be consistent with FolderName and name field in Chart.yaml.

title

• Type: string

Your app title that appears in the Olares Market. It can be up to 30 characters.

description

• Type: string

A short description appears below app title in the Olares Market.

icon

• Type: url

Your app icon that appears in the Olares Market.

The app's icon must be a PNG or WEBP format file, up to 512 KB, with a size of 256x256 px.

version

• Type: string

The Chart Version of the application. It should be incremented each time the content in the Chart changes. It should follow the Semantic Versioning 2.0.0 and needs to be consistent with the version field in Chart.yaml.

categories

• Type: list<string>
• Accepted Value: Blockchain, Utilities, Social Network, Entertainment, Productivity

Used to display your app on different category page in Olares Market.

Entrances

Specify how to access this app, at least 1 required. It is up to 10.

Example

entrances:
- name: a
  host: firefox
  port: 3000
  title: Firefox
  authLevel: public
  invisible: false
- name: b
  host: firefox
  port: 3001
  title: admin

name

• Type: string

• Accepted Value: [a-z]([-a-z0-9]*[a-z0-9])?

  Name of the Entrance. It can be up to 63 characters, and needs to be unique in an app.

port

• Type: int
• Accepted Value: 0-65535

host

• Type: string

• Accepted Value: [a-z]([-a-z0-9]*[a-z0-9])?

  Ingress name of current entrance, lowercase alphanumeric characters and - only. It can be up to 63 characters.

title

• Type: string

Title that appears in the Olares desktop after installed. It can be up to 30 characters.

icon

• Type: url
• Optional

Icon that appears in the Olares desktop after installed. The app's icon must be a PNG or WEBP format file, up to 512 KB, with a size of 256x256 px.

authLevel

• Type: string
• Accepted Value: public, private, internal
• Default: private
• Optional

Specify the authentication level of the entrance.

• Public: Accessible by anyone on the Internet without restrictions.
• Private: Requires authorization for access from both internal and external networks.
• Internal: Requires authorization for access from external networks. No authentication is required when accessing from within the internal network (via LAN/VPN).

invisible

• Type: boolean
• Default: false
• Optional

When invisible is true, the entrance will not be displayed on the Olares desktop.

openMethod

• Type: string
• Accepted Value: default, iframe, window
• Default: default
• Optional

Explicitly defines how to open this entrance in Desktop.

The iframe creates a new window within the desktop window through an iframe. The window opens a new tab in the browser. The default follows the system setting, which is iframe by default.

windowPushState

• Type: boolean
• Default: false
• Optional

When embedding the application in an iframe on the desktop, the application's URL may change dynamically. Due to browser's same-origin policy, the desktop (parent window) cannot directly detect these changes in the iframe URL. Consequently, if you reopen the application tab, it will display the initial URL instead of the updated one.

To ensure a seamless user experience, you can enable this option by setting it to true. This action prompts the gateway to automatically inject the following code into the iframe. This code sends an event to the parent window (desktop) whenever the iframe's URL changes. As a result, the desktop can track URL changes and open the correct page.

Code

<script>
  (function () {
    if (window.top == window) {
        return;
    }
    const originalPushState = history.pushState;
    const pushStateEvent = new Event("pushstate");
    history.pushState = function (...args) {
      originalPushState.apply(this, args);
      window.dispatchEvent(pushStateEvent);
    };
    window.addEventListener("pushstate", () => {
      window.parent.postMessage(
        {type: "locationHref", message: location.href},
        "*"
      );
    });
  })();
</script>

permission

Example

permission:
  appCache: true
  appData: true
  userData:
  - /Home/  
  sysData:
  - dataType: legacy_prowlarr
    appName: prowlarr
    port: 9696
    group: api.prowlarr
    version: v2
    ops:
    - All

appCache

• Type: boolean
• Optional

Whether the app requires read and write permission to the Cache folder. If .Values.userspace.appCache is used in the deployment YAML, then appCache must be set to true.

appData

• Type: boolean
• Optional

Whether the app requires read and write permission to the Data folder. If .Values.userspace.appData is used in the deployment YAML, then appData must be set to true.

userData

• Type: list<string>
• Optional

Whether the app requires read and write permission to user's Home folder. List all directories that the application needs to access under the user's Home. All userData directory configured in the deployment YAML, must be included here.

sysData

• Type: list<map>
• Optional

Declare the list of APIs that this app needs to access.

Example

  sysData:
  - group: service.bfl
    dataType: app
    version: v1
    ops:
    - InstallDevApp
  - dataType: legacy_prowlarr
    appName: prowlarr
    port: 9696
    group: api.prowlarr
    version: v2
    ops:
    - All

All system API providers are list below:

Group	version	dataType	ops
service.appstore	v1	app	InstallDevApp, UninstallDevApp
message-dispatcher.system-server	v1	event	Create, List
service.desktop	v1	ai_message	AIMessage
service.did	v1	did	ResolveByDID, ResolveByName, Verify
api.intent	v1	legacy_api	POST
service.intent	v1	intent	RegisterIntentFilter, UnregisterIntentFilter, SendIntent, QueryIntent, ListDefaultChoice, CreateDefaultChoice, RemoveDefaultChoice, ReplaceDefaultChoice
service.message	v1	message	GetContactLogs, GetMessages, Message
service.notification	v1	message	Create
service.notification	v1	token	Create
service.search	v1	search	Input, Delete, InputRSS, DeleteRSS, QueryRSS, QuestionAI
secret.infisical	v1	secret	CreateSecret, RetrieveSecret
secret.vault	v1	key	List, Info, Sign

spec

Additional information about the application, primarily used for display in the Olares Market.

Example

spec:
  namespace: os-system 
  # optional. Install the app to a specified namespace, e.g. os-system, user-space, user-system
  
  onlyAdmin:  true 
  # optional. When set to true, only the admin can install this app.
  
  versionName: '10.8.11' 
  # The version of the application that this chart contains. It is recommended to enclose the version number in quotes. This value corresponds to the appVersion field in the `Chart.yaml` file. Note that it is not related to the `version` field.

  featuredImage: https://file.bttcdn.com/appstore/jellyfin/promote_image_1.jpg
  # The featured image is displayed when the app is featured in the Market.

  promoteImage:
  - https://file.bttcdn.com/appstore/jellyfin/promote_image_1.jpg
  - https://file.bttcdn.com/appstore/jellyfin/promote_image_2.jpg
  - https://file.bttcdn.com/appstore/jellyfin/promote_image_3.jpg
  fullDescription: |
    Jellyfin is the volunteer-built media solution that puts you in control of your media. Stream to any device from your own server, with no strings attached. Your media, your server, your way.
  upgradeDescription: |
    upgrade descriptions
  developer: Jellyfin
  website: https://jellyfin.org/
  doc: https://jellyfin.org/docs/
  sourceCode: https://github.com/jellyfin/jellyfin
  submitter: Olares
  locale:
  - en-US
  - zh-CN
  # List languages and regions supported by this app

requiredMemory: 256Mi
  requiredDisk: 128Mi
  requiredCpu: 0.5
  # Specifies the minimum resources required to install and run the application. Once the app is installed, the system will reserve these resources to ensure optimal performance.

  limitedDisk: 256Mi
  limitedCpu: 1
  limitedMemory: 512Mi
  # Specifies the maximum resource limits for the application. If the app exceeds these limits, it will be temporarily suspended to prevent system overload and ensure stability.

  legal:
  - text: Community Standards
    url: https://jellyfin.org/docs/general/community-standards/
  - text: Security policy
    url: https://github.com/jellyfin/jellyfin/security/policy
  license:
  - text: GPL-2.0
    url: https://github.com/jellyfin/jellyfin/blob/master/LICENSE
  supportClient:
  - android: https://play.google.com/store/apps/details?id=org.jellyfin.mobile
  - ios: https://apps.apple.com/us/app/jellyfin-mobile/id1480192618

i18n

To add multi-language support for your app in Olares Market:

1. Create an i18n folder in the Olares Application Chart root directory.
2. In the i18n folder, create separate subdirectories for each supported locale.
3. In each locale subdirectory, place a localized version of the OlaresManifest.yaml file.

Olares Market will automatically display the content of the corresponding "OlaresManifest.yaml" file based on users' locale settings.

Example

.
├── Chart.yaml
├── README.md
├── OlaresManifest.yaml
├── i18n
│   ├── en-US
│   │   └── OlaresManifest.yaml
│   └── zh-CN
│       └── OlaresManifest.yaml
├── owners
├── templates
│   └── deployment.yaml
└── values.yaml

Currently, you can add i18n content for the following fields:

metadata:
  description:
  title:
spec:
  fullDescription:
  upgradeDescription:

middleware

• Optional
• Type: map

The Olares provides highly available middleware services. Developers do not need to install middleware repeatedly. Just simply add required middleware here, You can then directly use the corresponding middleware information in the application's deployment YAML file.

Use the scripts field to specify scripts that should be executed after the database is created. Additionally, use the extension field to add the corresponding extension in the database.

Example

middleware:
  postgres:
    username: immich
    databases:
    - name: immich
      extensions:
      - vectors
      - earthdistance
      scripts:
      - BEGIN;                                           
      - ALTER DATABASE $databasename SET search_path TO "$user", public, vectors;
      - ALTER SCHEMA vectors OWNER TO $dbusername;
      - COMMIT;
      # The OS provides two variables, $databasename and $dbusername, which will be replaced by TAPR when the command is executed.
  redis:
    password: password
    namespace: db0
  mongodb:
    username: chromium
    databases:
    - name: chromium
      script:
      - 'db.getSiblingDB("$databasename").myCollection.insertOne({ x: 111 });'
      # Please make sure each line is a complete query.

Use the middleware information in deployment YAML

- name: DB_POSTGRESDB_DATABASE # The database name you configured in OlaresManifest, specified in middleware.postgres.databases[i].name
  value: {{ .Values.postgres.databases.<dbname> }}
- name: DB_POSTGRESDB_HOST
  value: {{ .Values.postgres.host }}
- name: DB_POSTGRESDB_PORT
  value: "{{ .Values.postgres.port }}"
- name: DB_POSTGRESDB_USER
  value: {{ .Values.postgres.username }}
- name: DB_POSTGRESDB_PASSWORD
  value: {{ .Values.postgres.password }}


# For mongodb, the corresponding value is as follow
host --> {{ .Values.mongodb.host }}
port --> "{{ .Values.mongodb.port }}"  # The port and password in the yaml file need to be enclosed in double quotes.
username --> {{ .Values.mongodb.username }}
password --> "{{ .Values.mongodb.password }}" # The port and password in the yaml file need to be enclosed in double quotes.
databases --> "{{ .Values.mongodb.databases }}" # The value type of database is a map. You can get the database using {{ .Values.mongodb.databases.<dbname> }}. The <dbname> is the name you configured in OlaresManifest, specified in middleware.mongodb.databases[i].name


# For Redis, the corresponding value is as follow
host --> {{ .Values.redis.host }}
port --> "{{ .Values.redis.port }}"
password --> "{{ .Values.redis.password }}"

options

Configure system-related options here

policies

• Optional
• Type: map

Define detailed access control for subdomains of the app.

Example

options:
  policies:
    - uriRegex: /$
      level: two_factor
      oneTime: false
      validDuration: 3600s
      entranceName: gitlab

clusterScoped

• Optional
• Type: map

Whether this app is installed for all users in a Olares cluster.

Example For Server

metadata:
  name: gitlab
options:
  appScope:
    clusterScoped: true
    appRef:
      - gitlabclienta #app name of clients
      - gitlabclientb

Example For Client

metadata:
  name: gitlabclienta
options:
  dependencies:
    - name: olares
      version: ">=0.3.6-0"
      type: system
    - name: gitlab #app name of server
      version: ">=0.0.1"
      type: application

analytics

• Optional
• Type: map

Enable website analytics for the app.

Example

options:
  analytics:
    enabled: true

dependencies

• Type: list<map>

Specify the dependencies and requirements for your application. It includes other applications that your app depends on, as well as any specific operating system (OS) version requirements.

Example

options:
  dependencies:
    - name: olares
      version: ">=1.0.0-0"
      type: system
    - name: mongodb
      version: ">=6.0.0-0"
      type: middleware

websocket

• Optional
• Type: map

Enable websocket for the app. Refer to websocket for more information.

Example

options:
  websocket:
    url: /ws/message
    port: 8888

resetCookie

• Optional
• Type: map

If the app requires cookies, please enable this feature. Refer to cookie for more information

Example

options:
  resetCookie:
    enabled: true

upload

• Optional
• Type: map

The Olares Application Runtime (TAPR) includes a built-in file upload component designed to simplify the file upload process in your application. Refer to upload for more information.

Example

upload:
  # The types of files that are allowed to be uploaded, * stands for any type, The type of the uploaded file must be in the list.
  fileType:
    - pdf
  # The path of 'dest' must be a mountPath
  dest: /appdata
  # The maximum size of file, in bytes
  limitedSize: 3729747942

mobileSupported

• Optional
• Type: boolean
• Default: false

Determine whether the application is compatible with mobile web browsers and can be displayed on the mobile version of Olares Desktop. Enable this option if the app is optimized for mobile web browsers. This will make the app visible and accessible on the mobile version of Olares Desktop.

Example

mobileSupported: true

oidc

• Optional
• Type: map

The Olares includes a built-in OpenID Connect authentication component to simplify identity verification of users. Enable this option to use OpenID in your app.

# OpenID related varibles in yaml
{{ .Values.oidc.client.id }}
{{ .Values.oidc.client.secret }}
{{ .Values.oidc.issuer }}

Example

oidc:
  enabled: true
  redirectUri: /path/to/uri
  entranceName: navidrome

apiTimeout

• Optional
• Type: int

Specifies the timeout limit for API providers in seconds. The default value is 15. Use 0 to allow an unlimited API connection.

Example

apiTimeout: 0