DS-Deploy

DS-Deploy is a command line deployment tool that is much faster and more reliable for most hosts than the previous tool that is built into DesktopServer v3.8.1.

This is a command line tool that allows you to take an “archive” file created with DesktopServer and deploy it to a hosted WordPress install. If you’re not too familiar with using the DesktopServer Command Line Interface (DS-CLI), don’t worry. The goal of this document is to walk you through the steps of using the tool and deploying a locally hosted WordPress install to your live server.

(1) DesktopServer Plugin
First, there are a couple of prerequisites. The Deploy tool needs to have the most recent version of the DesktopServer Plugin installed on the site that you are deploying to. So if it’s not already installed, you should perform this step first. This plugin is freely available in the WordPress repository To do this, you can log in to the admin on your WordPress site that you are deploying to and go to the Plugins page. From here, click on the “Add New” button and enter “DesktopServer” as the plugin to search for. Find the “DesktopServer” plugin in the search results and then click on the “Install Now” button to install it. Follow the prompts and then activate the plugin.

If you already have the DesktopServer plugin installed, you will need to check that it is the most recent version. The Deploy tool requires version 1.6 or greater to work. If you have an older version installed just click on the “Upgrade Now” link and upgrade to the latest.

(2) Permalink Settings
Next is to check that the site you are deploying to has Permalinks set correctly. Go to the Settings -> Permalinks settings page. You need to select one of the settings besides “Plain”. Any of the other selections, or the Custom Structure will work. This setting will be overwritten with the settings selected in your local install that you are deploying to the site, so you don’t need to worry about selecting the wrong thing or changing it after the deployment. Just make sure it’s not set to “Plain.” Click on the “Save Changes” button at the bottom of the page.

That’s all you need to do on the live host that you are deploying to. From here on out, we’ll be doing the work on your local install within the DesktopServer application or on the command line.

(3) Create Archive
The next step is to create the archive file that you will be deploying. This is a .zip file containing all of your WordPress files, including your theme and plugins, as well as a copy of the database of your local install.

(3.1) To do this, use the DesktopServer application, selecting the “Export, import or share a website” option in the Main UI and then clicking on the “Next >” button.

(3.2) From here, you can select the “Export or deploy a WordPress website” option and then click on the “Next >” button

(3.4) The next step is to select the local site that you are going to deploy, and the domain name that it is being deployed to. In the example below, we’re selecting the “sample.dev” site -- that’s the local DesktopServer install that we want to deploy. And we’re telling it that we are deploying to a “sample.com” domain. Of course, here you will be filling in the domain name of your live install and not ‘sample.com’. Once these selections are made, ensure that the “Export to a website archive (.zip file).” option is selected and click on the “Next >” button.

(3.5) The next panel is a bit more complicated and may take a little bit of practice. Here, you will fill in the form fields with the Document Root and database credentials. If you’re not sure of these values and you have already installed the DesktopServer plugin on the host, then you can select the “Fetch live hosting server details” checkbox and enter your admin username and password and it will go find this information for you and fill in the fields.

If you do not have the DesktopServer plugin installed, you can still fill out all of the fields yourself. It just might take a bit of practice.

Probably the most difficult field will be the DOCUMENT_ROOT value. This is different for each host, and can also change depending on whether or not you have WordPress installed in a subdirectory or an “add-on” domain.

Many times, this looks something like:

/home/{account_name}/public_html

Where {account_name} is the main login that you use to get to your host’s Control Panel. Sometimes a host will use /htdocs instead of /public_html.

If WordPress is installed on an add-on domain, it may look like:

/home/{account_name}/public_html/sample.com.


You will have to determine what this is for your host, or use the DesktopServer plugin to automatically obtain this information.

The other fields are much easier. They are the database name, database user and database password -- the same values that the WordPress Installer needed when you first set up your WordPress site. If you’re not sure of these values, you can use your FTP client and take a look at your wp-config.php file. Inside there, you’ll see some lines that look like:

