Install Skopos™

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

Download and Install Control Utility

The 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).

The skopos utility is a self-contained executable available for the following operating systems:

To download and install on Linux:

chmod +x skopos
mkdir -p ~/bin
mv skopos ~/bin

The ~/bin directory used above is writeable even without root privileges. If you have root privileges, you may prefer to install skopos in the /usr/local/bin directory instead.

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                 \
    -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

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 \

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 --restart=unless-stopped --name skopos \

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 --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 --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 --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.sock as shown above. If running it anywhere else, instead of directory-mapping docker.sock, set the DOCKER_HOST environment variable using the -e option.

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 \

Optional changes:

  • change the port 8100 if you want to use a different port on the host's network, e.g., -p 8080:8100
  • change the service name (--name skopos), especially if you want to run multiple instances of Skopos, e.g., skopos-alice, skopos-bob
  • if you want to use application/site-specific plugins or scripts, map these as well using the --mount option, 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 status and make sure there is no deployment in progress) before trying to update Skopos

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 run -wait -project demo -env /data/env.yaml /data/model.yaml

If the realpath utility 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 --interactive option after --wait in 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 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.

For example:

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 \

NOTE: (If the docker login command fails and there is an empty config.json directory in ~/.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:

   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);
       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
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 \

Next Steps

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.