# Connecting a site

Surreal CMS doesn't host sites. It connects to the user's existing hosting, reads the page files, and publishes back to the same place. Before you can create a site you need a live website and credentials for where its files live.

Source: https://www.surrealcms.com/docs/connecting and the hosting guides under https://www.surrealcms.com/docs/.

## What to ask the user for

Ask once, and ask only for what the protocol needs. Don't guess credentials, and don't repeat them back in chat.

1. The public URL, e.g. `https://www.example.com/`. For a subsite, the URL of that folder, e.g. `https://example.com/menu/`.
2. How the files get to the server. If the user doesn't know, SFTP is the best choice when the host offers it, then FTPS, then plain FTP.
3. The credentials for that protocol, listed below.
4. The folder that holds the homepage, if they know it.

## Fields by protocol

All protocols also take `name`, `url`, `homeFolder`, and `uploadFolder`.

`url` must be a public `http` or `https` address. Surreal CMS fetches it to render pages, so `localhost`, private network addresses (such as `192.168.x.x` or `10.x.x.x`) and link-local addresses are refused with `VALIDATION_ERROR` and `invalid: ["url"]`. A site that is only reachable on a local network can't be edited.

| Protocol            | `protocol` | Required fields                                                                                                  | Home folder format                                                                         |
| ------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| FTP                 | `ftp`      | `host` (no `ftp://`), `username`, `password`; `port` if not 21                                                   | Server path, e.g. `/public_html`. Empty if the FTP account is locked to the site's folder. |
| FTP with TLS        | `ftps`     | Same as FTP                                                                                                      | Same as FTP                                                                                |
| SFTP                | `sftp`     | `host` (no `sftp://`), `username`, `password`; `port` if not 22                                                  | Full server path, e.g. `/home/user/public_html` or `/var/www/example.com`                  |
| WebDAV              | `webdav`   | `host` = full WebDAV URL with `https://` and port, e.g. `https://example.com:2078/`; `username`, `password`      | Path relative to the WebDAV URL                                                            |
| Amazon S3           | `s3`       | `s3Region` (e.g. `us-east-1`), `s3Bucket`, `s3AccessKey`, `s3SecretKey`; `s3Acl` only for old public-ACL buckets | Key prefix with no leading slash; empty for the bucket root                                |
| Cloudflare R2       | `r2`       | `r2AccountId` (32 hex chars), `s3Bucket`, `s3AccessKey`, `s3SecretKey`                                           | Same as S3                                                                                 |
| DigitalOcean Spaces | `spaces`   | `s3Region` (datacenter slug, e.g. `nyc3`), `s3Bucket`, `s3AccessKey`, `s3SecretKey`                              | Same as S3                                                                                 |

Rules for folders:

- `homeFolder` must be the folder that `url` serves. If they don't match, publishing "works" but the live site never changes.
- `uploadFolder` must be `homeFolder` or a folder inside it, publicly reachable, and free of pages.
- Best practice is a dedicated `uploads` folder (or similar) that holds only uploaded files, e.g. `/public_html/uploads` or `uploads`. The upload folder is the only part of the server editors can change from Surreal CMS: the file manager and the editor's image and link pickers show that folder and nothing else, and the server rejects uploads, renames, moves, deletes, and image edits outside it. Pointing it at the home folder would show editors every file on the site and let them rename or delete pages, stylesheets, and scripts. A dedicated folder scopes all their file activity to one place. **Scan for Pages** skips it too. Deleting pages is separate: users can delete pages from the Pages list unless `canDeletePages` is `false`.
- On FTP, FTPS, SFTP, and WebDAV, the upload folder must already exist on the server, or uploads fail. On S3, R2, and Spaces it doesn't matter.
- No trailing slashes.

Example:

```json
{
  "name": "Acme Bakery",
  "url": "https://www.acmebakery.com/",
  "classification": "commercial",
  "protocol": "sftp",
  "host": "acmebakery.com",
  "username": "surreal",
  "password": "…",
  "homeFolder": "/var/www/acmebakery.com",
  "uploadFolder": "/var/www/acmebakery.com/uploads",
  "canDeletePages": false,
  "canDuplicatePages": true
}
```

## Classification

`commercial` is the default and the right choice for any site that sells something or promotes a business, including a sole proprietor's. `personal`, `educational`, and `non-profit` sites are free, but Surreal CMS staff review them and may reclassify them. Ask the user if you're unsure, and never pick a non-commercial classification just to avoid cost. Details: https://www.surrealcms.com/docs/website-classifications

## Verifying the connection

