sftp(options)

This function returns a map-based tree of network files on a server that supports SFTP (SSH File Transfer Protocol), a standard internet protocol for transferring files. You can use this to create a network host connection to server files so you can retrieve files or publish them directly to a server from Origami.

The current state of server hosting is such that setting up an SFTP connection is generally complicated, and the instructions will vary from one hosting company to another. Most hosts that support downloading and uploading files via SFTP will document the process somewhere in their Help or Support area.

You will generally have two ways you can connect to an SFTP server:

• Using a username and password. This is easier to set up — but you will end up having to save your password in a text file on your computer.
• Using a secure cryptographic key. This is more complex but more secure.

The rest of this example will assume the use of a username and password.

Create a network connection file #

Create a new file to represent your network host, calling it host.ori or else incorporating the name of your hosting company. Copy and paste the following:

Origami.sftp({
  host: "example.com"
  password: "passwordGoesHere"
  path: "public_html"
  username: "alice"
})

Edit the text to reflect your host, password, and username. The path argument is optional; if you omit it, by default you’ll be working with the files at the top of your user account. But many web hosts typically have you store site files in a subfolder, which might be called something like httpdocs or public_html; you’ll need to check your host’s documentation.

Note: If you use a source control system like git, add this file to .gitignore. Never check passwords into source control! Because this is an Origami file, you also have the option of breaking it up into smaller pieces. You could store the password separately in a file called password.txt that is not saved in source control, then have host.ori reference that file:

Origami.sftp({
  host: "example.com"
  password: password.txt
  path: "public_html"
  username: "alice"
})

With this approach, host.ori contains no sensitive information and so is safe to check into source control.

If your using cryptographic keys, omit the password field. Origami.sftp should connect with the same keys available to you via ssh.

Test your connection #

After creating a file like host.ori to represent your SFTP host server, you can test it by using Tree.keys to list out the top level files and subfolders:

$ ori keys host.ori
assets/
posts/
feed.json
index.html
README.md

Once you’ve tested that your connection works, you can read and write files; see using the network connection.

Publish #

You can publish your site via SFTP with a command like:

$ ori "publish src/site.ori, host.ori, { manifest: 'manifest.json' }"

See Dev.publish for details.

The manifest option lets the publish operation keep track of what’s already been published before. If you have shell access to your account (see below), then you don’t need that option; Origami will be able to efficiently ask the server what files it currently has.

Shell access #

Some hosting companies that offer SFTP include full shell access so you can log into your account on their server. Other companies will give you SFTP access, but not provide a way for you to sign in.

If you do have shell access, add the following option to the sftp function call in host.ori:

  shellAccess: true

This shellAccess option:

• Lets Origami.sftp perform network operations in fewer steps.
• Enables the efficient retrieval of a manifest for the server files for use with Tree.manifest and Tree.changes. This makes the Dev.publish command be more efficient, and obviates the need for you to set a manifest option.