Draft dokku service spec

gistfile1.txt

Currently there seem to be different ways for attached services. Some prefer to attach a service (e.g. rabbitmq) 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.

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 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 <service>:export <old>, followed by <service>:import <new>>`.

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>` => remove the service forcefully (kill the 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>:delete> <name>` => if there are no links left, delete the service and stop its container
`<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.

Benefits:
- attached services follow a common pattern that is simple and effective
- makes it easier to implement services as you don't have to re-invent the wheel