ServerCtl - Services for Developers

This is a tool to start up servers on-demand for development. It is not a tool for orchestrating container stacks or deploying sevices for production. In many cases the default configuration might be directly insecure, and should not be put online. For what it is designed for however, i.e. quickly spinning up a ready-to-roll mongodb or openldap server, it does what it is supposed to.

Todo

• Rename from serverctl to server
• Implement variables in environment section
• Provide environment, ex. ${SERVER_HOST} for docker host IP
• Add filtering to find command, to seach for tags or name
• App port binding, i.e. phpmyadmin on 9000, phpcacheadmin on 9001
• Make use of a ~/.serverenvs to override envs for instances
• Consider UDP?
• Fix the service scripts implementation

Examples

Say you need a Mongodb instance for something. Try this:

$ serverctl start mongo
Started mongo<default>
  Mongo client: 27017
$

What just happened? Well, the start command pulled and started a new container from the latest docker image using sensible defaults from the service registry.

Let's start another one:

$ serverctl start mongo --instance other --portoffset 1
Started mongo<other>
  Mongo client: 27018
$

Check it out!

$ serverctl status
Service   Instance   Ports
mongo     default    27017
          other      27018
$ serverctl stop mongo --all
Stopped mongo<default>
Stopped mongo<other>
$

Service definition

Services are defined as JSON and should be put in the registry directory, which should be located in the same directory as the executable (when using phar) or in the project root when running from source.

{
  "$type": "service",
  "name": "myservice",
  "description": "My neat service",
  "tags": [ "app", "neat" ],
  "author": "Myself <myself@domain.tld>",
  "image": "myself/myservice",
  "ports": [ 
    { "port": 1337, "info": "Neat port" },
    { "port": 1337, "info": "Neat port (UDP)", "proto": "udp" }
  ],
  "persistence": [
    { "path": "/data", "hint": "Fancy data" }
  ],
  "environment": {
    "NEAT_ENV_VAR": "useful value",
  },
  "scripts": {
    "setup": {
      "info": "Launch the neat configuration tool",
      "execute": "/app/setup.sh"
    }
  }
}

Permanently customizing instances

To customize an instance, create the file ~/.serverenvs if it doesn't exist and open in a text editor. The definitions for each instance is contained in a section named after the server and the instance name separated by a colon:

[mysql:backups]
MYSQL_ROOT_PASSWORD=something

[server:instance]
ENV_VAR=value

FAQ

Where is the data stored?

Data goes in $HOME/.var/serverctl. As volumes are generally not owned by your user, you will have to manually delete old instances.

How can I tell a container to connect to another container?

Static configuration

If you need to preconfigure a connection, use the DOCKER_HOST environment variable. It will only work in the environment section of the service config:

  "environment": {
    "FOO_SERVER": "${DOCKER_HOST}"
  }

From running container

Lookup the IP on your host. On Linux you would do something like:

$ ip addr show docker0
6: docker0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default 
...
    inet 172.17.0.1/16 brd 172.17.255.255 scope global docker0
...

Can I configure the services?

Use the find command with the -E or --environment option to find what you can override on start:

$ server find mariadb -E
$ MYSQL_ROOT_PASSWORD=foobar server start mariadb --instance uniqueid