Home / Documentation / Administrator Guide / Deployment / SFTP Server

SFTP Server

Introduction

SFTP (Secure File Transfer Protocol) transfers files over SSH. It is commonly available on shared hosting, managed servers, and VPS environments where direct filesystem access from WordPress is not possible.

The SFTP Server deployment method deploys your static WordPress site to a remote SFTP target directory.

This deployment method supports:

  • Deployment to an SFTP server;
  • Support for SSH key authentication;
  • Password-based authentication;
  • A configurable target directory on the remote server;
  • Metadata-backed cleanup of files previously deployed by Staatic.

Preparation

Before setting up the SFTP deployment method, follow these steps to ensure you’re ready for deployment.

1. Ensure SFTP access

First, ensure you have SFTP access to the target server. This typically requires:

  • The hostname or IP address of the server.
  • A valid username and password or SSH key for authentication.

If you’re unsure about these details, contact your hosting provider or server administrator to ensure SFTP access is enabled.

2. Set up SSH keys (optional)

For enhanced security, we recommend using SSH key-based authentication instead of a password. To set up SSH keys:

  1. Generate a key pair: On your local machine, use ssh-keygen to generate a new SSH key pair if you don’t already have one.
  2. Copy the public key: Provide the server administrator with your public key (id_rsa.pub), or manually upload it to the server under ~/.ssh/authorized_keys.
  3. Secure the private key: Keep the private key (id_rsa) safe. You’ll need it for configuring Staatic’s SFTP deployment.

Note: If you use SSH key-based authentication, you can leave the password field empty during configuration.

Configuration

To configure the SFTP Server deployment method, follow these steps in the WordPress admin interface.

  1. Go to Staatic > Settings > Deployment.
  2. Select SFTP Server from the list of deployment methods.
  3. Enter the following details as described below.

SFTP Server

Host

Enter the hostname or IP address of the SFTP server. This is the server where your static site will be deployed.

Example: sftp.example.com or 192.168.1.1

Port

Enter the port number for the SFTP connection. The default SFTP port is 22, but your server may use a different port.

Example: 22

Target Directory

Specify the path to the directory on the SFTP server where the static version of your WordPress site should be deployed. Ensure this directory exists and is writable by the configured SFTP user.

Staatic also needs to create, rename, and delete metadata dotfiles in this directory. Check host restrictions if your SFTP environment blocks files such as .staatic_meta.json.

Example: /var/www/my-static-site/

Authentication

You can authenticate with the SFTP server using either a password or SSH key. For better security, we recommend using an SSH key.

Staatic stores the password, private SSH key, and SSH key password encrypted. If both a password and SSH key are configured, Staatic uses the SSH key.

Username

Enter the username that you use to log in to the SFTP server. This is required for both password and SSH key authentication.

Password

If you’re using password-based authentication, enter the password associated with the SFTP user account here. If you’re using an SSH key instead, leave this field blank.

SSH Key

To authenticate using an SSH key, upload the private SSH key file here. The public key must already be uploaded to the server for authentication.

Note: If you are not using SSH key authentication, leave this field empty.

SSH Key Password

If your private SSH key is password-protected, enter the passphrase here to unlock the key. This field can be left empty if your key does not require a passphrase.

Network

Timeout

Set the maximum number of seconds to wait for an SFTP command to execute before timing out. This setting can help prevent connection failures due to slow server responses.

By default, Timeout is set to 10 seconds.

Example: 30 (seconds)

How Deployment Sync Works

SFTP deployments use a metadata file named .staatic_meta.json in the target directory. Staatic uses this file to remember which remote files were deployed previously and which content hash each file had.

During deployment Staatic:

Step Behavior
Read metadata If .staatic_meta.json exists, Staatic uses it as the previous deployment state.
Upload files New and changed files are uploaded to the target directory.
Keep unchanged files Files with the same content hash are marked as already deployed.
Delete stale files Files from the previous Staatic metadata that are no longer in the build are removed.
Write metadata A new .staatic_meta.json file is written for the next deployment.

Staatic does not scan the entire remote directory looking for unrelated files to delete. Files that were not recorded in .staatic_meta.json are left alone. Do not remove this metadata file if you want Staatic to clean up files from earlier SFTP deployments.

The SFTP user must be allowed to create temporary metadata files, rename them, and remove old metadata files. If dotfiles or rename operations are blocked by the host, deployment cleanup can fail even when normal file uploads work.

Troubleshooting

While deploying via SFTP is generally straightforward, some common issues may arise during the process.

Handling connection issues

If you experience connection failures or timeouts during deployment, consider the following troubleshooting steps:

  1. Check server access: Verify that the hostname, port, and credentials (username, password, or SSH key) are correct. Also, ensure that your IP address isn’t blocked by the server firewall.
  2. Increase timeout: If the deployment is timing out, try increasing the Timeout setting in the configuration. A slow or busy server may require more time to process commands.
  3. Check the target directory: Confirm that the directory exists and that the SFTP user can create, overwrite, and delete files inside it.
  4. Ensure correct SSH key: If you are using SSH key-based authentication, ensure that the correct public key is installed on the server, and the private key is correctly uploaded to the Staatic configuration.
  5. SFTP server logs: Review the logs on your SFTP server for any clues related to authentication failures or file transfer issues.

By following these steps, you should be able to resolve most SFTP-related issues and ensure a successful deployment.