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

- [ ] Add a --temporary option to start to remove volume after stop
- [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
- [ ] Consider UDP?

## 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>
$
```


## FAQ

### Where is the data stored?

* Data goes in `$HOME/.var/serverctl`

### 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
```