Hosting with WebDAV
WebDAV is an extension of HTTP that lets apps read and write files on a web server. It's less common than FTP or SFTP, but it's handy when those aren't available, because it runs over the same ports your website already uses. This page walks you through finding your WebDAV URL, connecting your website, and fixing the most common problems.
Have a choice? Use SFTP
WebDAV servers vary a lot in how they're configured, which makes them harder to troubleshoot. If your host also offers SFTP, that's usually the simpler option.
Before you start
All of the following need to be true before you begin:
- Your web host or server has WebDAV enabled. Some control panels have their own name for it. cPanel calls it Web Disk.
- The WebDAV URL is served over HTTPS with a valid certificate.
- You can log in with a username and password using HTTP Basic authentication.
- Your website's files are already on the server and your website loads in a browser.
Use HTTPS
Surreal CMS logs in to WebDAV servers with Basic authentication, which sends your password with every
request. Over plain http:// that password isn't encrypted, so always use an
https:// WebDAV URL. Digest authentication isn't supported.
1. Find your WebDAV URL and credentials
Unlike FTP and SFTP, WebDAV doesn't use a separate host and port. Everything is part of one URL. Your host provides it along with a username and password.
| WebDAV URL |
The full address of the WebDAV server, e.g. https://example.com/ or
https://example.com/webdav/. If the server uses a nonstandard port, it's part of the
URL, e.g. https://example.com:2078/.
|
|---|---|
| Username | Your WebDAV username. |
| Password | Your WebDAV password. |
If your host uses cPanel, look for Web Disk. cPanel serves Web Disk over SSL on port
2078 and without SSL on port 2077, so use the 2078 address.
2. Test your credentials
This step is optional, but it saves time. Open a client that supports WebDAV, such as Transmit, WinSCP, or Cyberduck, and connect with the URL and credentials from the previous step. Make sure you can see your website's files, and note which folder holds your homepage.
3. Connect your website to Surreal CMS
Log in to Surreal CMS, then select New Site on the Sites page. Choose WebDAV for the protocol and fill out the form. Notice that there's no port field for WebDAV.
| Name | The name you want to use for your website. (Only used in the CMS.) |
|---|---|
| URL |
Your website's public URL, e.g. https://example.com/. This is the address visitors
use, which isn't necessarily the same as your WebDAV URL.
|
| Protocol | WebDAV |
| Host |
Your full WebDAV URL, including https:// and the port if there is one, e.g.
https://example.com:2078/.Important! If you leave off the scheme, http:// is added for you, which
isn't what you want. Always type https:// yourself.
|
| Username | Your WebDAV username. |
| Password | Your WebDAV password. |
| Home Folder |
The folder that contains your homepage, relative to your WebDAV URL. Use the
Browse button to navigate to it. Important! This needs to point to the same folder as your website's 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 WebDAV server, these details will help.
| IP address |
Connections come from 162.243.9.115. If your server restricts access by IP address, add
this one to the allowlist.
|
|---|---|
| Authentication | HTTP Basic authentication with a username and password. |
| Methods |
The server has to allow PROPFIND, GET, PUT, MKCOL,
MOVE, and DELETE.
|
| Connections | Up to 10 files are transferred at once. |
Using nginx?
The WebDAV module that ships with nginx only handles PUT, DELETE,
MKCOL, COPY, and MOVE. Surreal CMS needs PROPFIND to
list your files, so that module isn't enough on its own. See the
nginx documentation
for details.
Using PHP or another server-side language?
Surreal CMS needs to download each page's source. If your WebDAV URL is the same address that runs your scripts, the server will run the script and send back its output instead. Static HTML files aren't affected. For everything else, your WebDAV URL needs to serve files without executing them. The Apache documentation shows one way to set that up.
Troubleshooting
| Unable to authenticate with your server | The server rejected your username or password. Try the same credentials in a WebDAV client. If they work there but not in Surreal CMS, the server may only accept Digest authentication. Ask your host to allow Basic authentication over HTTPS. |
|---|---|
| Unable to connect to your website |
We couldn't get a response from the WebDAV URL. Check the host for typos, make sure it starts
with https:// and includes the port if your server uses one, and confirm the
server's certificate is valid and hasn't expired. Also make sure a firewall isn't
blocking 162.243.9.115.
|
| Unable to list the directory on your server |
The server answered, but it wouldn't list files. Either WebDAV isn't enabled at that URL,
the server doesn't allow PROPFIND, or the folder doesn't exist. Try the exact
same URL in a WebDAV client.
|
| Unable to upload the file to your server |
The server refused the PUT request. The web server's user usually needs write
permission on your website's files and folders, and some servers limit how large an upload can
be.
|
| Pages open with the wrong content | If you see the rendered page instead of its source code, such as missing PHP tags, your WebDAV URL is executing scripts. See the note about server-side languages above. |
| 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. If the folder is correct, your server or a CDN may be caching the old page. |
Checklist
- A WebDAV URL that starts with
https://and has a valid certificate - A username and password that work with Basic authentication, confirmed in a WebDAV client
-
PROPFIND,GET,PUT,MKCOL,MOVE, andDELETEallowed by the server 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!