define('DB_NAME', '{yourdbname}');

Where you see the {yourdbname} -- that’s your database name (without the quotes or the braces) and is the value that should be entered for that field.

Another will look like:

define('DB_USER', '{yourdbuser}');

And that’s your database username.


Find the other values for DB_PASSWORD and DB_HOST and you’re all set. When all the fields have been entered, click on the “Next >” button.

(3.6) This next panel will ask you for the name of the archive file to create and where to place it in your local filesystem. Since we’re creating an archive for “sample.com”, the file name will be filled in as “sample.com.zip” and it will be placed in your Websites directory. If you want to place the file somewhere else, here’s your chance to set that.

The other questions on this panel are:

Encourage search engine visibility -- If checked, this will “uncheck” the “Discourage search engines from indexing this site” in the Settings -> Reading configuration page. Since this is going to be a live site, we want the search engines to index it, so will leave this checkbox checked. But you can change this if you’re not quite ready to have the search engines indexing your live site.

Purge post and page revisions -- during local development, if you’ve created an post or page revisions while working on your new content, this is where you can have these removed before “going live.”

Customize scrubbing options. -- this allows you to select some more options to be used in scrubbing the database. This process changes all of your local domain references (sample.dev) to the live domain references (sample.com) wherever they may be found within the database. If you need to make some adjustments here, you can select this. In most cases, this is not necessary. But some plugins and themes may need this.

Click the “Next >” button when you are ready to continue.

(3.7) If you selected the “Customize scrubbing options” checkbox, another panel will be displayed allowing you to add some new selections to the scrubbing list. In most cases, this will not be necessary as the change from “sample.dev” to “sample.com” is all that is required. But if you need other changes made then this is where you can enter those values.

When you have all of these options set the way you need them, click on the “Next >” button and the archive file you selected will be created.

(3.8) The final panel shows you the steps as it’s performing each action and looks like this:

Now you have your archive file that you can deploy with the DesktopServer Command Line tool.

(4) Start the DS-CLI session

You’ll need to start a DS-CLI session from your WordPress admin. This will start the terminal session with all of the DesktopServer Command Line tools set up and ready for your use. This is done by clicking on the “DS-CLI” link in the admin bar as shown here, indicated with the red arrow:

Once the terminal window appears, it will look like this and you’ll be ready to enter in the command to start the deploy process.

The text displayed in white is what you will be typing in. A complete explanation of what all this means can be found below.

(5) Deploy the Archive
The command line tool for performing deployments has several parameters. Because of this, we’ve built a handy tool that will help you in creating this. It can be found here: https://serverpress.com/ds-deploy-form/

If you fill in all of the fields on that form with the appropriate values, it will show you a command that you can just copy and paste into the DS-CLI terminal window.

The Deploy command looks like the following:

ds-deploy 'protocol://user:pass@sample.com[:port]/[directory]'

-archive {archive.zip} -wphost http://www.sample.com

-wpuser {wpusername} -wppass '{wppassword}'

ds-deploy:This is the name of the DesktopServer Deploy tool. It is automatically installed with the latest version of DesktopServer v3.8.2.

protocol:The protocol to use for sending files to the host. This can be either ‘ftp’ for FTP connections or ‘sftp’ for SFTP connections.

user:The FTP/SFTP username to use for connecting to the host.

password:The FTP/SFTP password to use for connecting to the host.

domain.com:The FTP/SFTP domain to connect to. This is often prefixed with ‘ftp.’ for FTP connections, such as ftp.sample.com. For SFTP connections it can be the same as the domain name or different, depending on how your host has set up SFTP.


port:Optional port number override. FTP usually uses port 21 and SFTP uses port 22. However, some hosts change these for security reasons. If that’s the case, you can specify the correct port to use here.