`POST /sites` doesn't test the connection, and neither does enabling existing files. Ask the user to test it in the app with **Edit Site → Test Connection**. You can also test the credentials yourself with a local client (`lftp`, `sftp`, `curl`, `aws s3 ls`) if the user is comfortable with that. Creating a page with `createOnServer: true` connects too, and a `CONNECTION_AGENT_*` error there means the credentials or folders are wrong.

## How Surreal CMS connects

|            |                                                                                                                                                                                                                                                                                                                                          |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| IP address | `162.243.9.115`. Firewalls, fail2ban, and IP allowlists must allow it, for the file connection and for HTTP (the editor loads the live page from this IP). HTTP requests also send `Client-Id: clientcms` and a current Chrome user agent; bot protection that can only match on headers should match `Client-Id`, never the user agent. |
| FTP        | Passive mode only. One file at a time. 10-second timeout.                                                                                                                                                                                                                                                                                |
| FTPS       | Explicit TLS on the normal FTP port, TLS 1.2+. Implicit FTPS (port 990) isn't supported.                                                                                                                                                                                                                                                 |
| SFTP       | Password authentication only; SSH keys aren't supported. The SFTP subsystem must be enabled. 10 files at a time.                                                                                                                                                                                                                         |
| WebDAV     | HTTP Basic auth over HTTPS (not Digest). The server must allow `PROPFIND GET PUT MKCOL MOVE DELETE`. The WebDAV URL must serve files without executing them, or PHP pages come back rendered. nginx's built-in module lacks `PROPFIND`. 10 files at a time.                                                                              |
| S3         | The IAM user needs `s3:ListBucket` on the bucket, and `s3:GetObject`, `s3:PutObject`, `s3:DeleteObject`, and `s3:AbortMultipartUpload` on its objects. Use a private bucket behind CloudFront with the CachingDisabled policy and a function that maps `/` to `index.html`. 20 files at a time.                                          |
| R2         | The API token needs Object Read & Write on the bucket. Serve it on a custom domain; set Browser Cache TTL to "Respect Existing Headers" and avoid Cache Everything rules. 20 files at a time.                                                                                                                                            |
| Spaces     | The key needs Read/Write/Delete on the bucket. 20 files at a time.                                                                                                                                                                                                                                                                       |

Files published to S3, R2, and Spaces get `Cache-Control: no-cache`, so edits show up immediately unless a CDN rule overrides it.

## Troubleshooting

| Symptom                                  | Likely cause                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONNECTION_AGENT_AUTHENTICATIONERROR`   | Wrong username or password, or a key where a password is needed. Some hosts want the full `user@example.com` username. For SFTP, password login may be disabled (`PasswordAuthentication no`). For WebDAV, the server may only accept Digest auth. For S3, R2, and Spaces, a wrong key or secret, or a key without access to the bucket (S3 reports `AccessDenied` this way). |
| `CONNECTION_AGENT_CONNECTIONERROR`       | Wrong host or port, a scheme typed into an FTP or SFTP host, `162.243.9.115` blocked, an FTPS server without explicit TLS 1.2, or SFTP on port 21 by mistake. For S3 and Spaces, a wrong bucket or region; for R2, a wrong bucket or account ID.                                                                                                                              |
| `CONNECTION_AGENT_DOWNLOADERROR`         | Publishing couldn't read the page's file: it was moved, renamed, or deleted outside Surreal CMS, `homeFolder` changed, the user can't read it, or FTP passive ports are blocked.                                                                                                                                                                                              |
| Listing fails after login                | FTP passive ports are blocked, or the home folder doesn't exist or isn't readable.                                                                                                                                                                                                                                                                                            |
| Upload fails                             | The user can't write to that folder (files owned by `root` or `www-data`), the disk is full, or the folder doesn't exist. On S3, `s3Acl` is on for a bucket with ACLs disabled.                                                                                                                                                                                               |
| Publishing succeeds, site doesn't change | `homeFolder` doesn't match `url`, or a CDN or cache is serving an old copy.                                                                                                                                                                                                                                                                                                   |
| Editor shows the page without styles     | The stylesheet is served over `http://`, or fonts are missing CORS headers.                                                                                                                                                                                                                                                                                                   |
| Editor can't load the page               | HTTP auth, bot protection, or an IP allowlist is blocking `162.243.9.115`.                                                                                                                                                                                                                                                                                                    |

Step-by-step host guides: https://www.surrealcms.com/docs/ftp, /docs/sftp, /docs/webdav, /docs/amazon-s3, /docs/cloudflare-r2, /docs/digitalocean-spaces.

Each publishing error has its own page under https://www.surrealcms.com/docs/errors. The app links owners and admins to it from the publish dialog.
