evgy/dockerserver repository overview

⁠DockerServer

Super lightweight & simple RESTFul stateless server for running docker⁠ containers on a remote machine(s) in a secure way.

⁠

⁠Install

npm i -g docker-server

Or

docker run -d -p 1717:1717 --restart=always --name=docker-server -v /var/run/docker.sock:/var/run/docker.sock -e "DS_TOKEN=my_secret_token" evgy/dockerserver

⁠Background

I needed to run a couple of containers on a remote machine and came to these conclusions:

• Kubernetes is an overkill !
• docker-machine is also complicated !
• I just want to run a few containers on a remote machine.

⁠Approach

Built a small REST server with NodeJS, using the express and docker-cli-js packages as a base.

⁠Design Principles

• Keep the business logic simple!
• It must be stateless!
• Docker is (a) present.

⁠Current architecture

_{The cluster diagram demonstrates a PUT request.}

⁠Notes for the Cluster Mode:

*0 - Connection between the load balancer and the docker-server.

*1 - Save the machine load to a JSON⁠ file in a shared folder (among all the machines).

PUT method

1 - Requests comes to any free (according to the load balancer) node to answer.

2 - Get the most free (according to actual cpu-mem ratio) node (from redis or the shared storage, possibly on S3).

3 - Resend the current request to that node (or process if it's the current node) and return the answer.

For the rest of the methods

Resent the current request to all the nodes and return the merged results.

⁠Usage

Install DockerServer on the machine that you want to run your containers.

DockerServer can be run for a single session with:

$ docker-server

or as a service using PM2⁠:

$ pm2 start /usr/lib/node_modules/docker-server/pm2.config.js

and if you want in addition to start it on startup just run:

$ pm2 startup

And of-course, as mentioned before, but using params, via docker itself:

$ docker run -d -p 1717:1717 --restart=always --name=docker-server -v /var/run/docker.sock:/var/run/docker.sock evgy/dockerserver docker-server --token my_secret_token

Or you can run in HTTPS mode:

(Note that in this example I'm using Let's Encrypt⁠ and I'm using readlink because these files are symbolic links)

$ docker run -d -p 443:1717 --privileged --restart=always --name=docker-server -v /var/run/docker.sock:/var/run/docker.sock -v $(readlink -f /home/user/letsencrypt/config/live/your-domain.com/cert.pem):/certs/cert.pem:ro -v $(readlink -f /home/user/letsencrypt/config/live/your-domain.com/chain.pem):/certs/chain.pem:ro -v $(readlink -f /home/user/letsencrypt/config/live/your-domain.com/privkey.pem):/certs/privkey.pem:ro evgy/dockerserver docker-server --token my_secret_token --https

_{Note: The --privileged argument is only needed in order to use the 443 port, because all ports below 1024 are reserved by root.}

Moreover, you can run in a Cluster mode when you have a couple of machines to use:

$ docker run -d -p 1717:1717 --privileged --restart=always --name=docker-server -v /var/run/docker.sock:/var/run/docker.sock -v /some/shared/folder:/my/somewhy/custom/path evgy/dockerserver docker-server --token my_secret_token --cluster --folder /my/somewhy/custom/path

Or simply:

$ docker run -d -p 1717:1717 --privileged --restart=always --name=docker-server -v /var/run/docker.sock:/var/run/docker.sock -v /some/shared/folder:/tmp/docker-server evgy/dockerserver docker-server --token my_secret_token --cluster

Note: /tmp/docker-server is the default folder so you can easily and safely run it even without docker.

Now, you can do "remote" docker operation using simple HTTP requests:

⁠Options

⁠Environment

You can set the following environment variables to configure DockerServer:

⁠Parameters

Also, you can start DockerServerwith these parameters:

⁠PUT Data

When sending the PUT request, the following parameters are supported:

⁠POST Data

When sending the POST request, the following parameters are supported:

⁠Examples

NOTE: In the examples I assumed you're using the default port.

1. Get a list of all the containers:

$ curl -X GET http://1.2.3.4:1717/ -H 'Authorization: Basic base64EncodedToken'

1. Run redis on the remote machine:

$ curl -X PUT http://1.2.3.4:1717/ -H 'Authorization: Basic base64EncodedToken' --data 'name=p-redis&image=redis&ports[1234]=6379'

And/or

$ curl -X PUT http://1.2.3.4:1717/ -H 'Authorization: Basic base64EncodedToken' --data 'name=v-redis&image=redis&volumes[/tmp/data]=/data'

1. Remove our created container(s):

$ curl -X DELETE http://1.2.3.4:1717/p-redis -H 'Authorization: Basic base64EncodedToken'

And/or

$ curl -X DELETE http://1.2.3.4:1717/v-redis -H 'Authorization: Basic base64EncodedToken'

⁠Changelog

1.9.0 - Added optional Redis⁠ support for big clusters (recommended for clusters with more than 50 workers/hosts).

1.8.9 - Fixed CVE issue with docker-cli-js v2.5.2 ==> v2.5.3 & removed package-lock.json

See full changelog⁠

⁠Roadmap

• Queue (for heavy loads)
• Autoscaling

⁠License

APACHE-2.0 (see the LICENSE files in the repository).

⁠Donate

Running dockers is free, but beer is always welcome ⁠ or directly donate to our cause ⁠