directory:This is the optional directory prefix to use for file uploads and need to point to where (S)FTP will find your WordPress install. The default directory is the root directory (/) but this may not be correct for all hosting environments. The exact value depends on how (S)FTP is set up on your account, how your account is set up (the user’s default directory) and whether or not you are installing WordPress in a subdomain or on an add-on domain. Sometimes, this is /public_html or /htdocs. If you’re installing to an add-on domain, it might require the domain name as well, as in /public_html/sample.com. If you’re unsure, you can use your FTP client to connect to your server and see where it shows the files.


In the following image, we’re logged in with a root account and the directory that the WordPress files are in is /home/cda92250846747/html - you can see the files for the WordPress install. So this is the value that is needed for the ‘directory’ part of the command for this host and FTP account.

One final note on directories: Many web hosts today use Unix-based (Linux, etc.) web servers. Unix file systems are case-sensitive. When determining the directory name, take special care that you maintain the upper and lower case letters, otherwise the deployment will fail.

-archive:The -archive parameter tells the Deploy tool that you’re specifying the archive file name to be deployed. Following the -archive is the file name of the archive. In the examples here we’re using sample.com.zip, so you would use -archive sample.com.zip. If the archive file is not in the current directory, you can prefix the file name with the full path the the archive file location, as in -archive /home/user/sample.com.zip.

-wphost:The URL to the WordPress install. This should include the www. prefix if your site is set up that way. So, for deploying to our sample.com domain you would use -wphost http://sample.com. If your WordPress install is using an https connection you need to specify that instead of http.

-wpuser:This specifies the WordPress username on the host to authenticate with. If your user name is “deployadmin”, you would specify the username as -wpuser deployadmin.

-wppass:This is the password for the WordPress user. If your password is something like Secure!29passw#rd, you would specify this with -wpuser 'Secure!29passw#rd'.

-debug:This parameter will instruct the Deploy tool to output additional information that can be helpful in debugging problems. If you need to contact ServerPress for assistance, using this parameter will give us the additional information we need to help.


-verbose:This parameter displays additional, non debugging information and may also be helpful in tracking down problems.

A note about passwords: All security experts will tell you to use long passwords that contain a mixture of letters, numbers and special characters. This is very good advice, but it can cause problems when entering these as command line parameters. Many special characters have specific meanings to the Bash command line parser. Because of this, we recommend putting single quotes around the password.

Using single quotes will work for most passwords, unless the password itself contains a single quote. In this case you need to do some really confusing which involves single and double quoting. For example, if your password is Security'(Minded you can use the following to safely use this on the command line: -wppass 'Security'"'"'(Minded'. Initially this looks confusing, but what’s happening is the first part of the password is enclosed in single quotes: 'Security' and that’s followed by a single quote enclosed in double quotes: "'" and then it’s followed with the rest of the password, again enclosed in single quotes: '(Minded'. The Bash command line parser will just put these three parts together since there are no spaces between them and the combined parts make up your super-secure passwords that have special characters. This same single and double quoting trick needs to be used for both the (s)FTP password and the WordPress password if they contain a single quote character.

So putting all of the above parts together, the complete Deploy command for our sample site is as follows:

ds-deploy 'ftp://user:pa'"'"'ss@ftp.sample.com:21/htdocs/sample.com/'

-archive /home/user/sample.com.zip -wphost http://www.sample.com

-wpuser deployadmin -wppass 'Secure!29passw#rd' -debug -verbose >sampledebug.txt


This is specifying an FTP connection using port 21 to ftp.sample.com with the FTP account of user and a password of pa'ss. The WordPress install is located at www.sample.com in the directory /htdocs/sample.com (because it’s an add-on domain) and the WordPress username is deployadmin with a password of Secure!29passw#rd. This command is also specifying the -debug and -verbose parameters to provide additional information. And finally, it is “piping” the output from the Deploy tool into a file called sampledebug.txt. This text file can be sent to our support team if you need help.

And then the Deploy tool starts doing it’s work. Depending on the size of the site you are deploying, and if there are any files already in place on the host server, this can take quite a while. This is because all the files need to be uploaded and the files in some directories on the remote server need to be removed in order to make the hosted environment match the local environment that you are deploying.