DAppNodeDocsv2

The setup wizard for DAppNode packages helps automate the package customization and improve its user experience. You can allow users to conveniently edit environment variables, port mappings, and upload files while interacting with a simple web form, right before installing the package.

How to use

To add this functionality, create a file setup-wizard.yml in the root of your DAppNode package directory. Both JSON and YAML formats are supported, but YAML makes writing markdown text blocks much easier (its used in the description property).

  DAppNodePackage-my-package.public.dappnode.eth/
  ├── build
  │   ├── ...
  │   └── Dockerfile
  ├── avatar-my-package.png
  ├── dappnode_package.json
  ├── docker-compose.yml
 └── setup-wizard.yml

Example

version: "2"
fields:
  - id: payoutAddress,
    target:
      type: environment
      name: PAYOUT_ADDRESS
      service: service1
    title: Payout address
    description: >-
      Address to send **payouts** too. [More info](https://more.info)
      Supports markdown and multiline
    secret: true
    pattern: "^0x[a-fA-F0-9]{40}$"
    patternErrorMessage: Must be a valid address (0x1fd16a...)
    enum:
      - normal
      - archive
      - advanced
    required: true
    if: { "mode": { "enum": ["advanced"] } }

version

Identify this setup wizard version. Currently only supports version "2"

is required
type: string
value: "2"

fields

Setup wizard fields. Fields to show in the setup wizard form UI

is required
type: Array type: object[]

All items must be of the type: object with the following properties:

Property	Type	Required	Default
`target`	object	Optional
`id`	string	Required
`title`	string	Required
`description`	string	Required
`secret`	boolean	Optional	`false`
`pattern`	string	Optional
`patternErrorMessage`	string	Optional
`enum`	array	Optional
`required`	boolean	Optional
`if`	object	Optional

id

Unique property ID required for internal form parsing, and to use the if conditional block.

is required
type: string

Example:

id: payoutAddress

target

Maps the setup wizard field to a package configuration option. Supports:

environment: For environment variables
portMapping: For port mapping
namedVolumeMountpoint: To allow hosting a specific package volume into a different drive or mountpoint
allNamedVolumesMountpoint: To allow hosting all package volumes into a different drive or mountpoint
fileUpload: To upload user files to the package container

environment

To customize environment variables with user input. Targeted variables must be declared in the package’s docker-compose. You can customize the type of input shown in the UI with this field properties

secret: Hides input, to collect sensitive data.
pattern: To validate input against any Regex expression.
enum: Show as a select dropdown menu.

target:
  type: environment
  name: PAYOUT_ADDRESS
  service: service1

name

The name of the environment variable as declared in the docker-compose.

is required
type: string

Example:

name: PAYOUT_ADDRESS

service

In multi-service package, which service should be targeted with this setting.

type: string

Examples:

service: service1

portMapping

To customize port mappings with user input. Targeted container port must be declared in the package’s docker-compose.

target:
  type: portMapping
  containerPort: 9554/UDP
  service: service1

containerPort

Exposed container port to map to. Must follow the format {portNumber} or {portNumber}/{PROTOCOL}, where PROTOCOL must be TCP or UDP in all caps.

is required
type: string

Examples:

containerPort: 9554

containerPort: 9554/TCP

service

See service

namedVolumeMountpoint

To allow hosting a specific package volume into a different drive or mountpoint

target:
  type: namedVolumeMountpoint
  volumeName: blockchain_data

volumeName

Name of the docker volume to allow the user to change its mountpoint. Must have the exact same name as declared in the package’s compose volumes section.

is required
type: string

Example:

volumeName: blockchain_data

allNamedVolumesMountpoint

To allow hosting all package volumes into a different drive or mountpoint at once. Use this option if your package has multiple heavy volumes whose mountpoint should be changed at once.

target:
  type: allNamedVolumesMountpoint

fileUpload

To allow hosting a specific package volume into a different drive or mountpoint

target:
  type: fileUpload
  path: /usr/src/config.json
  service: service1

path

Destination path to upload the file to. Must be a valid absolute path in the package container.

is required
type: string

Example:

path: /usr/src/config.json

service

See service

title

The Title Schema

is required
default: ""
type: string

Example:

title: Payout address

description

The Description Schema

is required
default: ""
type: string

Example:

description: >-
  Address to send **payouts** too. [More info](https://more.info)
  Supports markdown and multiline

secret

Display field input as hidden. Use to collect sensitive data. It will automatically activate if the field name contains “secret” “passphrase” or “password”. Only available with target environment.

is optional
default: false
type: boolean

Example:

secret: true

pattern

Enforce this property to satisfy a regex before continuing. Only available with target environment. Use also patternErrorMessage to show a nicer error message when regex validation fails.

is optional
type: string

Example:

pattern: "^0x[a-fA-F0-9]{40}$"

patternErrorMessage

Error to show if the regex pattern validation fails. Only available with target environment.

is optional
type: string

Examples:

patternErrorMessage: Must be a valid address (0x1fd16a...)

patternErrorMessage: Must be at least 8 characters long

enum

List valid options. Will automatically display the input as a select menu. Only available with target environment.

is optional
type: Array type: string[]

All items must be of the type: string

Examples

enum:
  - normal
  - archive
  - advanced

required

Enforce this property to be provided before continuing

is optional
type: boolean

Examples

required: true

if

Only display the field property if the if schema is valid against the current form data provided by the user. The form data is an object with the structure { [field.id]: JSONSchema }.

is optional
type: object

Examples:

if: { "mode": { "enum": ["advanced"] } }

if: { "mode": { "enum": ["archive"] } }