Start development services from templates
Go to file
Chris df3e1211af Misc fixes, templates 2024-03-02 17:10:30 +01:00
bin Renamed serverctl to server 2022-09-28 01:12:53 +02:00
registry Misc fixes, templates 2024-03-02 17:10:30 +01:00
src Misc fixes, templates 2024-03-02 17:10:30 +01:00
.gitignore Initial commit 2022-09-27 12:29:56 +02:00 Added option to show env and ports in find command 2022-09-28 13:36:54 +02:00
LICENSE Improvements and fixes 2022-09-28 01:11:14 +02:00 Implemented .serverenvs file support 2022-10-14 22:43:21 +02:00
composer.json Renamed serverctl to server 2022-09-28 01:12:53 +02:00
composer.lock Initial commit 2022-09-27 12:29:56 +02:00

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.


  • 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


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/"

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:




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": {

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 brd 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