Dappnode Package (DNP) manifest

The Dappnode Package manifest defines all the necessary information for a Dappnode to understand this package:

IPFS of BZZ hashes to download its docker image
Docker related data to configure and run its container
Metadata to control how the package is shown in the admin UI.

Example

{
  "name": "ipfs.dnp.dappnode.eth",
  "version": "0.2.0",
  "upstreamVersion": "2.6.0-beta",
  "shortDescription": "Distributed file system for storing and accessing data.",
  "description": "Welcome! IPFS is a distributed system for storing and accessing files, websites, applications, and data. If you’re new to IPFS, check our [introductory page](https://ipfs.io/#why) for an easy overview. \n\nWith this node you can upload and download files from IPFS using it own fancy web console at [http://ipfs.dappnode:5001/webui](http://ipfs.dappnode:5001/webui). Other Dappnode Packages and external applications can use its API at the endpoint `http://ipfs.dappnode:5001/api`. Go to the [IPFS HTTP API full reference](https://docs.ipfs.io/reference/api/http/) to check all the features of the API.",
  "type": "service",
  "chain": "ethereum",
  "mainService": "webserver",
  "dockerTimeout": "5min",
  "dependencies": {
    "bitcoin.dnp.dappnode.eth": "^0.1.2",
    "swarm.dnp.dappnode.eth": "latest"
  },
  "requirements": {
    "minimumDappnodeVersion": "0.2.0"
  },
  "globalEnvs": {
    "all": "true"
  },
  "architectures": ["linux/amd64", "linux/arm64"],
  "backup": [
    {
      "name": "keystore",
      "path": "/root/.raiden/secret/keystore",
      "service": "validator"
    }
  ],
  "changelog": "Brief summary of the most relevant changes that the user must known before installing",
  "warnings": {
    "onInstall": "You must set the PASSWORD ENV before installing the Dappnode Package in order for the setup to work correctly.",
    "onUpdate": "Your VPN connection will be lost when the VPN finalizes updating. Leave 1-2 minutes after executing the update and then reconnect and refresh this site.",
    "onReset": "You MUST properly close your open channels before resetting this Dappnode Package or you may lose your funds.",
    "onRemove": "You MUST properly close your open channels before removing this Dappnode Package or you may lose your funds."
  },
  "updateAlerts": [
    {
      "from": "0.1.x",
      "to": "0.1.x",
      "message": "Major update to OpenVPN: This update breaks compatibility with the last VPN version. Please read the migration guide: https://migration020.dappnode.io"
    }
  ],
  "disclaimer": {
    "message": "This software is experimental, presented “as is” and inherently carries risks."
  },
  "style": {
    "featuredBackground": "linear-gradient(to right, #323131, #395353)",
    "featuredColor": "white",
    "featuredAvatarFilter": "invert(1)"
  },
  "exposable": [
    {
      "name": "Geth JSON RPC",
      "description": "JSON RPC endpoint for Geth mainnet",
      "serviceName": "beacon_chain",
      "port": 80
    }
  ],
  "author": "Dappnode Association <admin@dappnode.io> (https://github.com/dappnode)",
  "contributors": [
    "Michael First <developerHanlder@project.io> (https://github.com/developerHanlder)",
    "Michael Second <developerHanlder@project.io> (https://github.com/developerHanlder)"
  ],
  "categories": ["Developer tools", "Blockchain"],
  "keywords": ["DappnodeCore"],
  "links": {
    "homepage": "https://github.com/dappnode/DNP_IPFS#readme",
    "ui": "http://ipfs.dappnode:5001/webui",
    "api": "http://ipfs.dappnode:5001/api/v0",
    "gateway": "http://ipfs.dappnode:8080/ipfs"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/dappnode/DNP_IPFS.git",
    "directory": "packages/react-dom"
  },
  "bugs": {
    "url": "https://github.com/dappnode/DNP_IPFS/issues"
  },
  "license": "GPL-3.0"
}

Properties reference

