Skopos is packaged as a Docker container for easy deployment and upgrade. The container includes the Skopos engine, all standard plugins and the control utility.
Skopos has been tested with Docker versions 1.13 and 17.06
Use the following steps to install and start Skopos.
Get Docker Image
docker pull opsani/skopos:edge
Download and Install Control Utility
skopos utility is used to load a deploy model into the Skopos engine.
It can also be used as an alternative to the web-based user interface to control a deploy
via command line (i.e. start/stop/pause, etc.). The utility can be installed on the same host as the
engine or any other host (static binary).
skopos utility is a self-contained executable available for the following operating systems:
- Linux: https://s3.amazonaws.com/get-skopos/edge/linux/skopos
- OS X: https://s3.amazonaws.com/get-skopos/edge/darwin/skopos
- Windows: https://s3.amazonaws.com/get-skopos/edge/windows/skopos.exe
To download and install on Linux:
wget https://s3.amazonaws.com/get-skopos/edge/linux/skopos chmod +x skopos mkdir -p ~/bin mv skopos ~/bin
~/bindirectory used above is writeable even without root privileges. If you have root privileges, you may prefer to install
Alternate Location For Control Utility
If the download locations above are not convenient, or you need the control utility for an older version of Skopos, you may extract it from the Skopos container itself.
mkdir -p ~/bin rm -rf ~/bin/skopos touch ~/bin/skopos docker run \ --rm \ -v ~/bin/skopos:/skopos/bin/skopos \ --entrypoint "/bin/bash" \ opsani/skopos:edge \ -c 'cp -a engine /skopos/bin/skopos'
Once extracted, the
skopos utility can be run as any user and does not
require Docker or the container image.
Start the Skopos Engine
Security Warning: Some of the following commands start the Skopos engine as an HTTP server or an HTTPS server which operates with a secure connection, but without authentication and is suitable only for use on networks that are not exposed to the public Internet. Exposing the Skopos API/UI directly to an untrusted network opens a significant security risk, as the Skopos plans contain names of executable files and can invoke, for example, an arbitrary container from Docker Hub or another accessible registry. If you intend to access Skopos remotely, make sure that a safe tunnel/channel is arranged or run authentication and encryption in front of it (NOTE SSL alone is not sufficient); do not expose the Skopos API port to a public or other untrusted network. See the Running Skopos Securely guide for information on setting up Skopos to operate securely over public networks
Starting Skopos on Docker
To start Skopos with defaults and expose it to host port 8100 (all interfaces) with access to docker's socket:
docker run -d -p 8100:8100 --restart=unless-stopped --name skopos \ -v /var/run/docker.sock:/var/run/docker.sock \ opsani/skopos:edge
A variant of the above, but listening only on the local loopback interface (this is safer, but requires using an ssh tunnel to access the GUI):
docker run -d -p 127.0.0.1:8100:8100 --restart=unless-stopped --name skopos \ opsani/skopos:edge
To start Skopos with host networking and specifying a different server port for Skopos:
docker run -d --net=host --restart=unless-stopped --name skopos \ opsani/skopos:edge --bind localhost:8080
To start Skopos also with a custom scripts (and plugins) directory:
docker run -d --net=host --restart=unless-stopped --name skopos \ -v ~/example-twotier-app/skopos-ec2/scripts:/skopos/user/bin/ \ opsani/skopos:edge --bind localhost:8080
To start Skopos so you can use host's Docker service:
docker run -d --net=host --restart=unless-stopped --name skopos \ -v /var/run/docker.sock:/var/run/docker.sock \ -v ~/example-twotier-app/skopos-ec2/scripts:/skopos/user/bin/ \ opsani/skopos:edge --bind localhost:8080
Starting Skopos on Docker Swarm as a plain container
You can use the simple container
docker run commands above.
Note: when running Skopos with Docker Swarm, it is best to start it on the manager node and pass the
docker.sockas shown above. If running it anywhere else, instead of directory-mapping
docker.sock, set the
DOCKER_HOSTenvironment variable using the
To access the Skopos logs, use
docker logs -f skopos
Starting Skopos on Docker Swarm as a service
You can start Skopos as a service, which will give you the additional benefits of (a) simplified updates and (b) automatic migration to the new leader swarm node should the initial one fail.
docker service create --name skopos --constraint 'node.role == manager' \ --mount type=bind,source=/var/run/docker.sock,destination=/var/run/docker.sock \ --publish 8100:8100 \ opsani/skopos:edge
- change the port
8100if you want to use a different port on the host's network, e.g.,
- change the service name (
--name skopos), especially if you want to run multiple instances of Skopos, e.g.,
- if you want to use application/site-specific plugins or scripts, map these as well using the
--mountoption, making sure they will be available to Skopos
If there is a new version of Skopos, you can upgrade your existing running instance by running the following command:
docker service update skopos
If a new version is available, Docker will shut down the current Skopos instance, fetch the new image and start a brand new instance with the same configuration. Note that you will have to re-load the environment and model.
Of course, make sure Skopos is not currently running a deployment (run
skopos -bind :8100 statusand make sure there is no deployment in progress) before trying to update Skopos
Starting Skopos on Kubernetes
To start Skopos on a Kubernetes cluster:
- download the following file:
kubectl apply -f skopos-k8s.yaml
This will expose the Skopos service on a NodePort 32100 on your cluster. You
can modify the
skopos-k8s.yaml file to adjust the service type (e.g., load
balancer), port number and specific Skopos image (
:edge is the default).
Transient (Dynamic) Deployments
It is possible to run Skopos as a transient container that exists only for the duration of the deploy process and disappears right away after that - it acts as a single shell command executed synchronously. Such transient deployments do not require the Skopos engine (server) to be already running.
If you have installed the
skopos command line utility, the easiest way to execute a transient deployment is to use the
--transient option with the
skopos run or
skopos stack deploy commands. See the CLI reference for transient deployments.
If you have not installed the
skopos utility, it is possible to execute a transient deployment directly with
docker run, e.g.:
docker run --rm -ti -p 8100:8100 \ -v /var/run/docker.sock:/var/run/docker.sock -v `realpath .`:/data/ \ opsani/skopos:edge run -wait -project demo -env /data/env.yaml /data/model.yaml
realpathutility is not installed or you want to provide a path to a directory other than the current working directory, replace `realpath .` with the absolute path to the directory where the model and environment reside. If they come from different directories, you can mount multiple volumes and refer to their in-container paths.
If you want Skopos to automatically pause on deployment error, add the
--waitin the command above.
If you don't need to access the web user interface or need to control the deployment process, you can simplify the command by removing the port mapping and bind options:
docker run --rm -ti \ -v /var/run/docker.sock:/var/run/docker.sock -v `realpath .`:/data/ \ opsani/skopos:edge run -wait -project demo -env /data/env.yaml /data/model.yaml
Private Docker Registries
If you deploy images that come from private docker images, you need to give Skopos access to the Docker config file that holds credentials to your repositories. Doing so would allow Skopos to pass the credentials when calling the Docker API.
To do so, start Skopos with your docker config file mapped into the container namespace. This should be done on a node that has the authentication credentials for all repositories that you need access to already stored in ~/.docker/config.json - ensure that you have ran
docker login for each one than needs login.
docker run -d --restart=unless-stopped --name skopos \ -v /var/run/docker.sock:/var/run/docker.sock \ -v ~/.docker/config.json:/skopos/docker/config.json \ opsani/skopos:edge
NOTE: (If the
docker logincommand fails and there is an empty
~/.docker, remove the empty directory and try logging in again.)
NOTE: When running on a Docker swarm cluster, both the login and the Skopos start command should be executed on a swarm manager node.
Using Docker Registries without SSL and with Self-signed Certificate
If your private Docker registry has been set up to run without SSL or you have SSL but want to skip the certificate validation, the Skopos plugin configuration should be modified to allow it to fall back to insecure access (SSL with no certificate verification and plain HTTP). To do this, add the following to your environment file:
plugin_config: docker: # set to the plugin name that is to access Docker registries insecure_registries: true # (repeat for any other plugin you're using that works with Docker registries: # docker, docker-swarm, ec2-asg, etc); docker-swarm: insecure_registries: true # ...
If you have a private registry that runs SSL with a self-signed certificate (or any certificate that is not verifiable against the well-known root CA bundle from Mozilla), but want to keep secure access and certificate verification enabled, you can add your self-signed certificate or custom CA certificate to the bundle used by Skopos, making it a trusted certificate. The easiest way to do this is to make a copy of the Skopos image with the added certificate, so it can be used multiple times to start a new Skopos container. Place your signing CA certificate, (or self-signed cert, if that is what you use) without the private key into and empty directory under the name ca.pem and create a Dockerfile with the following contents in the same directory:
FROM opsani/skopos:edge COPY ca.pem /etc/ssl/certs/extra-registry-certfile.pem RUN cat /etc/ssl/certs/extra-registry-certfile.pem >>/etc/ssl/certs/ca-certificates.crt ; c_rehash
Now, the updated image can be created (change the image tag as desired, you can even tag it with your registry name and push it to that registry for later use on other hosts):
docker build --tag opsani/skopos:mycert .
Use the new image to start the customized Skopos with the extra certificate:
docker run -d -v /var/run/docker.sock:/var/run/docker.sock [... other options... ] opsani/skopos:mycert
It is also possible to prepare the cert files needed and map them into the container, without building a new image. Note that one of the required files is a link with a name that depends on your certificate's contents, so the command line for starting the Skopos container is not trivial to create.
# Create a new cert bundle, note this assumes you have a current version of openssl # and the Mozilla CA certificates packages (ca-certificates) installed. # This needs to be done only once (or updated rarely, if the default cert bundle changes) cat /etc/ssl/certs/ca-certificates.crt ca.pem >ca-certificates.crt # find the hash of your certificate hash=`openssl x509 -in ca.pem -subject_hash -noout` # start Skopos (add other Docker options, as needed) docker run -d --restart=unless-stopped --name skopos \ -v /var/run/docker.sock:/var/run/docker.sock \ -v $PWD/ca.pem /etc/ssl/certs/$hash.0 \ -v $PWD/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt \ -v ~/.docker/config.json:/skopos/docker/config.json \ opsani/skopos:edge
Now that you have Skopos installed and running you may want to check out the Skopos concepts user guide which covers application models, deployment environments and deployment plans.