Hosting with SFTP
SFTP transfers files over SSH, so your password and your files are encrypted the whole way. If your web host or server offers it, it's the best choice for connecting a traditional web server to Surreal CMS. It's secure, it needs only one port, and it moves several files at once. This page walks you through finding your credentials, connecting your website, and fixing the most common problems.
SFTP isn't FTPS
The names are similar, but SFTP runs over SSH, usually on port 22, while
FTP with TLS/SSL (FTPS) is regular FTP over an encrypted connection, usually on port
21. They aren't interchangeable. If your host gave you FTP or FTPS credentials, follow
the FTP guide instead.
Before you start
All of the following need to be true before you begin:
- Your web host or server offers SFTP access. On shared hosting you may need to turn on SSH or SFTP access in your control panel first.
- You can log in with a username and password. Surreal CMS doesn't support SSH keys.
- Your website's files are already on the server and your website loads in a browser.
-
You know the path to the folder that holds your homepage, e.g.
/home/username/public_htmlor/var/www/example.com.
Password login has to be enabled
Many cloud servers ship with SSH password login turned off and only accept SSH keys. Since Surreal CMS
logs in with a password, you'll need to enable password authentication for the user you connect with.
On a server running OpenSSH, that's the PasswordAuthentication setting in
sshd_config.
1. Find your SFTP credentials
On shared hosting, these are in your hosting control panel and are often the same as your main hosting or FTP login. On your own server, they belong to a user account on that server.
| Host | The server's hostname or IP address, e.g. example.com. |
|---|---|
| Port |
Almost always 22. Some hosts use a different port for SSH, so check their documentation.
|
| Username | The user to log in as. |
| Password | That user's password. |
Running your own server?
Create a user just for Surreal CMS rather than connecting as root. Give it a strong password
and write access to your website's folder and nothing else. That way you can change or remove it
later without affecting anything else on the server.
2. Test your credentials
This step is optional, but it saves time. Open an SFTP client such as Transmit, FileZilla, WinSCP, or Cyberduck, choose SFTP, and connect with a password, not a key. If it works there, it will work in Surreal CMS. While you're connected, note the full path to the folder that holds your homepage.
3. Connect your website to Surreal CMS
Log in to Surreal CMS, then select New Site on the Sites page. Choose SFTP for the protocol and fill out the form.
| Name | The name you want to use for your website. (Only used in the CMS.) |
|---|---|
| URL | Your website's URL, e.g. https://example.com/ |
| Protocol | SFTP |
| Host |
Your server's hostname or IP address, e.g. example.com. Don't include
sftp://.
|
| Port | Leave this blank to use port 22, or enter the port your host gave you. |
| Username | Your SFTP username. |
| Password | Your SFTP password. |
| Home Folder |
The folder that contains your homepage. Use the Browse button to navigate to it. Unlike most
FTP accounts, SFTP users can often see the whole server, so this is usually a full path such as
/home/username/public_html.Important! This needs to point to the same folder as your URL. If you're creating a subsite, e.g. https://example.com/subsite, then your home folder needs to
point to the subsite folder on your server.
|
| Upload Folder |
The folder that uploaded files will be stored in. It has to be inside your home folder. Users can
upload, rename, move, and delete anything inside this folder, but nothing outside of it, so don't
select one that contains webpages or other important files. Create a folder called
uploads for this purpose. See
best practices for why.
|
Select Test Connection to make sure everything works. If all goes well, you'll see Connection successful!
How Surreal CMS connects
If you or your host manage the server's firewall or SSH settings, these details will help.
| IP address |
Connections come from 162.243.9.115. If your server restricts SSH access by IP address,
add this one to the allowlist.
|
|---|---|
| Authentication | Username and password only. SSH keys aren't supported. |
| SFTP subsystem | The SSH server has to have its SFTP subsystem enabled. It is by default on most servers, but some hardened configurations turn it off. |
| Connections | Up to 10 files are transferred at once. |
| Timeout | The server has 10 seconds to respond before the connection is abandoned. |
Troubleshooting
| Unable to authenticate with your server | The server rejected the login. Check the username and password in an SFTP client, making sure the client is using a password and not a saved key. If a key works but a password doesn't, password authentication is turned off on the server. |
|---|---|
| Unable to connect to your website |
We couldn't reach the server, it took longer than 10 seconds to respond, or its SFTP subsystem is
disabled. Check the host and port, and make sure a firewall or a tool like fail2ban isn't
blocking 162.243.9.115. Also confirm you didn't enter your FTP port by mistake. SFTP
almost never runs on port 21.
|
| Unable to list the directory on your server | The folder doesn't exist or your user isn't allowed to read it. Check the home folder's path in an SFTP client. |
| Unable to upload the file to your server |
Your user doesn't have permission to write to that file or folder, or the disk is full. This is
common when the website's files are owned by a different user, such as
root or www-data. Give the user you connect with write access to the
website's folder.
|
| Publishing succeeds but your website doesn't change | Your home folder probably doesn't match your URL, so the files are being published somewhere other than where your website is served from. Check which folder your web server uses as the document root for your domain. If the folder is correct, your server or a CDN may be caching the old page. |
Checklist
- Your SFTP host, port, username, and password, confirmed in an SFTP client using a password
- Password authentication and the SFTP subsystem enabled on the server
162.243.9.115allowed through any firewall- A user with write access to your website's folder
- A home folder that points to the same place as your website's URL
- An upload folder inside the home folder that doesn't contain webpages
Once you're connected, head back to Connecting your website to enable pages and define your first content region. If you run into trouble getting connected, feel free to contact us for help!