Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/freaker2k7/dockerserver
Super lightweight & simple RESTFul distributed server for running docker containers on a remote machine(s).
https://github.com/freaker2k7/dockerserver
Last synced: 16 days ago
JSON representation
Super lightweight & simple RESTFul distributed server for running docker containers on a remote machine(s).
- Host: GitHub
- URL: https://github.com/freaker2k7/dockerserver
- Owner: freaker2k7
- License: apache-2.0
- Created: 2019-07-20T16:57:53.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-06-21T14:16:57.000Z (over 1 year ago)
- Last Synced: 2024-09-21T10:27:21.267Z (about 2 months ago)
- Language: JavaScript
- Homepage: https://dockerserver.io/
- Size: 127 KB
- Stars: 41
- Watchers: 6
- Forks: 4
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# DockerServer
Super lightweight & simple RESTFul stateless server for running [docker](https://docker.com/ "docker") containers on a remote machine(s) in a secure way.
[](https://badge.fury.io/js/docker-server)
[](https://www.npmjs.com/package/docker-server)
[](https://www.npmjs.com/package/docker-server)
[](https://gitter.im/freaker2k7-dockerserver/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
[](https://lgtm.com/projects/g/freaker2k7/dockerserver/alerts/)
[](https://lgtm.com/projects/g/freaker2k7/dockerserver/context:javascript)
[](https://scrutinizer-ci.com/g/freaker2k7/dockerserver/?branch=master)
[](https://opensource.org/licenses/Apache-2.0)
[](https://bundlephobia.com/result?p=docker-server)
[](https://github.com/freaker2k7/dockerserver)
[](https://ci.appveyor.com/project/freaker2k7/dockerserver/branch/master)
[](https://beerpay.io/freaker2k7/dockerserver)
[](https://liberapay.com/evgy/)
[](https://github.com/freaker2k7/dockerserver/stargazers/)
[](https://snyk.io//test/github/freaker2k7/dockerserver)
## 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](https://json.org "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](https://pm2.keymetrics.io/ "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](https://letsencrypt.org/ "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:
HTTP Method
Endpoint
Desc.
Docker cmd
HEAD
/:id*
Pull an image
docker pull :id
GET
/
List all the containers
docker ps -a
GET
/:id
Show the logs of a specific container
docker logs :id
PUT
/
Run a container
docker run...
POST
/:id
Execute a command in a container
docker exec...
DELETE
/:id
Delete a container with such a name or an ID
docker rm -f :id
## Options
### Environment
You can set the following environment variables to configure DockerServer:
Environment Var.
Desc.
Default
DS_PORT
The port on which the DockerServer is running
1717
DS_TOKEN
The secret token for the authorization
xxxxxx
### Parameters
Also, you can start DockerServerwith these parameters:
Param
Desc.
Default
--port [num]
The port on which the DockerServer is running
1717
--token [string]
The secret token for the authorization
xxxxxx
--low_burst [num]
Max number of requests per minute for Low burst.
60
--mid_burst [num]
Max number of requests per minute for Mid burst.
180
--high_burst [num]
Max number of requests per minute for High burst.
300
--https
Enable HTTPS mode.
For this you must have the following files:
a. /certs/cert.pem
b. /certs/privkey.pem
c. /certs/chain.pem (optional, to support self-signed certs)
false
--cluster
Enable Cluster mode.
false
--refresh_rate [num]
Milliseconds between writes to the shared memory
30000
--cache_interval [num]
Milliseconds to cache reads of all the machines
3000
--folder [path]
Shared folder between all docker-servers. (Used only in cluster mode)
/tmp/docker-server
--redis [hostname]
Shared redis server hostname.
If set, the `--folder` param. becomes the key prefix (default: "DSC:")
null
--db_port [num]
Shared server port number.
6379
--s3 [bucket-name]
S3 bucket name, use with high refresh_rate.
If set, the `--folder` param. becomes the Key.
null
--log_lovel [option]
Log level [trace|debug|info|warn|error|fatal]
info
--log_expiry [num]
Time for a log to live in days.
14
--log_max_size [num]
Max log size in MB
25
--help
Show he
--version
Show current version
### PUT Data
When sending the PUT request, the following parameters are supported:
Param
Desc.
Default
Docker cmd
image
The image for the run. (required)
null
name
The name of the container.
uuid4()
--name
remove
Flag to remove the container when it finishes --rm
false
--rm
detach
Flag to detach the container -d
false
-d
ports
Map of ports to publish.
null
-p
volumes
Map of volumes to mount.
null
-v
data
CMD to run inside the container.
null
### POST Data
When sending the POST request, the following parameters are supported:
Param
Desc.
Default
Docker cmd
tty
Flag to enable TTY mode
false
-t
interactive
Flag to enable interactive mode
false
-i
data
CMD to run inside the container
null
## 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'`
2. 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'`
3. 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](https://redis.io) 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](https://github.com/freaker2k7/dockerserver/blob/master/CHANGELOG.md)
## 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
