Skip to main content

Wizard Reference

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 (it's 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:

PropertyTypeRequiredDefault
targetobjectOptional
idstringRequired
titlestringRequired
descriptionstringRequired
secretbooleanOptionalfalse
patternstringOptional
patternErrorMessagestringOptional
enumarrayOptional
requiredbooleanOptional
ifobjectOptional

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

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.

It exists two ways of defining environment variables. The first one, where you define one environment var for one service, you the format to do it is the following:

target:
type: environment
name: PAYOUT_ADDRESS
service: service1

In case you want to define an environment variable that is used in multiple services you can define it in the next way:

target:
type: environment
name: PAYOUT_ADDRESS
service: [service1, service2, service2]
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 uploading user files to the package container

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"] } }