Nut command / Set-up / setup:deploy
Note: You are currently reading the documentation for Bolt 3.7. Looking for the documentation for Bolt 5.2 instead?
Note: The command is provided by a separate
package called bolt/simple-deploy
that is installed by default
with archive distributions. If you've installed Bolt using a different method,
it needs to manually be included with Composer project installs using
composer require bolt/simple-deploy:^1.0
.
Nut's setup:deploy
is a simple tool to deploy a build of the current site
from a local workstation to a (S)FTP enabled destination host.
To use this tool on your development machine only you can create a file
named .deploy.yml
.
Each key in the .deploy.yml
represents a deployment target that can be
uploaded to the remote destination via either FTP or SFTP (secure FTP).
Every deployment configuration you add to .deploy.yml
must set the protocol
to either ftp
or sftp
, and an options
array. It is strongly recommended to
use SFTP, if your host supports it.
Usage¶
php app/nut setup:deploy [options] <target>
Note: This command will not appear in the list
of available commands if the .deploy.yml
file is not present.
Arguments¶
Argument | Description |
---|---|
target | Name of the deployment setting to use from .deploy.yml |
Options¶
Option | Description |
---|---|
--check | Only check the connection settings for a given deployment |
--edit | Interactively create or edit a deployment configuration |
--force | Update files & permissions even if unchanged |
Example: Checking a connection¶
php app/nut setup:deploy --check production
Using this command will allow you to verify the connection and destination connections are configured correctly, before running the actual deployment. This will help prevent the accidental removal of files on the destination environment.
Example: Running a deployment¶
php app/nut setup:deploy production
This will run the actual deployment: Uploading and/or updating the files on the destination environment.
View this short screencast, to see it in action:
Configuration File¶
Configuration is done in the .deploy.yml
file in the site's root directory on
your development environment, with the following format:
staging:
protocol: ftp-or-sftp
options:
host: hostname.example.org
root: root/folder/name
username: your-username
…
The protocol
should be set as lowercase ftp
or sftp
.
Note: If your host provides SFTP, it is the preferred upload method. It is both faster and more secure than FTP alone, and supports more functionality.
SFTP Options¶
If you've set sftp
as the protocol, the following options are available.
Options¶
Key | Description |
---|---|
host | DNS host name to upload to |
root | The root directory of the remote site. Can be an absolute path, or if missing a trailing / it will be assumed to be a subdirectory of the remote user's home directory |
username | User name to login to the remote host with |
password | (optional) Password to login to the remote host with |
privateKey | (optional) Full path to private key file to for key exchange if not using password authentication |
useAgent | (optional) Set to true if using a private key, and you don't want to use the system SSH agent |
port | (optional) Port number to connect to if the target is not listening on the default |
timeout | (optional) Time in seconds to wait for a connection attempt |
hostFingerprint | (optional) The public key fingerprint of the deployment target |
NOTE: Either a password
or privateKey
must be set.
Example: Password Login¶
production:
protocol: sftp
options:
host: example.com
username: deploy
password: 'your password goes here'
root: /var/www/sites/example.com
Example: Key-Based Login¶
production:
protocol: sftp
options:
host: example.com
username: deploy
privateKey: /home/your_home_dir/.ssh/id_rsa
root: /var/www/sites/example.com
FTP Options¶
If you've set ftp
as the protocol, the following options are available.
Options¶
Key | Description |
---|---|
host | DNS host name to upload to |
root | The root directory of the remote site. Can be an absolute path, or if missing a trailing / it will be assumed to be a subdirectory of the remote user's home directory |
username | User name to login to the remote host with |
password | Password to login to the remote host with |
port | (optional) Port number to connect to if the target is not listening on the default |
ssl | (optional) Connect to the FTP target host over a secure SSL-FTP connection |
timeout | (optional) Time in seconds to wait for a connection attempt |
transferMode | (optional) The transfer mode. Must be either ASCII or BINARY |
utf8 | (optional) Set the connection to UTF-8 mode |
passive | (optional) Force FTP to use "passive" mode |
ignorePassiveAddress | (optional) Ignore the IP address returned when setting up a passive connection. Useful if a server is behind a NAT device. Requires PHP >= 5.6.18 |
Example¶
staging:
protocol: ftp
options:
host: example.com
root: my-site
username: deploy
password: 'your password goes here'
NOTE: In the above example, the root directory is a subdirectory of the
remote user's home directory called my-site/
, e.g. /home/deploy/my-site/
.
Setting Permissions¶
You can control the permissions of newly created files and directories by
adding a permissions
key under options
.
By default, Simple Deploy will set files to 0664
and directories to 0775
,
but if you need less restricted permissions (not recommended) you can set
them like:
options:
permissions:
file: 0666
dir: 0777
Of course more secure values are also possible and recommended.
Editing¶
A very simple editor is also available by adding the --edit
option to the
command.
php app/nut setup:deploy --edit <target>
Example: Editing the configuration for the "production" target¶
php app/nut setup:deploy --edit production
This will allow you to interactively review and modify the settings in your
.deploy.yml
file.
Couldn't find what you were looking for? We are happy to help you in the forum, on Slack or on Github.