serverctl/README.md

# 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

- [x] Rename from `serverctl` to `server`
- [x] Implement variables in environment section
- [x] Provide environment, ex. `${SERVER_HOST}` for docker host IP
- [x] 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
- [x] 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.

```json
{
  "$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:

```json
  "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:

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