Documentation

Connecting your website

Surreal CMS connects to your website to read and write files. When you make changes, everything gets published directly back to your server in real-time.

This page will walk you through creating a new website and connecting it to Surreal CMS. If you don't have an account yet, you can sign up here for free.


Creating your website

If you don't have a website yet, you'll need to create one first. If you already have a website, feel free to skip ahead.

There are a lot of great apps you can use to create your website with, or you can code it by hand if that's your thing. You can also search online for a template. You'll find a lot of free and premium options out there.

The important thing is that you use an HTML template and not one that's designed for a specific app such as WordPress.

Try the demo

Just want to try things out? Feel free to kick the tires on our demo site. Just look for the Kumo demo in the dashboard after you create your account.


Hosting your website

Once you have your website design, it's time to upload the files to the Internet. Follow the instructions provided by your web hosting company. Most provide FTP or SFTP access to transfer files to and from your server. Make sure you keep those credentials nearby, because you'll need them again later.

If you need an FTP client to transfer files, here are some options:

Step-by-step hosting guides

We have a guide for each way Surreal CMS can connect to your server: FTP and FTPS, SFTP, WebDAV, Amazon S3 & CloudFront, Cloudflare R2, and DigitalOcean Spaces.

Once your website is online, you're ready to connect it to Surreal CMS!


Connecting to Surreal CMS

Now that your website is online, log in to your Surreal CMS account (or create a new one). You'll be taken to the Sites page after you log in.

On the Sites page, select New Site. You'll see the following form.

Screenshot of the New Site form, with the name, URL, type of website, and protocol filled in. Screenshot of the New Site form, with the name, URL, type of website, and protocol filled in.

Whoa, that's a big form! Don't worry, I'll walk you through it.

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/
Type of Website Commercial or non-commercial. Non-commercial websites are free. See website classifications.
Protocol How we should connect to your website: FTP, FTP with TLS/SSL, SFTP, WebDAV, Amazon S3, Cloudflare R2, or DigitalOcean Spaces. (Ask your webhost if you're not sure.)
Host Your server's hostname. If your website is https://example.com, the host will usually be example.com. This can also be an IP address.
Port The port we should use to connect to your server. You can leave this blank unless you've configured your server to use a nonstandard port.
Username The username to use when connecting to your server.
Password The password to use when connecting to your server.
Home Folder The folder that contains your homepage. Use the Browse button to navigate to your homepage to make sure you have the right location.

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 specifically for this purpose. See best practices for why.

The fields change with the protocol. WebDAV has no port field, and Amazon S3, Cloudflare R2, and DigitalOcean Spaces ask for a bucket and access keys instead of a host, username, and password. The step-by-step guides above cover each one.

Once you've filled out the form, select Test Connection to make sure everything works.

If all goes well, you'll see Connection successful!

Need our IP address?

In some cases, access to your server may be restricted by your web host or a firewall. You can usually get around this by whitelisting our IP address. Surreal CMS uses 162.243.9.115.

Trouble connecting with FTPS?

If you're having trouble connecting with FTPS, make sure your server supports TLS 1.2 or newer. Older versions of TLS are no longer supported. Surreal CMS uses explicit TLS, so implicit FTPS isn't supported either.


Enabling pages

Now that you're all connected, it's time to tell Surreal CMS which pages you want to be able to edit. Select your site from the Sites page, then select Enable Pages.

Screenshot of the Enable Pages dialog, listing the files in the home folder. Screenshot of the Enable Pages dialog, listing the files in the home folder.

You'll see the files in your home folder. Click a page to enable it, and it turns green. Open a folder to see what's inside. Select Done when you're finished.

Or select Scan for Pages and Surreal CMS will look through the folder and its subfolders for every page that has content regions. Uncheck any you don't want and enable the rest in one go.

Now you're ready to tell Surreal CMS what parts of the page you want to edit.


Defining content regions

Great! You're all connected and you've enabled some pages. Now let's edit one! Click a page in the list and you'll probably see a notice telling you that no content regions have been defined.

That's because you haven't told Surreal CMS what you want to edit. By design, we don't make your entire page editable. That would be disastrous, especially if you handed it off to a client! By opting in, you can ensure your design stays intact and that only certain parts of the page can be changed.

Let's define a content region so we can edit the page. In the editor's toolbar, select Source. You'll see the page's HTML appear in the source editor. Find something you want to make editable and give it a unique id and the cms-editable class:

<div id="my-content" class="cms-editable">
  <p>Editors can change this.</p>
</div>

Now hit Save Changes. Notice that you can edit the element you just tagged! 🎉

You can have as many content regions as you want on a page, and most elements can be made editable. Surreal CMS will give you the right set of tools based on the type of element you've tagged. A few elements, such as tables and forms, can't be content regions. For more info on various types of content regions, refer to this page.


Further reading

Now that we've covered the basics, you'll probably want to know what else you can do with Surreal CMS. Here are some things to explore once you've started editing your first website.

If you're having trouble connecting, feel free to contact us for help!