Documentation

RunCloud Sites builds new websites on your own RunCloud servers from the WebProCMS dashboard. Pick a server, type the domain, and the site is created, waits until the domain points at the server, gets a free Let's Encrypt certificate, and is checked over HTTPS. It can build a plain WordPress site, or a WebProCMS site by way of a WordPress install that arrives with the WebProCMS installer plugin already in it.

Beta. RunCloud only offers API access on its Business and Enterprise plans, and this feature was built from RunCloud's API documentation before a live account was available to test against. Every step reports RunCloud's own error message when something is refused. Check your first few sites in RunCloud as they finish.

The problem

Setting up a client site on a RunCloud server is a checklist done by hand in the RunCloud panel: create the web app, install WordPress, add www, wait for the client to change DNS, come back later to issue the SSL certificate, and (for WebProCMS) change the PHP settings and upload the installer plugin. The step that waits for DNS is the one that gets forgotten. Requesting the certificate too early fails, and Let's Encrypt locks a domain out for an hour after five failures.

The fix

A feature module under app/Features/RunCloud/ talks to the RunCloud API with a token you provide. Each new site is a row in runcloud_sites, driven through its stages by a background task (runcloud-provision) that keeps going without anyone watching:

1. Create. RunCloud creates the web app and installs WordPress with the title, admin username, email and a generated password.
2. Configure. www is turned on when asked. The DNS records the domain needs are saved for the dashboard to show. For a WebProCMS site, the PHP settings are changed (see below).
3. Wait for DNS. Every five minutes the site checks whether the domain (and www) resolve to the server's IP. It gives up after seven days and lists the records to add.
4. SSL. One Let's Encrypt request. The request is recorded before it is sent, so if the call times out the task does not send another. A refusal is shown with RunCloud's message and is not retried automatically, because repeated failures lock the domain out. Only a person pressing Retry asks again.
5. Verify. The site counts as finished only once https:// answers with a valid certificate. If that hasn't happened 30 minutes after the request, the site is marked Needs attention. Retry then checks RunCloud for a certificate and asks Let's Encrypt again only if RunCloud has none.

Brief RunCloud trouble is waited out on the task's own backoff: a rate limit, a RunCloud server error or a network failure is retried for about an hour and a half before the site is marked Needs attention. The backoff resets each time a step succeeds. Button presses on the page always win over a step that is still running.

When the domain's DNS is on Cloudflare and your RunCloud account has a Cloudflare integration, pick it in the form. RunCloud adds the DNS record itself and proves the domain through Cloudflare (dns-01), so step 3 is skipped.

What the dashboard gets

RunCloud in the sidebar (admins only), with a Beta badge:

• Servers — every server the token can see, with its IP and whether RunCloud reports it online.
• Sites created here — each site's status (Creating, Configuring, Waiting for DNS, Issuing SSL, Checking HTTPS, Ready, Needs attention), the latest message, and the DNS records to give the client. Actions:
  • Check DNS now — re-checks immediately instead of waiting for the next five-minute check.
  • Request SSL now — skips the DNS check, after a confirmation. Use it only when the domain reaches the server through a proxy such as Cloudflare's orange cloud, because the IP check can't see through one.
  • Retry — picks a failed site up from the stage it stopped at.
  • Remove from list — stops any setup still running, deletes the site's temporary installer canvas, and forgets the site here. It never deletes the web app, its files or its database in RunCloud.
• New site — site type, server, PHP version (from what the server has installed), domain, "also serve www.", web app name, site title, WordPress admin username and email, and the optional extras the account has: a starter canvas (WordPress only), a Cloudflare integration, and — on a fleet server, for WebProCMS — the member to license the new site under.

The WordPress admin password is generated (24 characters) and shown once, right after you press Create site. It is stored encrypted only until RunCloud has created the site, then discarded. If it is lost, reset it from WordPress's "Lost your password?" link (it goes to the admin email) or in RunCloud.

RunCloud → Settings holds the API token in a write-only field: stored encrypted, never shown again, replaced by pasting a new one, and removed with the field's Remove button. Save & test pings RunCloud and counts the servers the token can see.

WebProCMS sites

Choosing WebProCMS builds the setup that the WordPress installer plugin expects:

• WordPress is installed with the public path set to /public, so the installer can put WebProCMS beside it.

• A temporary RunCloud canvas adds the installer plugin. The canvas points RunCloud at a signed link to this site (/runcloud/installer/{id}/webprocms-installer.zip). The link:

  • is always on the site's own address (APP_URL);
  • expires after six hours;
  • stops working once the site is finished or has failed.

  Each attempt at the create step makes a fresh canvas, so a retry never hands RunCloud an expired link. The canvas is deleted when the site is finished or removed, and these canvases are kept out of the starter-canvas picker.

• On a fleet server, if you pick a member, the zip comes with the member's license and the fleet's enrollment settings filled in (the same zip as Fleet → Download installer), so the new site joins the fleet when it installs. If that member is deleted, or the site stops being a fleet server before RunCloud fetches the zip, the site fails with the reason. A plain installer is never served in place of the one you picked.

• The site records when RunCloud downloads the installer. A WebProCMS site that finishes without that download is still marked ready, but says that the plugin is missing and should be uploaded in WordPress.

• Disabled Functions is set to the installer's Recommended list and Max Execution Time is raised to 60 seconds. The site's other PHP settings are sent back to RunCloud unchanged.

• PHP 8.4 or newer is required. The form refuses an older version.

When the site is ready, log in at https://{domain}/wp-admin, open Install WebProCMS and click Install.

Two steps from the RunCloud prerequisites in the installation guide still have to be done by hand, because RunCloud's API can't change OpenLiteSpeed configuration:

• Raise the per-worker memory limit to 4096M.
• Set the one-year static-asset cache.

WordPress sites

WordPress is installed with an http:// address, and HTTP stays reachable after the certificate is issued, because forcing HTTPS before WordPress's own addresses are changed causes a redirect loop. Once the site is ready:

1. Change both addresses under WordPress Settings → General to https://.
2. Turn off HTTP access on the web app's SSL tab in RunCloud.

Setup

1. In RunCloud, open your workspace → Settings → API Management and create a token. This needs a Business or Enterprise plan.
2. Enable RunCloud Sites under Settings → Features.
3. Paste the token under RunCloud → Settings and press Save & test.
4. Press New site.

Security

• The token can manage every server in the workspace, including deleting them, and RunCloud tokens have no narrower permissions. That is why the pages are Admin-only, the field is write-only, and the token is only read when a call is about to be made.
• RunCloud's integrations list returns each saved integration's secret. The client keeps only the id and label; nothing else from that response reaches a page.
• The installer link is the only route without a login, and it is gated by its signature, its expiry and the site's state.

Limitations

• Not yet proven against a live account (see the beta note). In particular, the RunCloud docs leave these open, so they are handled defensively:
  • The response shapes vary, so the client accepts lists both with and without a data wrapper.
  • The PHP-settings update may reset fields it isn't sent, so the current values are always sent back with it.
  • It isn't documented whether a canvas plugin link must end in .zip, so the link does.
• RunCloud's API can't buy a server. It works with servers already connected to your RunCloud account.
• DNS is only set automatically through a RunCloud Cloudflare integration. Every other DNS host needs the listed records added by hand.
• Removing a site from the list never deletes the web app, its files or its database in RunCloud. Do that in RunCloud.