I'm not sure proposals like this are warranted, so please let me know if not. This is born out of the observation (and some frustration ;-) that various dokku plugins take different (and somewhat conflicting) approaches in both naming convention, command syntax and functionality.

Goal

Facilitate an ecosystem of dokku plugins that provide attached services that follow a common pattern in building such plugins, their use cases and a common command syntax. This is intended as a minimum level.

Rationale

Currently there seem to be different ways for attached services. Some prefer to attach a service to a single app by default, while the dokku-link plugin allows one service to be linked to multiple apps. Also there are various ways for service plugins to name their environment variables.

This is to propose a standard for attached services, as follows. Ammendments, feedback and proposals welcome.

Definition

1. A service is a dokku-plugin that, upon plugin installation, builds a base image to run the service in its own container.
2. A service can be linked to any number of dokku apps, but it can also be created without any app specified (deferred linking).
3. When linked, the service is to expose its connection URL to app containers as a single environment variable that follows this dokku-args standard: -e <SERVICE>_URL=<service>://<user>:<password>@<ip>[/<path>], where service is the service name (e.g. MYSQL, RABBITMQ etc.), user/password the access credentials or tokens, ip the linked container's address, and the optional path any further information required.
4. Services can expose further name-spaced env variables via dokku-args or dokku's config:set command, e.g. -e <SERVICE>_SOMEVAR=some-value. Such variables are to be documented in the plugin's README for easy reference
5. Upon startup of the service container, the plugin creates a credentials file in $DOKKU_ROOT/.$SERVICE/credentials
6. Upon link of a service to an app, the plugin uses dokku-link to create the link
7. Upon removal of a service link from an app, the plugin uses dokku-link to remove the link
8. A service maintains its persistent data (if any) in $DOKKU_ROOT/.$SERVICE/volume, which it maps in its container as /var/$SERVICE. Such volumes are to be recorded in $DOKKU_ROOT/.$SERVICE/volumes
9. A service offers import and export commands to allow users to import/export service state (e.g. backup of persistent data or configuration).
10. A service can be cloned. Cloning means to create a new service that exactly matches the specification of the old service, and copies all data (i.e. does :export , followed by :import >`.

Common command syntax

<service>:create <name> [<options>] => create the service, no link to an app. options are optional and service-specific
<service>:link <name> <app> => link the service to an app
<service>:unlink <name> <app> => unlink the service from an app
<service>:delete> <name> => if there are no links left, delete the service and stop its container
<service>:export <name> => return a the export filename that can be used by import (URL?)
<service>:import <name> <file> => import file into the service (deleting all previous data first)
<service>:logs <name> => print the most recent log(s) for this service
<service>:restart <name> => graceful shutdown and restart of the service container. graceful means it will only work if no other containers/apps are currently using the service.
<service>:info <name> => print the connection information
<service>:list => list all services of this type
<service>:clone <existing-name> <new-name> [config | data | both] => shortcut for :create the service new-name by copying the config (default), the data (do :export , then :import ), or both from the existing service . The new service shall not be linked to any apps.
<service>:expose <name> port => expose the service on port. By default a service does not publicly expose any ports and can only be access via docker links.

Benefits

• attached services follow a common pattern that is simple and effective, making it easier for users to build upon the respective plugins.
• makes it easier to implement services as you don't have to re-invent the wheel
• by specifically using the docker link facilities services become first class citizen in the docker and dokku universes (like apps).

Acknowledgment

This is meant as a constructive first step, and very much in appreciation of all those who have provided service plugins. In particular this is inspired and builds upon the fine work done by the authors of dokku-redis, dokku-mysql, dokku-rabbitmq and dokku-link.

Updates

• added :clone syntax
• added :expose syntax as patrickjahn suggested