dotnet-ssh-deploy

Deploys applications to remote hosts using SSH through the .NET CLI.

This is a re-implementation of the DotnetSshDeploy created by Yves Goergen on Github!

Installation

dotnet local tool

Install the NuGet package AMWD.SshDeploy10 to your project directory. Then you can run it from the project directory to deploy your application.

Installation:

dotnet new tool-manifest
dotnet tool install AMWD.SshDeploy10

Command invocation:

dotnet publish -c Release
dotnet ssh-deploy staging

dotnet global tool

Install the NuGet package AMWD.SshDeploy10 as a global tool. Then you can run it from all directories to publish your project. This requires the .NET 10.0 runtime to be installed.

Installation:

dotnet tool install -g AMWD.SshDeploy10

Command invocation:

ssh-deploy staging

Learn more about managing .NET tools.

Configuration

sshDeploy.json

The deployment is configured through a single file that should be placed somewhere in your project directory. This file contains all deployment profiles.

Security notice:

You don't want hackers to deploy anything to your site, do you? Because the config file contains access credentials or at least personal data, it should never be added to version control. Add it to your .gitignore file. It should also never land on your web server (it has no use there anyway). Keep this file local and give it to everybody who needs to deploy the project to your server. You might check in a template of this file that contains all public data and has placeholders for confidential data, if you like.

The file sshDeploy.json is automatically discovered in the current working directory and in its subdirectory "Properties" which is common for .NET/Visual Studio projects. If it's located somewhere else, specify its path with the -c command line option.

The JSON structure looks like this:

{
  "profiles": {
    "profilename": {
      "isDefault": true,
      "hostName": "example.com",
      "userName": "appuser",
      "keyFileName": "sshDeploy.key",
      "keyFilePassphrase": "keypassphrase",
      "localPath": "../bin/Release/net10.0/publish",
      "remotePath": "app",
      "ignoredLocalFiles": [
        "appsettings.Development.json"
      ],
      "ignoredRemoteFiles": [
        "cgi-bin/**"
      ],
      "commands": {
        "preInstall": [
          "aspnetappctl stop"
        ],
        "postInstall": [
          "aspnetappctl start"
        ]
      }
    }
  }
}

profiles

The profiles property contains a map of all profile names with their data. In this example, the profile name is "profilename". Call it "production", "staging" or whatever you want. You can add multiple of these profiles. One of them can be the default profile.

isDefault (optional)

Declares the default profile that is used when none is specified on the command line. If this option is not specified and there is no default profile, the first profile is used if there is only one.

hostName, port (optional, not shown), userName

SSH connection and login data. The port defaults to 22.

password (optional)

The plain password for SSH login.

keyFileName (optional), keyFilePassphrase (optional)

The name of the key file and, if required, its passphrase for SSH login. Key files must be in PEM format. PuTTY or OPENSSH files are not supported. The file name can contain environment variables in Windows syntax like %userprofile%/deploy.key. Non-rooted file names are evaluated relative to the config file directory. Directory separators can be backslash (\) or forward slash (/), but the forward slash is more convenient in JSON files.

Either a password or a key file must be specified.

localPath

The path to the local files to be deployed. This is usually the output directory of dotnet publish or just your project directory for other web project types. It can contain environment variables in Windows syntax like %myprojects%/projectname. Non-rooted paths are evaluated relative to the config file directory. Directory separators can be backslash (\) or forward slash (/), but the forward slash is more convenient in JSON files.

remotePath

The path on the remote server to deploy the files into. This path is relative to the home directory that you are in after SSH login.

ignoredLocalFiles (optional)

A list of names or glob patterns of local files that are not deployed.

ignoredRemoteFiles (optional)

A list of names or glob patterns of remote files that are not deleted. If ssh-deploy finds a remote file that doesn't exist locally and is not matched by this list, it asks you what to do with it. If you choose to always keep it, it is added to this list.

commands (optional)

Commands can be executed on the SSH server at different events:

commands.preUpload (optional, not shown)

A list of commands to execute on the SSH server before files are uploaded.

commands.preInstall (optional)

A list of commands to execute on the SSH server after the files are uploaded and before files are deleted and copied from the temporary upload directory. Use this to stop the web application server.

commands.postInstall (optional)

A list of commands to execute on the SSH server after the files are deleted and copied. Use this to start the web application server again.

Command Line Arguments

ssh-deploy [-c configfile] [-np] [-q] [-v] [-P <n>] [-K/-D] [profilename]

-c, --config

Specifies the configuration file to use. See above for default locations if unspecified.

-np, --no-progress

Hide upload progress. Prints normal messages but no upload progress information. Quiet mode includes this.

-q, --quiet

Quiet mode. Does not print anything except error messages and questions about what to do with remote-only files.

-v, --verbose

Verbose mode. Prints more details about what is going on. Useful for troubleshooting. This overrides quiet mode.

-P, --parallel

Set the number of parallel actions on file transfers. This can speed up the deployment process by performing multiple file operations simultaneously. The default value is 1, which means single-threaded mode.

-K, --keep

Keeps all remote files that are not present locally. No questions are asked, and no remote files are deleted. This is not compatible with -D.

-D, --delete

Deletes all remote files that are not present locally. No questions are asked, and no remote files are kept. This is not compatible with -K.

If no profile name is specified, the default or single profile is used. See the isDefault property above.

License

MIT License (see choose a license)