# SSHKit

[![Build Status](](
[![Inline docs](](

SSHKit is an Elixir toolkit for performing tasks on one or more servers,
built on top of Erlang’s SSH application.

[Documentation for SSHKit is available online](

## Usage (work in progress)

SSHKit is designed to enable server task automation in a structured and
repeatable way, e.g. in the context of deployment tools:

hosts = ["", {"", port: 2222}]

context =
  |> SSHKit.path("/var/www/phx")
  |> SSHKit.user("deploy")
  |> SSHKit.umask("022")
  |> SSHKit.env(%{"NODE_ENV" => "production"})

:ok = SSHKit.upload(context, ".", recursive: true)
:ok =, "yarn install")

The [`SSHKit`]( module documentation has
more guidance and examples for the DSL.

If you need more control, take a look at the
[`SSHKit.SSH`]( and
[`SSHKit.SCP`]( modules.

## Installation

You can use SSHKit in your projects in two steps:

1. Add `sshkit` to your `mix.exs` dependencies:

  def deps do
    [{:sshkit, "~> 0.0.3"}]

2. List `sshkit` in your application dependencies:

  def application do
    [applications: [:sshkit]]

## Modules

SSHKit consists of three core modules:

1. [**`SSHKit.SSH`**]( provides
   convenience functions for working with SSH connections and for executing
   commands on remote hosts.

2. [**`SSHKit.SCP`**]( provides
   convenience functions for transferring files or entire directory trees to
   or from a remote host via SCP. It is built on top of `SSHKit.SSH`.

3. [**`SSHKit`**]( provides the main API
   for automating tasks on remote hosts in a structured way. It uses both `SSH`
   and `SCP` to implement its functionality.

Additional modules, e.g. for custom client key handling, are available as
separate packages:

* [**`ssh_client_key_api`**]( An Elixir implementation for the Erlang `ssh_client_key_api` behavior, to make it easier to specify SSH keys and `known_hosts` files independently of any particular user's home directory.

## Testing

As usual, to run all tests, use:

mix test

Apart from unit tests, we also have
[functional tests](
These check SSHKit functionality against real SSH server implementations
running inside Docker containers. Therefore, you need to have
[Docker]( installed.

All functional tests are tagged as such. Hence, if you wish to skip them:

mix test --exclude functional

Hint: We've found functional tests to run significantly faster with
[Docker Machine]( compared to
[Docker for Mac]( on OS X.

## Contributing

We welcome everyone to contribute to SSHKit and help us tackle existing issues!

Use the [issue tracker][issues] for bug reports or feature requests.
Open a [pull request][pulls] when you are ready to contribute.

If you are planning to contribute documentation, please check
[the best practices for writing documentation][writing-docs].

## License

SSHKit source code is released under the MIT License.
Check the [LICENSE](LICENSE) file for more information.