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¶

Options¶

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¶

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¶

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.