Property	Type	Required
name	`string`	Required
version	`string`	Required
upstreamVersion	`string`	Optional
shortDescription	`string`	Optional
description	`string`	Required
type	`enum`	Required
chain	`enum`	Optional
mainService	`string`	Optional
dockerTimeout	`string`	Optional
dependencies	`object`	Optional
requirements	`object`	Optional
globalEnvs	`object`	Optional
architectures	`enum[]`	Optional
backup	`object[]`	Optional
changelog	`string`	Optional
warnings	`object`	Optional
updateAlerts	`object[]`	Optional
disclaimer	`object`	Optional
style	`object`	Optional
exposable	`object[]`	Optional
author	`string`	Optional
contributors	`string[]`	Optional
categories	`enum[]`	Optional
keywords	`string[]`	Optional
links	`object`	Optional
repository	`object`	Optional
bugs	`object`	Optional
license	`string`	Required

name

Dappnode Package ENS name.

is required
type: string

Example:

"ipfs.dnp.dappnode.eth"

version

Dappnode Package semantic version (semver).

is required
type: string

All instances must conform to this regular expression

^((([0-9]+).([0-9]+).([0-9]+)))$

test example: 0.2.0

Example:

"0.2.0"

upstreamVersion

For Dappnode Packages that only wrap existing software (i.e. Bitcoin node, Ethereum node), the underlying software version can be specified here. It will be shown in the admin UI alongside the field version.

is optional
type: string

Examples:

"2.6.0-beta"

"any-text"

shortDescription

Short Dappnode Package description, 6-8 words sentence briefly describing the purpose of this Dappnode Package. The purpose is to quickly grab users' attention and clearly define its purpose. Markdown is discouraged as it will NOT be rendered on the Dappnode Package store view.

is optional
type: string

Example:

"Distributed file system for storing and accessing data."

description

Dappnode Package description. Markdown and links are allowed and ecouraged to give users the option to read more information about this Dappnode Package.

is required
type: string

Example:

"Welcome! IPFS is a distributed system for storing and accessing files, websites, applications, and data. If you’re new to IPFS, check our [introductory page](https://ipfs.io/#why) for an easy overview. \n\nWith this node you can upload and download files from IPFS using it own fancy web console at [http://ipfs.dappnode:5001/webui](http://ipfs.dappnode:5001/webui). Other Dappnode Packages and external applications can use its API at the endpoint `http://ipfs.dappnode:5001/api`. Go to the [IPFS HTTP API full reference](https://docs.ipfs.io/reference/api/http/) to check all the features of the API."

type

Type of this Dappnode Package. It is used to trigger some special features such as core functionality.

is required
default: "service"
type: string

The value of this property must be equal to one of the known values below.

Value	Description
`service`	Can have ENVs a depend on library Dappnode Packages
`library`	Should not have ENVs and cannot depend on service Dappnode Packages
`dncore`	Dappnode Packages that are part of the Dappnode core and have special permissions

Examples:

"service"

"dncore"

chain

Indicate that this Dappnode Package is a blockchain node so the admin UI shows its syncing status

is optional
type: string

The value of this property must be equal to one of the known values below.

Value	Description
`ethereum`	Must have an Ethereum JSON RPC exposed internally at port 8545
`bitcoin`	Must have a standard Bitcoin JSON API exposed at the default port (8332). Uses the NPM package `bitcoin-core`
`monero`	Must have a Monero API exposed internally at port 18081. Uses the NPM package `monero-rpc`

Examples:

"ethereum"

"bitcoin"

"monero"

mainService

For multi-service packages, indicate which service is the main one. The root ENS domain of this package will be mapped to this service IP.

is optional
type: string

Examples:

"webserver"

"backend"

"service1"

dockerTimeout

Modify the default Docker timeout of 10 seconds. It affects package updates, removals, container restarts, start and stop, updating config environments and port mappings. You can either pass a numerical value in seconds or a string representation parsed with timestring. Available from DAPPMANAGER v0.2.36

is optional
type: string

