You may want to target your deployment for non-windows machines where you don't have the ability to run a full Tentacle. In cases such as this, a SSH Target is the next best thing.
In the standard-model the Octopus server talks to the Tentacle (ignoring the distinction between between Polling and Listening) who in turn delegates the actual deployment work to Calamari, which contains all the information regarding conventions and deployments. Calamari then executes the scripts and the Tentacle passes back to the Server the task progress, logs and artifacts.
As of Octopus Deploy 3.0, Calamari can now also run on mono and therefore any Unix-like OS that supports mono. In this set up the Octopus Server will communicate via SSH and execute bash scripts to invoke Calamari in much the same way that would be done by a Tentacle.
The great thing about this approach is that by using effectively the same Calamari code base, it should continue to have almost complete feature parity!
We support any Unix-like OS that can run mono, and we currently run automated tests against the following platforms:
Centos 7.2 + Mono 4.4.2
Debian 8.4 + Mono 4.4.2
Fedora 23 + Mono 4.4.2
FreeBSD 10.3 + Mono 4.6.2
openSUSE 13.2 + Mono 4.6.0
Redhat 7 + Mono 4.4.2
SUSE LES 12 SP1 + Mono 4.6.0
Ubuntu 12.02 LTS + Mono 3.12.1
Ubuntu 14.04 LTS + Mono 4.0.5
Ubuntu 16.04 LTS + Mono 4.6.1
We generally expect deployments with Octopus to work with practically any distribution so long as a few key prerequisites are met. Of course, if you notice it failing on some other popular distribution then please drop us a line.
To use this feature there are the following requirements:
- It must be accessible using SSH and SFTP
$HOMEenvironment variable must be available
bash3+ is available at
/bin/bash. (It does not need to be the user’s default shell.)
mono-complete3.10+ is available (you can find instructions on how to install mono on the related mono docs page).
taris available - for unpacking calamari
base64is available - for encoding/decoding variables
grepis available - Everyone needs grep!
The health check that takes places once you configure the target should check for these requirements and let you know if any dependencies are missing.
Getting just the right naming pattern is a tricky balance. In an effort to keep some similarity with the Windows based Tentacle, we have gone with the following approach:
The root directory for all Octopus work is
$HOME/.octopus and all packages are deployed to a relative location similar to that done by a normal Tentacle at
Calamari is also copied across by the deployment if a new version is detected and extracted to
By making all paths relative to the user's home directory, you can then theoretically use the same physical machine with multiple user accounts acting as separate targets. The Octopus server can then treat each machine\user as a separate SSH endpoint which will update Calamari and deploy independently of each other.
As we are just using Calamari directly, essentially the same steps are taken as a standard Tentacle Agents whenever a deployment takes place with a few key differences due to the missing Tentacle layer.
The package and any supporting deployment files are uploaded via SFTP.
Before any processing is begun we do an initial check to ensure the available Calamari executable on the endpoint is up to date with the server. If not we push up the latest Calamari package and then recommence the task. The Calamari package is sent as a
.tar.gz so it can be extracted with minimal dependencies. This obviously means the server needs to be able to un-tar that package however this should be available by default in most distros.
Leveraging Calamari means that the deployment can obtain the package via the same methods as a normal Tentacle; either pushed from the server or directly from a NuGet repository. There is therefore no bottleneck in acquisition if there are multiple SSH endpoints all trying to retrieve the same package independently.
The vast majority of Octopus features are supported, with the exception of IIS steps and Windows services. To support windows services under Mono, we suggest using mono-service.
As yet we do not support running PowerShell scripts on Linux, either on their own as a script task, or as pre-deploy/deploy/post-deploy steps. We do however support running bash scripts on SSH endpoints. Conversely, bash is not yet supported on normal Windows Tentacles, even with Cygwin available.
The deployment process will check for scripts either provided in the deployment step itself or embedded in the package, looking for
PostDeploy.sh (names are case-sensitive). If these scripts are found, Calamari will then execute their contents at the appropriate time. Again an interesting side-effect of using Calamari on mono is that any C# or F# scripts should continue to function just like with normal Tentacles. Keep in mind the platform differences such as file paths or separators, line breaks, environment variables and security considerations.
The same variables that are accessible to PowerShell scripts are available to the bash scripts, albeit using a different syntax. All scripts that run are wrapped inside bootstrapping code that provides access to getting/setting variables and the ability to designate build artifacts.
Getting access to a variable involves invoking a function named
get_octopusvariable. For example, to echo out the installation directory call
echo "Installed to step: " $(get_octopusvariable "Octopus.Action[Acme Deployment].Output.Package.InstallationDirectoryPath")
Setting a variable:
set_octopusvariable RandomNumber 3
which results in the server retrieving that file, at the end of that step. Keep in mind that this means the file must be accessible over SFTP using the same credentials as that used during execution.
Although there is no Tentacle involved with SSH endpoints there are still some useful metrics that are used to determine its health in regards to its ability to perform deployments. It is the absence of any dependencies (i.e. mono, tar) that deems the endpoint unhealthy (in addition to the typical checks of inability to even connect using the provided credentials) while an absence or out-of-date version of Calamari is considered only a warning as this will be updated when its required by a task.
Note that due to the Tentacle being effectively a “virtual Tentacle” running on the server itself, if the endpoint is healthy it will indicate in the health logs that the running version is the same as the server version.