Trying Raw Octopus

Published on: 28 Feb 2017 by: Robert Erez

Calamari & Mono-free deployments for your SSH targets.

Raw Scripting

If you have read some our awesome documentation, you may have come across the following simple architecture diagram.


This describes a standard Windows installation where the Octopus Server performs deployments using Calamari through an installed Tentacle which provides the communications channel. With SSH deployments, the SSH connection eliminates the need for a Tentacle so Octopus could issue commands directly to Calamari on the remote target


It seems that this is not quite far enough for some scenarios. Even the requirement to run Calamari (and its core dependency mono) is sometimes a luxury that users don't have or want. Perhaps you are trying to simply execute some script on a hardware load balancer or IOT device where you can't install mono. Perhaps mono isn't supported on that obscure Unix distro that was forked back in the 80s and where the bash shell is yet to be ported. For this reason we have for some time shipped a hidden feature called raw scripting which, through a special project variable, allows your script steps to execute directly through the opened SSH connection without any extra wrapping or bootstrapping on the part of Octopus. Combined with the new Transfer a Package step in 3.7.12, you can now deploy your apps to your Linux server without even knowing what a mono is!


We really are just opening a SSH connection and passing through your scripts as-is.

Transfer A Package

For some deployments you may simply want the package to be transferred to the remote target but not actually extracted. Perhaps it needs to be further processed through scripts or uploaded to another server. The new Transfer A Package step works in much the same way as the normal Deploy A Package step, except that the package contents aren't actually extracted, nor are any additional scripts able run as part of that step. When used in a normal deployment (non-raw), the acquisition phase can take advantage of delta compression and retention policies which then results in the package being copied to your provided destination path from its staging location. If package transfer is taking place during raw scripting, none of the above acquisition optimisations can take place (since they are performed by Calamari) and the package is instead moved from the upload staging location to the destination.

Setting It Up

Setting up your project for raw scripting is just a matter of configuring a standard SSH target and then adding the project level variable OctopusUseRawScript. This flag will only have an effect on Package Transfer and Script steps in that project.

We have included a guide in our docs outlining these short steps to deploy and run a simple packaged script without having to do any extra work on your target.

One thing that cannot be stressed enough about raw scripting is that we really are just opening a SSH connection and passing through your scripts as-is. That means you need to be aware of a few behavioural differences to typical SSH deployments:

  • Standard SSH health checks test for the presence of various dependencies such as Mono and Calamari. If the endpoints are intended to be exclusively used in raw scripting you will probably want to configure their machine policy to only perform connectivity tests to avoid their health checks failing. This is setting is now available from version 3.10.1.

  • If your default shell is not bash, your scripts will not be running in bash. Make sure you configure your login shell or write your scripts accordingly.

  • The get_octopusvariable function will no longer be available in your scripts since this is provided by a Calamari bootstrapper script. You can instead write to your script to take advantage of the variable replacement syntax (#{MyVariable}) which will be replaced before it is passed to and invoked by the remote target. This obviously excludes environment variables which can only be resolved on the remote target itself.

  • The set_outputvariable and new_artifact functions are also not available. Since Octopus Deploy will still be listening for and respond to these service messages, you can get around this by writing these service messages yourself. Check out the bootstrapping script in the Calamari source code for details.

Go Raw

Ultimately this feature exists to provide a mechanism for a those users who cannot install the elements that Octopus needs to run Calamari on their SSH endpoints. While we could provide additional support for raw scripting on Windows machines (which would default to running in a PowerShell session, sans-Calamari) we figured this was a scenario that would be unlikely to be needed given the existing unavoidable requirement to install and run the whole Tentacle Service. For those of who you who do have a need for this (or just want a slimmer, quicker deployment experience on SSH), we encourage you to give it a go and let us know where you think there is room for improvement.