Examples:

"5min"

"60"

dependencies

Dappnode Package dependencies. Must be an object where the keys are the Dappnode Package's ENS. The values must be a semantic range, i.e. '0.2.0', '^0.2.1', '*', 'latest', '/ipfs/QmWwMb3XhuCH6JnCF6m6EQzA4mW9pHHtg7rqAfhDr2ofi8'.

is optional
type: object with the following properties:

Property	Type	Required

Examples:

{
  "bitcoin.dnp.dappnode.eth": "^0.1.2",
  "swarm.dnp.dappnode.eth": "latest"
}

{
  "only-for-dev-1.dappnode.eth": "/ipfs/QmYjtig7VJQ6XsnUjqqJvj7QaMcCAwtrgNdahSiFofrE7o",
  "only-for-dev-2.dappnode.eth": "/ipfs/zdj7WWeQ43G6JJvLWQWZpyHuAMq6uYWRjkBXFad11vE2LHhQ7"
}

requirements

Specify requirements to be met before allowing users to install this Dappnode Package.

is optional
type: object with the following properties:

Property	Type	Required
`minimumDappnodeVersion`	string	Optional

minimumDappnodeVersion

Minimum Dappnode version that includes all the features necessary to run this Dappnode Package.

is optional
type: string

All instances must conform to this regular expression

^((([0-9]+).([0-9]+).([0-9]+)))$

test example: 0.2.0

Example:

"0.2.0"

globalEnvs

Request the DAPPMANAGER to inject global ENVs to this package's containers

is optional
type: object with the following properties:

Property	Type	Required
`all`	boolean	Optional

all

Request the DAPPMANAGER to inject all available global ENVs

is optional
type: boolean

Example:

"true"

architectures

Build and distribute this package in multiple architectures using Docker's buildx plugin

is optional
type: Array type: enum[]

All items must be of the type: string

The value of this property must be equal to one of the known values below.

Value	Description
`linux/amd64`	Default architecture, x86-64
`linux/arm64`	ARM architecture

Example:

["linux/amd64", "linux/arm64"]

backup

Allows users to download and restore a backup of key files of this package. If this property is non-empty array, a new view will be available in the admin UI for this Dappnode Package. The files or directories specified in the array will be bundled in a tarball. As long as the name properties stay the same, their associated paths can change in future versions. Then, when restoring an old backup, the new paths will be associated to files stored under the same name keys. Note: it is recommended to only backup lightweight files such as configs, keys or passwords.

is optional
type: Array type: object[]

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

Property	Type	Required
`name`	string	Required
`path`	string	Required
`service`	string	Optional

name

A key identifier of this file or directory. Its purpose is to allow the path to change in the future.

is required
type: string
minimum length: 1 characters

Examples:

"keystore"

"config"

"keys"

path

Path to the file or directory to backup. It MUST be an absolute path (do not use the ~ character) for the backup tool to work correctly.

is required
type: string
minimum length: 1 characters

Examples:

"/root/.raiden/secret/keystore"

"/usr/src/app/config.json"

service

Service to which the path belongs to. Must be equal to the name used in the docker-compose services object

is optional
type: string
minimum length: 1 characters

Examples:

"validator"

"service1"

changelog

Description of relevant changes of this specific version. Supports markdown and links.

is optional
type: string

Example:

"Brief summary of the most relevant changes that the user must known before installing"

warnings

Very relevant information that MUST be shown to the user BEFORE executing a specific action in the Dappnode Package's lifecycle.

is optional
type: object with the following properties:

Property	Type	Required
`onInstall`	string	Optional
`onUpdate`	string	Optional
`onReset`	string	Optional
`onRemove`	string	Optional

onInstall

Will be shown before installing the Dappnode Package.

is optional
type: string

Example:

"You must set the PASSWORD ENV before installing the Dappnode Package in order for the setup to work correctly."

onUpdate

Will be shown before updating the Dappnode Package, not in the first installation.

is optional
type: string

Example:

