Deployer is an npm package dealing with replacing the image of a service in a remote docker swarm using local docker images. This is achieved by running a local docker registry. The local machine builds and pushes the images to that registry and the remote machine pulls and deploys them using an ssh reverse tunnel.
Version 2 enables the functionality in a multi-node environment. This is done by running a docker registry as a service in the swarm, which allows all nodes to access the newly pulled image.
- Docker must be installed on local machine.
- Established ssh connection between remote host and local machine (authorized_keys).
cat ~/.ssh/<YOUR_KEY>.pub | ssh <YOUR_USER>@<YOUR_HOST> "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"- An existing docker swarm on the remote machine that contains the services which deployer will update with new images.
Use the node package manager npm to install deployer.
npm install -g https://github.com/backslashbuild/deployerDeployer requires a local docker registry to be running which can be created by running deployer registry start. Deployer must be used in conjuction with a config file describing the build command as well as image and service names. By default the script looks for deployer.yml at cwd and if not found, recursively looks in parent directories. Alternatively, a path to another yml file can be specified using the -f option.
services:
hello-world1:
serviceName: stack_hello-world1
imageName: tutum/hello-world
build: docker pull tutum/hello-world --quiet
my-hello:
serviceName: stack_my-hello
#imageName: my-hello --- imageName defaults to the key but can be overwritten
build: docker-compose -f docker-compose.yml build my-hello- "serviceName": The name of the service as it appears on the swarm.
- "build": The command used to build the image.
- "imageName": The name of the image used to update the remote service. This key is optional. If omitted it defaults to the name of the service. In the example below, for "hello-world2" service, "imageName" will take the value "hello-world2".
-q, --quiet Suppresses verbose output. Sets log-level to 1.
-l, --log-level Sets the log-level to provided level. Accepts numerical value between
0-7 or one of the choices.
[choices: "OFF", "FATAL", "ERROR", "WARN", "INFO", "DEBUG", "TRACE", "ALL"]
--help Show help.
--version Show version number.
--check-updates Sets whether the command should check for updates before executing.
Deployer uses global configuration, stored at ~/.deployer/config.json. Deployer comes with a default set of values configuration all of which can be changed using deployer config set and can be reset to default using deployer config unset. The config can be reset to default using deployer config reset.
{
"name": "deployer",
"logLevel": "INFO",
"checkForUpdates": true
}- "name": A string that may contain alphanumeric characters and "-" which is used when deployer tags images. It is advised that a meaningful
nameis set to enable communication in a team environment. - "logLevel" A numerical value between 0-7 or a string representing a log level. Available options are:
OFF,FATAL,ERROR,WARNING,INFO,DEBUG,TRACE,ALL. - "checkForUpdates" A flag to choose whether deployer should check for updates.
Resets the deployer config to default values.
Updates the deployer config <key> to provided <value>.
key - The key of the config to be updated
value - The value to be stored in the key
Resets the deployer config <key>.
key - The key of the config to be reset
When deployer updates the image of a service, it also sets a label on the service with metadata related to the deploy in a stringified JSON format. Running deployer inspect prints the metadata stored in the service label.
{
"date": "2021-09-05T21:31:32.000Z",
"deployerVersion": "2.2.0",
"name": "deployer",
"computerUsername": "Vasilis",
"deviceName": "LAPTOP-SD9J03UG",
"operatingSystem": {
"type": "Windows_NT",
"platform": "win32",
"architecture": "x64",
"release": "10.0.19043"
},
"image": "deployer/hello-world1:latest"
}Inspects deployer metadata of remote service.
To operate using deployer, it is required to have a locally running docker registry. Deployer provides CLI to assist in creation and maintenance of that registry. A registry can be started by running docker registry start. The registry container is configured to automatically start at startup to enable immediate use of Deployer. The registry can removed and have its resources cleaned up by running deployer registry stop.
Starts up deployer local registry.
-p --port - The port the registry should listen on. Default: 20000
Removes local deployer registry and cleans up its resources.
This is deployer's core functionality, named to match the convention of docker-compose up, which replaces the image of one or more services on the remote docker swarm with a locally built image.
Replaces the image of one or service which is deployed on <host> using the configuration specified in the config file. A config file is required to run this command. <service> serves as a key of the config file to lookup build and service configurations. More than one services can be passed as arguments to the function and they will be deployed in parallel. If the --file option which specifies an exact path is not defined, Deployer will look for "deployer.yml" in the current directory and in the case of miss recursively in the parent directories.
host - The ssh target. For example "user@example.com"
service - The name of a key from deployer.yaml. Using example deployer.yaml provided above: "my-hello"
services - Additional deployer.yaml keys to be deployed in parallel
deployer up user@example.com my-hello hello-world1 -q
-f --file - Path to the config file. Default: "deployer.yml"