SSH based Deployment

Sometimes using complex and modern platforms like Kubernetes, serverless systems, etc are not practical and quite painful to maintain for individual and smaller organization. Like many integrations that we provide, you can also deploy your code using SSH-based transfer.

Deployment is usually the last step of a pipeline after your code passed through various stages. Either you use your own scripting or use standard tools available in various languages like Capistrano(Ruby), Fabric(Python), Deployer(PHP), or Rsync for deploying your code. The tools mentioned use SSH protocol and deploy your code over a secure channel.

How it works¶

The SSH private key that you upload in pipeline's variables section, is injected into each workflow run and already configured with correct permissions in ~/.ssh folder. You can simply run the commands that you usually would from your laptop to deploy your application to remote servers. For example, to restart an apache server on a remote host -

$ ssh [email protected] 'sudo service apache restart'

Razorops provides first-class support for SSH-based deployment and can be easily integrated within your pipeline. Please follow the following steps -

Generate SSH credentials if you don't have any

We recommend creating a new set of keys for deployment purposes and configuring your remote system with the public key as follows -

ssh-keygen -t rsa -b 4096 -C "[email protected]"
mkdir -p ~/.ssh && touch ~/.ssh/authorized_keys && chmod -R go-rwx ~/.ssh/

nano ~/.ssh/authorized_keys

Note

SSH credentials generally include private and public key pair in various formats. We support these private key formats currently.

If you are using Putty based format (PPK) then you should convert it to PEM ( show below on this page).

Upload SSH private key in pipeline settings

Please login to the dashboard and navigate to a pipeline's variables section and click on "SSH Keys" tab. Afterward, you can upload the private key and specify the remote system FQDN or IPAddress. On successful upload, it will show the fingerprint impression of the private key.

Note

If you have a shared ssh-key for multiple servers, you might need to upload the key multiple times for each server in settings.

Run commands on remote servers

You're almost done. Now you can use your favorite tool which works over SSH to perform deployment activities. Here is an example -

rsync -avz ./dist/ $SSH_USER@$$SSH_HOST:~/dist/

If you're not using your own script, you can use various standard tools which use SSH under the hood -

Rsync/SCP¶

You can use rsync to synchronize the files from the pipeline to the remote system. rsync is already part of our Linux-VM build environment, but if you're using a custom environment or your own docker image, it's pretty trivial to install -

# Ubuntu & Debian based Docker images
sudo apt-get update && sudo apt-get install rsync

# Alpine based Docker images
apk update && apk add rsync

After you can simply transfer files using rsync or scp-

rsync -va --delete src/public/ $SSH_USER@$SSH_INSTANCE:www/public
scp -r src/public $SSH_USER@$SSH_INSTANCE:~/www/public

Capistrano (Ruby)¶

If you have a Ruby-based application, Capistrano is an excellent deployment tool to ship software to single or multi machines in one go. Please follow the official guide on how to configure your project with Capistrano. As part of the pipeline, you can trigger deployment with -

bundle install
cap install STAGES=production

Fabric (Python)¶

If you have a Python-based application, Fabric is an excellent deployment tool to ship software to single or multi machines in one go. Please follow the official guide on how to configure your project with Fabric. As part of the pipeline, you can trigger deployment with -

pip install fabric
fab deploy # uses fabfile.py

Deployer (PHP)¶

If you have a PHP-based application, Deployer is an excellent deployment tool to ship software to single or multi machines in one go. Please follow the official guide on how to configure your project with Deployer. As part of the pipeline, you can trigger deployment with -

composer require deployer/deployer
dep deploy
dep rollback # if pipeline fails

Docker and SSH¶

If you're running Docker based application and don't have sophisticated orchestration platforms like Kubernetes, Nomad, or Docker swarm, you can simply run commands on the remote system to pull the image and re-create containers -

  steps:
  - run: |
      export CONTAINER_NAME=web-app # change as per yout app
      export IMAGE=acme/web-app:v1 # change as per your app
      ssh [email protected] <<'ENDSSH'
      docker pull $IMAGE
      docker stop $CONTAINER_NAME && docker rm $CONTAINER_NAME
      docker run --name=$CONTAINER_NAME --restart=always -v $PWD:/app -d $IMAGE
      ENDSSH

Ansible¶

Ansible is an excellent tool to provision and configure your remote systems using a declarative manner over SSH protocol. You can execute ansible as part of the pipeline and ship your applications easily -

...
  steps:
  - run: |
      # Install ansible if not present in pipeline build environment
      sudo apt-get install software-properties-common
      sudo apt-add-repository ppa:ansible/ansible -y
      sudo apt-get update
      sudo apt-get install ansible

      # execute playbook
      ansible-playbook provisioning/playbook.yml

Supported SSH key format¶

We support RSA, DSA, ECDSA, OPENSSH and ED25519 key formats currently. For linux based runner, we automatically convert the newline break or feed from CRLF (\r\n) to LF (\n) for cross-platform compatibility.

Putty PPK format¶

PuTTY doesn't natively support the private key formats that we support. Before you can use Razorops to connect to your instance, you must convert your Putty private key into a .pem file or any other format that we support. You can use the PuTTYgen tool for this conversion.

For Unix/Linux, you can install PuTTY package to perform the conversion -

$ yum install putty           # RPM based
$ apt-get install putty-tools # Dpkg based (ubuntu, debian)

To convert .ppk private key to .pem format -

puttygen ppkkey.ppk -O private-openssh -o pemkey.pem

Now you can simply upload pemkey.pem to in your pipeline to access the instance from Razorops.

Troubleshooting¶

1. Error loading key "~/.ssh/SSH_PRIVATE_KEY": error in libcrypto message¶

This message can be returned if there is a formatting error with the SSH key.

When pasting the SSH key in CI/CD variable in dashboard, the value must end with a newline (LF character). To add a newline, press Enter or Return at the end of the -----END OPENSSH PRIVATE KEY----- line of the SSH key before saving the variable.