This section explains the basics for creating a new functionality that will show up in nextcloudpi-config and ncp-web.

See also how to use the development environment.

Anatomy of a ncp-app

An ncp configuration option, such as nc-datadir, is defined by a single bash .sh file in /usr/local/etc/ncp-config.d.

In order to be launched from the web interface, it needs a permission mask 660 and ownership root:www-data

chown -R root:www-data /usr/local/etc/ncp-config.d
chmod 660 /usr/local/etc/ncp-config.d/*


It needs to define two functions called install() and configure(), and optionally another one called cleanup().

  • The install() function is called during the build process and also during ncp-update if it hasn’t been installed before.
  • The configure() function is called when
    • launched from ncp-web,or ncp-config
    • during installation ( during build, or from ncp-update ) if it has a field ACTIVE_=yes
  • The cleanup() function is only called at the end of the image building process, to leave the system as clean as possible after installation. Optional.

Public fields

“Fields” that will show up in ncp-web and nextcloudpi-config for the user to modify are only bash variables with a special name. If a variable ends in underscore _, then it will be modifiable by the user. The original value will be left as a suggestion or default.

For instance, the top of the ‘nc-backup-auto’ option shows the following variables

DESCRIPTION="Periodic backups"

And looks like this


Special fields

There’s some fields fields that have a special behavior

  • DESCRIPTION is used to show a little explanation in the webUI or TUI and is a mandatory field.
  • ACTIVE_ will show a ✓ next to the option when it has the value yes. Optional.
  • INFO will display the contents of this string in the interface. Used to provide some additional information such as warnings and instructions. Optional.
  • INFOTITLE header for the INFO box. Defaults to “Info” if it is not provided. Optional.

Also, any field that reads yes or no will be displayed as a checkbox in the web interface.

Code style

Please, check for style and common mistakes by running shellcheck on your script before submitting.

shellcheck -s bash myscript.sh