"Your VPN connection will be lost when the VPN finalizes updating. Leave 1-2 minutes after executing the update and then reconnect and refresh this site."

onReset

Will be shown before resetting the Dappnode Package.

is optional
type: string

Example:

"You MUST properly close your open channels before resetting this Dappnode Package or you may lose your funds."

onRemove

Will be shown before removing the Dappnode Package.

is optional
type: string

Example:

"You MUST properly close your open channels before removing this Dappnode Package or you may lose your funds."

updateAlerts

Alerts targeted to a specific update jump.

is optional
type: Array type: object[]

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

Property	Type	Required	Default
`from`	string	Required
`to`	string	Optional	`"*"`
`message`	string	Required

from

Semver range, show this message when a user updates this Dappnode Package FROM a version that satisfies this range.

is required
type: string
minimum length: 1 characters

Examples:

"0.1.x"

"^0.2.0"

to

Semver range, show this message when a user updates this Dappnode Package TO a version that satisfies this range.

is optional
default: "*"
type: string
minimum length: 1 characters

Examples:

"0.1.x"

"^0.2.0"

"*"

message

Alert message to be shown when from and to ranges are satisfied.

is required
type: string
minimum length: 1 characters

Example:

"Major update to OpenVPN: This update breaks compatibility with the last VPN version. Please read the migration guide: https://migration020.dappnode.io"

Specific update jump alert.

disclaimer

Disclaimer to be shown to the user on install, and will require the user to approve it.

is optional
type: object with the following properties:

Property	Type	Required
`message`	string	Required

message

The message shown in the pop-up. Markdown and links are allowed.

is required
type: string

Example:

"This software is experimental, presented “as is” and inherently carries risks."

style

Graphic information to control the appearance of Dappnode Package related items in the admin UI.

is optional
type: object with the following properties:

Property	Type	Required
`featuredBackground`	string	Optional
`featuredColor`	string	Optional
`featuredAvatarFilter`	string	Optional

featuredBackground

CSS background property to be applied to the Dappnode Package card in the Dappnode Package store if featured. Go to the Mozilla CSS background reference for valid values.

is optional
type: string

Examples:

"linear-gradient(to right, #323131, #395353)"

"black"

featuredColor

CSS color property to be applied to the Dappnode Package card in the Dappnode Package store if featured. Go to the Mozilla CSS color reference for valid values.

is optional
type: string

Examples:

"white"

"#fff"

featuredAvatarFilter

CSS filter property to be applied to <img> component (avatar) of the Dappnode Package card in the Dappnode Package store if featured. Go to the Mozilla CSS filter reference for valid values.

is optional
type: string

Examples:

"invert(1)"

"grayscale(80%);"

exposable

Exposable services safe to be in the public internet

is optional
type: Array type: object[]

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

Property	Type	Required
`name`	string	Required
`description`	string	Optional
`serviceName`	string	Optional
`port`	number	Required
`fromSubdomain`	string	Optional

name

Short human readable name of this exposable service

is required
type: string
minimum length: 1 characters

Example:

"Geth JSON RPC"

description

Description of this exposable service

is optional
type: string

Example:

"JSON RPC endpoint for Geth mainnet"

serviceName

Docker compose service this exposable service belongs to. Defaults to the first service.

is optional
type: string
minimum length: 1 characters

Example:

"beacon_chain"

port

Port this exposable service listens to

is required
type: number

Examples:

Single exposable service item

author

Main author of this Dappnode Package. Must follow the structure ${name} <${email}> (${githubUserLink}).

is optional
type: string
minimum length: 1 characters

Example:

"Dappnode Association <admin@dappnode.io> (https://github.com/dappnode)"

contributors

Contributing authors of this Dappnode Package.

is optional
type: Array type: string[]

All items must be of the type: string

minimum length: 1 characters

Contributor author. Must follow the structure ${name} <${email}> (${githubUserLink}).

Example:

