This is a grunt task for code sync over the ftp protocol.
These days git is not only our goto code management tool but in many cases our deployment tool as well. But there are many cases where git is not really fit for deployment:
- we deploy to servers with only ftp access
- the production code is a result of a build process producing files that we do not necessarily track with git
This is why a grunt task like this would be very useful.
By default this task uploads only modified files, checking by time stamp and file size, but it also has an option to force uploading all files.
This task also has an optional syncMode that deletes extra files and folders in destination.
This plugin requires Grunt ~0.4.0
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-ftp-sync --save-dev
and load the task:
grunt.loadNpmTasks('grunt-ftp-sync');
To use this task you will need to include the following configuration in your grunt file:
'ftp-sync': {
build: {
auth: {
host: 'server.com',
port: 21,
authKey: 'key1'
},
src: 'path/to/source/folder',
dest: '/path/to/destination/folder',
exclusions: ['path/to/source/folder/**/.DS_Store', 'path/to/source/folder/**/Thumbs.db', 'path/to/dist/tmp'],
forceVerbose : true,
forceUpload : false,
syncMode : true,
keep : ['logs']
}
}
Please note that when defining paths for sources, destinations, exclusions e.t.c they need to be defined having the root of the project as a reference point.
The parameters in our configuration are:
- host - the name or the IP address of the server we are deploying to
- port - the port that the ftp service is running on
- authPath - an optional path to a file with credentials that defaults to
.ftppass
in the project folder if not provided - authKey - a key for looking up credentials saved in a file (see next section). If no value is defined, the
host
parameter will be used - src - the source location, the local folder that we are transferring to the server
- dest - the destination location, the folder on the server we are deploying to
- destSep - optional - the path separator used on the destination location, default
/
- exclusions - an optional parameter allowing us to exclude files and folders by utilizing grunt's support for minimatch. The
matchBase
minimatch option is enabled, so.git*
would match the path/foo/bar/.gitignore
. - forceVerbose - if set to
true
forces the output verbosity. - forceUpload - if set to
true
forces the upload of all files avoiding the time stamp and file size check. - syncMode - if set to
true
deletes extra files and folders in destination. - keep - an optional parameter to keep files or folders in destination that are not present in source (only used in syncMode). It uses the grunt's support for minimatch. The
matchBase
minimatch option is enabled, so.git*
would match the path/foo/bar/.gitignore
. - destTimeAdjustmentMinutes - an optional parameter to set the time difference in minutes between the host and the remote for when the host and the remote are in different time zones. Example:
destTimeAdjustmentMinutes: -600
allows for a -10 hour time difference.
Usernames and passwords can be stored in an optional JSON file (.ftppass
in the project folder or optionaly defined inauthPath
). The credentials file should have the following format:
{
"key1": {
"username": "username1",
"password": "password1"
},
"key2": {
"username": "username2",
"password": "password2"
}
}
This way we can save as many username / password combinations as we want and look them up by the authKey
value defined in the grunt config file where the rest of the target parameters are defined.
The task prompts for credentials that are not found in the credentials file and it prompts for all credentials if a credentials file does not exist.
IMPORTANT: make sure that the credentials file uses double quotes (which is the proper JSON syntax) instead of single quotes for the names of the keys and the string values.
This task is built by taking advantage of the great work of Sergi Mansilla and his jsftp node.js module and suited for the 0.4.x branch of grunt.
- 2015-03-04 v0.2.0 Added syncMode and changed files upload
- 2015-02-04 v0.1.10 An option to force output verbosity.
- 2014-10-22 v0.1.9 Log successful uploads only in verbose mode.
- 2014-10-13 v0.1.8 Allow empty strings to be used as login details.
- 2014-09-03 v0.1.7 Restructured the code deailing with the authentication values to address some issues.
- 2014-08-20 v0.1.6 Bug fix with the modules updates.
- 2014-08-20 v0.1.5 Refresh of versions of used modules.
- 2014-07-28 v0.1.4 Added a
authPath
configuration option. - 2014-05-05 v0.1.3 Added warning if an
authKey
is provided and no.ftppass
is found. - 2013-11-22 v0.1.1 Added compatibility with
grunt
0.4.2 and switched tojsftp
1.2.x. - 2013-08-26 v0.1.0 Switched to
jsftp
1.1.x.