Files

Meow33 984582c520 Update docs/developer/develop/package/manifest.md

Co-authored-by: Yajing <110797546+fnalways@users.noreply.github.com>

2025-11-27 21:19:34 +08:00

30 KiB

Raw Blame History

outline

OlaresManifest Specification

Every Olares Application Chart should include an 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.

:::info NOTE Latest Olares Manifest version: 0.10.0

Modified the categories field
Added the provider field in the Permission section
Added the Provider section, to allow apps to expose specific service interfaces within the cluster
Removed some deprecated fields from the Spec section
Removed some deprecated fields from the Option section
Added the allowMultipleInstall field, allowing the app to be installed as multiple independent instances
Added the Envs section, to define environment variables required by the application ::: :::details Changelog 0.9.0
Added a conflict field in options to declare incompatible applications
Removed analytics field in options
Modified the format of the tailscale section
Added a allowedOutboundPorts field to allow non-http protocol external access through the specified port
Modified the format of the ports section

0.8.3

Add a mandatory field in the dependencies section for dependent applications required for the installation
Add tailscaleAcls section to permit applications to open specified ports via Tailscale

0.8.2

Add a runAsUser option to force the app to run under non root user

0.8.1

Add a ports section to specify exposed ports for UDP or TCP

0.7.1

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

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

::: details OlaresManifest.yaml Example

olaresManifest.version: '0.10.0'
olaresManifest.type: app
metadata:
  name: helloworld
  title: Hello World
  description: app helloworld
  icon: https://app.cdn.olares.com/appstore/default/defaulticon.webp
  version: 0.0.1
  categories:
  - Utilities
entrances:
- name: helloworld
  port: 8080
  title: Hello World
  host: helloworld
  icon: https://app.cdn.olares.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'

:::

olaresManifest.type

Type: string
Accepted Value: app, recommend, middleware

Olares currently supports 3 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

:::info NOTE recommend apps will not be listed in the Olares Market, but you can install recommendation algorithms for Wise by uploading a custom Chart. :::

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.version: 1
olaresManifest.version: 1.1.0
olaresManifest.version: '2.2'
olaresManifest.version: "3.0.122"

Metadata

Basic information about the app shown in the system and Olares Market.

:::info Example

metadata:
  name: nextcloud
  title: Nextcloud
  description: The productivity platform that keeps you in control
  icon: https://app.cdn.olares.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

The title of your app title shown in the Olares Market. Must be within 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.

Entrances

The number of entrances through which to access the app. You must specify at least 1 access method, with a maximum of 10 allowed.

:::info 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.

::: details 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>

:::

Ports

Specify exposed ports

:::info Example

ports:
- name: rdp-tcp             # Name of the entrance that provides service
  host: windows-svc         # Ingress name of the entrance that provides service
  port: 3389                # Port of the entrance that provides service
  protocol: udp             # Protocol used by the exposed port
  exposePort: 46879         # The port to be exposed can only be assigned to one application at a time within the cluster.
  addToTailscaleAcl: true   # Automatically added to Tailscale's ACL

:::

Olares will expose the ports you specify for an application, which are accessible via the application domain name in the local network, for example: 84864c1f.your_olares_id.olares.com:46879. For each port you expose, Olares configures both TCP and UDP with the same port number.

When the addToTailscaleAcl field is set to true, the system will automatically assign a random port and add it to the Tailscale ACLs.

:::info NOTE The exposed ports can only be accessed on the local network or through a VPN. :::

Permission

:::info Example

permission:
  appCache: true
  appData: true
  userData:
  - /Home/

:::

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.

:::info NOTE This configuration has been deprecated since version 1.12.0. :::

:::info 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

provider

Type: list<map>
Optional

Use this field to declare APIs from other applications that your app needs to access. The target application must have exposed a providerName in its own provider section (refer to the Provider section below).

To configure access:

Set the appName field to the name of the target application.
Set the providerName field to match the name specified in the target app’s provider configuration.

You can optionally use the podSelectors field to specify which pods in your app should have access. If this field is omitted, all pods in your app will be injected with the outbound envoy sidecar to enable access.

:::info Example for calling app

# App requiring provider, e.g. sonarr
permission:  
  provider:
  - appName: bazarr
    providerName: bazarr-svc
    podSelectors:
      - matchLabels:
          io.kompose.service: api

::: :::info Example for provider app

#  Provider app, e.g. bazarr
provider:
- name: bazarr-svc
  entrance: bazarr-svc
  paths: ["/*"]
  verbs: ["*"]

:::

Tailscale

Type: map
Optional

Allow applications to add Access Control Lists (ACL) in Tailscale to open specified ports.

:::info Example

tailscale:
  acls:
  - proto: tcp
    dst:
    - "*:46879"
  - proto: "" # Optional. If not specified, all supported protocols will be allowed.
    dst:
    -  "*:4557"

:::

Spec

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

:::info Example

spec:
  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://app.cdn.olares.com/appstore/jellyfin/promote_image_1.jpg
  # The featured image is displayed when the app is featured in the Market.

  promoteImage:
  - https://app.cdn.olares.com/appstore/jellyfin/promote_image_1.jpg
  - https://app.cdn.olares.com/appstore/jellyfin/promote_image_2.jpg
  - https://app.cdn.olares.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:

Create an i18n folder in the Olares Application Chart root directory.
In the i18n folder, create separate subdirectories for each supported locale.
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. :::info 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:

supportArch

Type: list<string>
Accepted Value: amd64, arm64
Optional

Specifies the CPU architecture supported by the application. Currently only amd64 and arm64 are available.

:::info Example

spec:
  supportArch:
  - amd64
  - arm64

:::

:::info NOTE Olares does not support mixed-architecture clusters for now. :::

onlyAdmin

Type: boolean
Default: false
Optional

When set to true, only the admin can install this app.

runAsUser

Type: boolean
Optional

When set to true, Olares forces the application to run under user ID 1000 (as a non-root user).

Middleware

Type: map
Optional

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.

:::info NOTE MongoDB, MySQL, MariaDB, MinIO, and RabbitMQ must first be installed by an admin from the Market before they can be used by other applications. :::