citadel-apps/app-standard-v3.yml

# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema
$schema: https://json-schema.org/draft/2020-12/schema


title: Citadel app.yml v3
description: The third revision of Citadel's app.yml format
type: object

properties:
  version:
    type:
      - string
      - number
    description: The version of the app.yml format you're using.

  metadata:
    type: object
    properties:
      name:
        description: Displayed name of the app
        type: string
      version:
        description: Displayed version for the app
        type: string
      category:
        description: The category you'd put the app in
        type: string
      tagline:
        description: A clever tagline
        type: string
      description:
        description: A longer description of the app
        type: string
      developers:
        description: The awesome people behind the app
        type: object
        patternProperties:
          "^.*$":
            type: string
      dependencies:
        description: >-
          The services the app depends on.

          This can also contain an array like [c-lightning, lnd] if your app requires one of two dependencies to function.          
        type: array
        items:
          type: [string, array]
          items:
            type: string
      repo:
        description: "The development repository (or repositories) for your app, if you have multiple, in the format human readable name: repo url"
        type: [string, object]
        patternProperties:
          "^.*$":
            type: string
      support:
        description: A link to the app support wiki/chat/...
        type: string
      gallery:
        type: array
        description: >-
          URLs or paths in the runcitadel/app-images/[app-name] folder with app
          images          
        items:
          type: string
      path:
        description: The path of the app's visible site the open button should open
        type: string
      defaultPassword:
        description: >-
          The app's default password.
          Set this to $APP_SEED if the password is the environment variable $APP_SEED.          
        type: string
      torOnly:
        description: Whether the app is only available over tor
        type: boolean
      updateContainer:
        type:
          - string
          - array
        description: The container(s) the automatic update system should automatically update.
    required:
      - name
      - version
      - category
      - tagline
      - description
      - developers
      - repo
      - support
      - gallery
    additionalProperties: false

  containers:
    type: array
    items:
      type: object
      properties:
        name:
          type: string
        image:
          type: string
        requiredPorts:
          type: array
          items:
            type: number
          description: Ports this container requires to be exposed to work properly
        port:
          type: number
          description: >-
            If this is the main container, the port inside the container which
            will be exposed to the outside as the port specified in metadata.
            If this is not set, the port is passed as an env variable in the format APP_${APP_NAME}_${CONTAINER_NAME}_PORT            
        preferredOutsidePort:
          type: number
          description: The port this container would like to have "port" exposed as.
        requiresPort:
          type: boolean
          description: Set this to true if the app requires the preferredOutsidePort to be the real outside port.
        environment:
          type: object
        data:
          type: array
          description: >-
            An array of at directories in the container the app stores its data
            in. Can be empty. Please only list top-level directories.            
          items:
            type: string
        user:
          type: string
          description: The user the container should run as
        stop_grace_period:
          type: string
          description: The grace period for stopping the container. Defaults to 1 minute.
        depends_on:
          type: array
          description: The services the container depends on
        entrypoint:
          type:
            - string
            - array
          description: The entrypoint for the container
        mounts:
          type: object
          description: Where to mount some services' data directories
          properties:
            bitcoin:
              type: string
              description: Where to mount the bitcoin dir
            lnd:
              type: string
              description: Where to mount the lnd dir
            c_lightning:
              type: string
              description: Where to mount the c-lightning dir
            additionalProperties: false
        command:
          type:
            - string
            - array
          description: The command for the container
        init:
          type: boolean
          description: Whether the container should be run with init
        stop_signal:
          type: string
          description: The signal to send to the container when stopping
        noNetwork:
          type: boolean
          description: >-
            Set this to true if the container shouldn't get an IP & port
            exposed. This isn't necessary, but helps the docker-compose.yml generator to generate a cleaner output.            
        hiddenServicePorts:
          type: 
            - object
            - number
            - array
          items:
            type:
              - string
              - number
              - array
          description: >-
            This can either be a map of hidden service names (human readable names, not the .onion URL, and strings, not numbers)
            to a port if your app needs multiple hidden services on different ports,
            a map of port inside to port on the hidden service (if your app has multiple ports on one hidden service),
            or simply one port number if your apps hidden service should only expose one port to the outside which isn't 80.            
        restart:
          type: string
          description: When the container should restart. Can be 'always' or 'on-failure'.
        requires:
          description: Dependencies this container requires, it is ignored without it.
          type: array
          items:
            type: string
        network_mode:
          type: string
      additionalProperties: false
      required:
        - name
        - image
    additionalProperties: false

required:
  - metadata
  - containers

additionalProperties: false