Docksal > Docksal Fin > Addons

Addons

In addition to the custom commands, it is possible to extend fin further with addons per project or per host. Addons are community submitted commands and can be found in the Docksal Addons Repository. In order to use addons, fin version 1.7.0 or higher is required.

Installing to Project

Installing an addon can be as simple executing the addon command within the project that the addon should be added for.

fin addon install <name>

Fin will first look for the addon in the ~/.docksal/addons directory. If it is not located there, then it will attempt to search the Docksal Addons Repository.

Removing from Project

To remove an addon run:

fin addon remove <name>

Current List of Addons

Here is a list of already created addons that can help extend functionality for your project.

Name	Description	Requirements
example	A working documentation on what is Docksal addon and how it works
adminer	Adminer database management tool	MySQL
codeclimate	CodeClimate code quality tool
mailhog	Mailhog e-mail capture service for current project
phpunit	Creates a phpunit.xml file and runs PHPUnit tests	Drupal
pma	PhpMyAdmin database management tool	MySQL
redis	Add Redis to current project
sequelpro	Launches SequelPro with the connection information for current project.	macOS
solr	Apache Solr search service for current project
uli	Generate one time login url for current site	Drupal

NOTE: This list may not be up to date. To see a more comprehensive list consult the Docksal Addons Repository.

Creating Addons

To create an addon the following example can be followed.

Other than that, the bare minimum is necessary.

A folder that is the name of your addon. Careful when choosing a name. Make sure it is a machine readable name using only letters, numbers, dashes, and underscores. All other characters should be avoided.
Next, create a file within that addon folder that is the same name as the addon. This is where the base of the addon command will live. Example if my addon’s name was example, my folder structure would look like example/example.

#!/usr/bin/env bash

VERSION="1.0"

## Example addon
##
## This is an example addon. It's purpose is to show sample folder structure
## and concepts of creating addons.
##
##   fin example <command>
##
## Usage:
##   hello      Say Hello!
##   version     Display addon version


case "$1" in
	hello)
		echo "Hello!"
		;;
	version|-v)
		echo "$VERSION"
		;;
	*)
		fin help example
		;;
esac

Lastly, if you want to include more than a single script file, create a file that is the same name as the addon with the extension .filelist at the end of it. For example, if the addon’s name was example, the file name would be example/example.filelist. This file will contain any additional files within the addon folder that should be included at the time of install.

# If you want to include more than a single script file,
# you do it by creating addon.filelist file
# where all additional files should be described.
# One line per file, paths relative to current folder.

# Here is additional files
some-additional-files/somefile

# If you want to use hooks they should also be included here
# or they won't get downloaded and executed
example.pre-install
example.post-install
example.pre-uninstall
example.post-uninstall

Install Hooks for an Addon

When adding or removing an addon, it can contain a set of pre and post commands that will be executed. Example use cases would be to add/remove a service to the projects docksal.yml. Each use case will vary but they are available for use if necessary. For instance, an addon named example that needs to execute a process before it is installed would be be located in the file named example/example.pre-install. This file should also be included within the example/example.filelist file as noted above.

Phase	Process	File Extension
Before	Install	`.pre-install`
After	Install	`.post-install`
Before	Uninstall	`.pre-uninstall`
After	Uninstall	`.post-install`