[
  "Michael First <developerHanlder@project.io> (https://github.com/developerHanlder)",
  "Michael Second <developerHanlder@project.io> (https://github.com/developerHanlder)"
]

Value	Description
`Blockchain`	Blockchain nodes, i.e. Bitcoin, Monero
`Communications`	Decentralized networking or chat solutions, i.e. Swarm
`Developer tools`	Packages that their main purpose is to aid in developing, i.e. testnets
`ETH2.0`	Packages to participate or use the Eth2.0 network
`Economic incentive`	Packages that offer an economic incentive or reward to the admin that runs it, i.e. Lightning Network
`Monitoring`	Packages that track metrics
`Payment channels`	Packages whose main purpose is to manage or control payment channels, i.e. Raiden
`Storage`	Decentralized storage solutions, i.e. Swarm

keywords

Keywords, relevant and descriptive of this Dappnode Package. They will be shown in the admin UI Dappnode Package store.

is optional
type: Array type: string[]

All items must be of the type: string

minimum length: 1 characters

Single keyword.

links

Various links (URLs) useful for the user of this package. All links will be shown in the dedicated view of this package in the admin UI. The predefined links properties below will be shown with concept related icons. Other links will be shown as well but with their plain name instead of an icon.

is optional
type: object with the following properties:

Property	Type	Required
`homepage`	string	Optional
`ui`	string	Optional
`api`	string	Optional
`gateway`	string	Optional

homepage

Url to an informative homepage for this Dappnode Package. Should be a README or landing website.

is optional
type: string

Example:

"https://github.com/dappnode/DNP_IPFS#readme"

ui

Url to this DNP's Dappnode local UI.

is optional
type: string

Example:

"http://ipfs.dappnode:5001/webui"

api

Url to this DNP's Dappnode local HTTP API endpoint.

is optional
type: string

Example:

"http://ipfs.dappnode:5001/api/v0"

gateway

Url to this DNP's Dappnode local gateway.

is optional
type: string

Example:

"http://ipfs.dappnode:8080/ipfs"

repository

Dappnode Package's repository. Must be a publicly available url that can be handed directly to a VCS program.

is optional
type: object with the following properties:

Property	Type	Required
`type`	string	Required
`url`	string	Required
`directory`	string	Optional

type

is required
type: string
minimum length: 1 characters

Example:

"git"

url

is required
type: string
minimum length: 1 characters

Example:

"https://github.com/dappnode/DNP_IPFS.git"

bugs

Url to your project’s issue tracker.

is optional
type: object with the following properties:

Property	Type	Required
`url`	string	Required

url

is required
type: string

Example:

"https://github.com/dappnode/DNP_IPFS/issues"

license

Dappnode Package's License.

is required
type: string
minimum length: 1 characters

Example:

"GPL-3.0"

Example​

Properties reference​

name​

version​

upstreamVersion​

shortDescription​

description​

type​

chain​

mainService​

dockerTimeout​

dependencies​

requirements​

minimumDappnodeVersion​

globalEnvs​

all​

architectures​

backup​

name​

path​

service​

changelog​

warnings​

onInstall​

onUpdate​

onReset​

onRemove​

updateAlerts​

from​

to​

message​

disclaimer​

message​

style​

featuredBackground​

featuredColor​

featuredAvatarFilter​

exposable​

name​

description​

serviceName​

port​

author​

contributors​

categories​

keywords​

links​

homepage​

ui​

api​

gateway​

repository​

type​

url​

directory​

bugs​

url​

license​

Example

Properties reference

name

version

upstreamVersion

shortDescription

description

type

chain

mainService

dockerTimeout

dependencies

requirements

minimumDappnodeVersion

globalEnvs

all

architectures

backup

name

path

service

changelog

warnings

onInstall

onUpdate

onReset

onRemove

updateAlerts

from

to

message

disclaimer

message

style

featuredBackground

featuredColor

featuredAvatarFilter

exposable

name

description

serviceName

port

author

contributors

categories

keywords

links

homepage

ui

api

gateway

repository

type

url

directory

bugs

url

license