Standalone on Windows

How to setup & use Snake CI on Windows.

Snake Runner can be installed and started on Windows hosts since 0.9.0.

Download

Snake Runner is distributed as binary releases and is available on the official Releases page: Snake Runner Binary Releases

  • Create a directory on your Windows machine, let’s say C:\snake-runner\.
  • Download the executable from the Releases page and place it into C:\snake-runner\.
  • Rename the executable to snake-runner.exe for your convienience.

Configure

Snake Runner itself has a few requirements to work properly on Windows without using Docker:

  • git — for cloning Git repositories from Bitbucket
  • ssh-agent and ssh-add — for providing SSH access to Bitbucket while cloning Git repositories & fetching dependencies of projects

You can get all required programs by installing Git BASH from the official website on your Windows machine.

  • Create a configuration file C:\ProgramData\snake-runner\config\snake-runner.conf and put the following contents in there:
    master_address: "https://address-of-your-bitbucket-instance/"
    registration_token: "the registration token for Snake Runner"
    

    Replace the placeholders with the following parameters:

    • The URL of Bitbucket Server with the Snake CI add-on installed.
    • The registration token, which can be found in Bitbucket Admin PanelSnake CIRunners.

There are two executors available for Windows: the Shell executor and the Docker executor.

  • The Docker executor creates Docker containers and starts pipelines & jobs in the containers.
  • The Shell executor creates system processes on the windows machine without using any isolation.

Using Shell Executor

Snake Runner can be installed & running on pre-configured Windows machines and use PowerShell or Windows Command Line instead of using Docker containers.

While it’s very efficient in terms of cost and performance, it has downsides too — pipelines & jobs processes will have the same privileges as Snake Runner. It means that commands executed in pipelines will have the same access to the filesystem & information as Snake Runner itself.

We do not recommend running Snake Runner with this configuration on your personal computers.

To use the Shell executor specify the exec_mode configuration variable for Runner:

  • add exec_mode: "shell" into the runner’s config located in C:\ProgramData\snake-runner\config\snake-runner.conf.
  • or, specify the SNAKE_EXEC_MODE=shell environment variable while starting Snake Runner

Read more about the Runner’s config

Using Docker Executor

Snake Runner can be installed on pre-configured Windows machiens and use Docker containers for running Pipelines & Jobs. The only requirement for this is to have Docker Engine to be up and running.

Official Guide: Install Docker on Windows

It is a default behavior of Snake Runner, you don’t need to provide any additional configuration.

On the other hand, you can pass special configuration variables such as additional Docker Networks & Docker Volumes: Runner Config.

Start

This section describes how to make Snake Runner start automatically on Windows boot and start it as a Windows service.

  • Start PowerShell with Administrative Privileges (Run as Administrator)
  • Execute the following command to install Snake Runner as a Windows service:
    C:\snake-runner\snake-runner.exe service install
    
  • Start Snake Runner:
    C:\snake-runner\snake-runner.exe service start
    
  • Confirm it’s running:
    C:\snake-runner\snake-runner.exe service status
    
  • Now, the runner is up and ready to handle the workload.

Upgrade

This section describes how to upgrade Snake Runner to a new version.

  • Start PowerShell with Administrative Privileges (Run as Administrator).

  • Stop the service by executing the following command:

    Stop-Service snake-runner
    

    or

    C:\snake-runner\snake-runner.exe service stop
    
  • Copy the existing Snake Runner executable for backup purposes:

    Copy-Item -Path C:\snake-runner\snake-runner.exe -Destination C:\snake-runner\snake-runner.backup.exe
    
  • Copy a new release to C:\snake-runner\snake-runner.exe.

  • Start Snake Runner:

    C:\snake-runner\snake-runner.exe service start
    

Troubleshoot

Check the Troubleshooting page.

Last modified October 21, 2020