Hosting with FTP
FTP is the most common way to connect a website to Surreal CMS. Almost every web host offers it, and if you've ever uploaded your website with an app like Transmit or FileZilla, you already have everything you need. This page walks you through finding your credentials, connecting your website, and fixing the problems people run into most often.
FTP, FTPS, and SFTP aren't the same thing
Plain FTP sends your password and your files without encryption. FTP with TLS/SSL, also called FTPS, is the same protocol over an encrypted connection. SFTP is a different protocol that runs over SSH, and it has its own guide. If your host supports FTPS or SFTP, use one of those instead of plain FTP.
Before you start
All of the following need to be true before you begin:
- You have a web hosting account that offers FTP access.
- Your website's files are already on the server and your website loads in a browser.
-
You know which folder on the server holds your homepage. Hosts often name it
public_html,www, orhtdocs.
1. Find your FTP credentials
Your web host provides these, usually in your hosting control panel or in the welcome email you received when you signed up. You need four things:
| Host | The server's hostname, e.g. ftp.example.com. This can also be an IP address. |
|---|---|
| Port |
Almost always 21. You only need this if your host tells you to use a different one.
|
| Username | Your FTP username. On some hosts this includes your domain, e.g. user@example.com. |
| Password | Your FTP password. This isn't always the same as the password you use to log in to your hosting account. |
Ask your host whether the server supports FTP with TLS/SSL. If it does, use it.
Consider a dedicated FTP account
Many hosting control panels let you create additional FTP accounts that are limited to a single folder. Creating one just for Surreal CMS, limited to your website's folder, means you can change or revoke it later without affecting anything else.
2. Test your credentials
This step is optional, but it saves time. Open an FTP client such as Transmit, FileZilla, WinSCP, or Cyberduck and connect with the credentials from the previous step. If it works there, you know the credentials are good, and you can see exactly which folder your homepage lives in.
3. Connect your website to Surreal CMS
Log in to Surreal CMS, then select New Site on the Sites page. Choose FTP or FTP with TLS/SSL 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 | FTP with TLS/SSL if your host supports it, otherwise FTP. |
| Host |
Your FTP server's hostname or IP address, e.g. ftp.example.com. Don't include
ftp://.
|
| Port | Leave this blank to use port 21, or enter the port your host gave you. |
| Username | Your FTP username. |
| Password | Your FTP password. |
| Home Folder |
The folder that contains your homepage. Use the Browse button to navigate to it. 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 FTP settings, these details will help.
| IP address |
Connections come from 162.243.9.115. If your host restricts FTP access by IP address, add
this one to the allowlist.
|
|---|---|
| Transfer mode | Passive mode only. Active mode isn't supported, so your server has to allow passive connections, including through its firewall. |
| Encryption |
FTP with TLS/SSL uses explicit TLS, which starts on the regular FTP port and upgrades to an
encrypted connection. Implicit FTPS, the legacy variant that usually runs on port
990, isn't supported. Your server needs to support TLS 1.2 or newer.
|
| Connections | One file is transferred at a time. SFTP transfers several at once, so it's noticeably faster when you're working with a lot of files. |
| Timeout | The server has 10 seconds to respond before the connection is abandoned. |
Troubleshooting
| Unable to authenticate with your server |
The server rejected your username or password. Try the same credentials in an FTP client. If they fail
there too, reset the password with your host. Also check whether your host expects the full username,
such as user@example.com.
|
|---|---|
| Unable to connect to your website |
We couldn't reach the server. Check the host and port, make sure you didn't include
ftp:// in the host, and ask your host whether a firewall is blocking
162.243.9.115. If you chose FTP with TLS/SSL, confirm that the server
supports explicit TLS and TLS 1.2 or newer. If it doesn't, use SFTP if it's available, or
plain FTP as a last resort.
|
| Unable to list the directory on your server | You logged in, but the file listing failed. This usually means passive mode connections are being blocked. Ask your host to confirm that passive FTP is enabled and that its passive port range is open in the firewall. |
| The Browse button doesn't show your website's folder | Many FTP accounts are locked to a specific folder, so the top level you see in Surreal CMS is whatever folder your account is locked to. If that folder already is your website's folder, leave the home folder blank. |
| 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. Compare the folder in an FTP client with what you see in a browser. If the folder is correct, your host or a CDN may be caching the old page. |
| Unable to upload the file to your server | Your FTP user doesn't have permission to write to that file or folder, or your hosting account is out of disk space. Your host can fix the permissions for you. |
Checklist
- Your FTP host, port, username, and password, confirmed in an FTP client
- FTP with TLS/SSL selected if your host supports it
- Passive mode allowed by your server, and
162.243.9.115allowed through any firewall - 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!