#FE: Add a server (from backend Phase 8)

Phase 8 status (2026-10-16 10:59, Pair 2): 8.1 (all 5 cloud providers), 8.3, 8.4, 8.5, 8.7, 8.9–8.12 built & pushed. 8.8 checks built except plan active / server limit (wait for Phase 7) and provider enabled by admin (waits for the admin panel). Pending: 8.2 managed (waits for Billing — no user screen anyway, D-36) and 8.6 Lite (waits for Phase 10 + Phase 12 Control Panel). Still needs the OSS installer update before install-based ways go live.

Frontend spec for backend Phase 8 — Servers: create & connect — requirements complete 2026-10-06 (Pair 1), not built. V8 requirement The phase the Servers screens had been waiting on since the first draft of this site. It covers six ways to get a server into Central — five of which install the OSS panel — what Central stores about it, and what happens while the install runs.

i18n namespaces: servers.add.*, servers.create.*, servers.connect.*, servers.install.*.

#Connect a panel — built (B8.5, Pair 2 API62–64)

🆕 Route/navigation: Servers → Add server → Connect a panel (/servers/create?source=connect_oss, proposed) → on success → Server details (/servers/{id}). Backend: API62 connect, API63 list, API64 view — all under the selected organization. Permission: server manage to connect, server view to list/view; not a member → 404, role without the permission → 403 (hide Add server). i18n: servers.connect.*, servers.list.*, servers.errors.*.

• Form fields (updated 2026-10-14 11:22): API address — request field api_url (renamed from panel_url) (https://api.…, shown together with the Central token in the OSS panel; port 443 only, no login/query/#; a path is dropped). The panel's web address (https://panel.…) is not accepted — label the field "API address" with an example and help text, not "Panel address" · Central token (from the panel: Admin → Central, shown with the API address; starts with sv_central_, no spaces) · Name (optional, max 100; default = server hostname). Help text tells the user where to find the token.
• Connect: button shows loading and is disabled while Central checks the panel live (a few seconds). ✔ 201 → TOAST "Server connected" → Server details. ✖ 422 → show the backend message as is:
  • private/local address → field error on API address (api_url);
  • oss_unreachable (offline, wrong address, firewall) · oss_not_a_panel (something answered, but not the OSS API — e.g. the panel.… address was entered instead of api.…; hint the user to use the API address) · oss_bad_response (answered with data Central couldn't read) · oss_error;
  • oss_token_rejected → also tell the user to generate a new token in the panel;
  • server_already_connected → this panel (same address or IP) is already in ServerAvatar — keep it neutral, never say whose account.
  • 429 (10/min) → wait and retry.
• Server list (API63): cards/rows: name, hostname, status label, source label, API address (api_url; the panel's web address is panel_url), public IP (or "—"), stack, OS, created by, connected date. Newest first, 12 per page (max 50). Empty → "No servers yet" + Add server. No search/filters yet (they come with the server-list step).
• Server details (API64): the same fields plus the one-time system_info (renamed from facts, 2026-10-14) (OSS version, OS, CPU/cores, RAM and disk in bytes → format with locale, web server, app count) labelled "at the time it was added" — not live. Another organization's server → 404 page. The Central token is never shown.
• Statuses: pending, creating, installing, connecting, ready, failed (use status_label). Sources: connect_oss, install_command. Stack values now include docker.
• Done when: connect form validation, loading/disabled, every 422 code + 429, success redirect, list pagination/empty, details 404, permission hide/deny and locale formatting pass against Pair 2's API.

#Cloud server — all five providers built (B8.1, Pair 2 API71–75)

🆕 Route/navigation: Servers → Add server → Cloud provider (/servers/create?source=cloud, proposed) → progress screen = Server details (/servers/{id}). Backend: API71 accounts, API72 regions, API73 sizes, API74 create, API64 view (poll), API75 retry, API67 delete. Permission: server manage (no Integrations permission needed to pick an account). i18n: servers.cloud.*, servers.install.*, servers.errors.*.

• Step 1 — Account (API71): the organization's connected cloud accounts. Only providers in meta.supported_providers (all five: digitalocean, vultr, hetzner, linode, lightsail) can be picked; others greyed "Coming soon". Account with status: needs_new_token → disabled with "Update this account in Integrations" link. No accounts → "Connect a cloud account first" → Integrations.
• Step 2 — Region (API72) list by name → Size (API73) for that region (1 GB and up, cheapest first; show the price/specs the API returns with its currency — USD for DigitalOcean/Vultr, EUR for Hetzner; never assume $. Hetzner also lists Arm (CAX) sizes) + Ubuntu (22.04 / 24.04 / 26.04) + Stack (LEMP / LAMP / MERN / OpenLiteSpeed / Docker) + Name (rules per provider, as V7 — DigitalOcean: max 63, letters, numbers, dots, hyphens; Vultr: no dots; show the API's field error) + optional your SSH public key (ssh-ed25519 / ssh-rsa / ecdsa; for your own SSH access) + Linode only: root password (required; 11–128 characters with lower + upper case, a number and one of @$!%*#?&; Linode's own strength check may still refuse it — show its reason; never kept after the request; don't send it for other providers). Linode hides sold-out and GPU/Accelerated plans. Lightsail only: availability zone — regions from API72 carry zones; pick a region, then a zone (required for Lightsail, don't send for others). Tell Lightsail users the server has no static IP (as V7: the IP can change after a stop/start in AWS).
• Create (API74) → spinner (a few seconds) → ✔ 201 → progress screen: Creating ("Creating your server at {provider}…", up to 15 min) → Installing (step + title) → Connecting → Ready ("Open your panel now and create your admin account").
• ✖ (nothing saved): cloud_provider_not_supported · cloud_account_not_connected / cloud_token_rejected → "Update the account in Integrations" · cloud_rejected (DigitalOcean's reason, e.g. size not in region) · cloud_unavailable (503, try again) · central_ssh_key_missing (503 — Central not set up; contact support) · 429. Region/size loading errors use the same codes.
• Failed (extra reasons: cloud_create_failed, cloud_timeout, cloud_token_rejected, cloud_account_not_connected, server_ip_in_use, ssh_start_failed): Retry (API75) CONFIRM — same droplet, no new cost → back to Creating; 409 cloud_server_gone → "The server was deleted at DigitalOcean — delete it here and create a new one". Delete (API67) CONFIRM with checkbox "Also delete this server in my {provider} account" (it still costs money there) → delete_at_provider; a provider error stops the delete (nothing removed, try again).
• Install fixes (Pair 2, 2026-10-21, built): (1) a panel that only got a self-signed certificate now still becomes Ready — nothing extra to show. (2) New Failed reason ssh_login_refused (Central's SSH key refused; shows after ~3 min instead of a silent 15-min cloud_timeout). (3) Retry after a finished install only re-checks the panel (no new install, same server) — keep the same Retry CONFIRM, back to Connecting. (4) Show the real cause: under the Failed message render failure_detail.message when it is not null (e.g. "The SSL certificate at … is not valid"); failure_detail.code is for logic only (e.g. cloud_not_active, ssh_port_closed, tls_invalid, connect_timeout). Texts come translated from the backend — never show raw errors.
• Start-up script (Pair 2, 2026-10-22, built): a new cloud server now starts the panel install by itself at first boot; Central falls back to SSH after ~5 min if it did not. No new screen or step. Frontend notes: the server's IP may already show while still Creating (public_ip set) — show it when present; a cloud_timeout failure can carry failure_detail.code user_data_pending (the start-up script never ran) — show its failure_detail.message like any other cause.
• Note for users: without their own SSH key they reach the server through the panel or the DigitalOcean console (Central's key is removed after a successful install).
• Done when: account/region/size steps with every state, supported-provider greying, needs-new-token link, validation, every create error, progress polling incl. Creating, Retry (+ server gone) and Delete with/without provider deletion pass.

#Root password — built (B8.3, Pair 2 API69–70)

🆕 Route/navigation: Servers → Add server → My own server → "Yes, I have the root password" (/servers/create?source=root_password, proposed) → progress screen = Server details (/servers/{id}), same as the install command but without the command box. Backend: API69 add, API64 view (poll), API70 retry, API67 delete. Permission: server manage (email check in the frontend — see D-59). i18n: servers.rootPassword.*, servers.install.*, servers.errors.*.

• Form: Name (max 100) · Stack (LEMP / LAMP / MERN / OpenLiteSpeed / Docker) · IP (public IPv4 only) · SSH port (default 22) · Root password. Tip under the form: "Allow SSH from 23.172.120.38 and enable root password login." → Add server (spinner, a few seconds).
• Root password: never kept after the request — no state, storage, logs, URLs or analytics; clear the field on success and on error.
• ✔ 201 → progress screen: poll API64 every ~5 s while Installing / Connecting, show installation_status.step + .title; Ready → "Open your panel now and create your admin account" (panel_url).
• ✖ 422 (nothing saved — show the API message as is): server_ip_in_use (IP already in ServerAvatar) · ssh_unreachable_from (wrong IP/port, offline, firewall — plain V7 message since 2026-10-16, Central's IP no longer shown) · ssh_login_failed (password refused or root login disabled) · ssh_unsupported_os (not Ubuntu 22.04/24.04/26.04) · ssh_unsupported_arch (not x86_64/ARM64) · ssh_start_failed · field errors. 429 (10/min per user, 5/min per IP) → wait.
• Failed → Retry (API70) MODAL: asks for the root password again (+ SSH port) → back to Installing with a new token. 409 if not failed; SSH errors keep it Failed with the message. Delete (API67) CONFIRM → Servers list.
• Hostinger servers: nothing extra for the user (Central cleans up as V7).
• Done when: form validation, IP rules, password never retained, every SSH error, progress polling, Ready link, Retry (password again) and Delete pass.

#Install command — built (B8.4, Pair 2 API65–68)

🆕 Route/navigation: Servers → Add server → My own server → "No root password" → Install command (/servers/create?source=install_command, proposed) → install progress page = Server details (/servers/{id}). Backend (renumbered 2026-10-16): API65 create, API64 view (poll), API66 retry, API67 delete (one delete API for every server; for cloud servers it can also delete the droplet); API68 is the installer report (not for the frontend). The old "command again" API was removed 2026-10-15. Permission: server manage. Email verification (changed 2026-10-15): the API no longer checks it — the backend says the frontend must block unverified users (and an unverified owner, as V7) before showing the form: "Verify your email to add a server" + Resend. See D-59. i18n: servers.install.*, servers.errors.*.

• Simple flow (2026-10-15): Name + Stack → Create server → the command and the live steps on the same screen.
• Form: Name (required, max 100) + Stack (LEMP / LAMP / MERN / OpenLiteSpeed / Docker — added 2026-10-15; API values lemp, lamp, mern, ols, docker). No IP field, no force-cleanup option, no database field. Submit → 201 → progress page.
• Command box: the one-line command (copy button) + "Run this as root on your Ubuntu 22.04 / 24.04 / 26.04 server". The command holds the server's secret token — never log it, put it in a URL or analytics; show it only from the 65/67 answers. No "show command again" (removed 2026-10-15): if the page is refreshed before the command is run, the user starts again.
• Field name (2026-10-16): the install progress object is installation_status (was install).
• Progress (poll API64 every ~5 s while pending / installing / connecting; stop on leave):
  • Pending — waiting for the command to run (command + live steps on the same screen). A never-run server is not shown in the server list and is removed automatically after 24 h (not Failed).
  • Installing — show installation_status.step + installation_status.title as sent by the installer (English, show as is), e.g. "[08] Fetching the panel".
  • Connecting — "Connecting…" (Central checks the new panel, up to ~5 min).
  • Ready — "Open your panel now and create your admin account" + link to panel_url (the panel's web address; api_url is the API address). Then the normal server page.
  • Failed — failure_message + where it stopped (installation_status.title / installation_status.message) + Retry and Delete. Codes: install_failed, install_timed_out (30 min silent), oss_unreachable, oss_token_rejected, oss_bad_response, oss_error, install_panel_mismatch, server_already_connected.
• Retry (API66) — only for Failed (2026-10-15) — CONFIRM ("the old command stops working") → new command + Pending again. 409 otherwise.
• Delete (API67 — the one delete API for all servers) CONFIRM → 204 → Servers list. Only for install-command servers that never became Ready (409 otherwise; deleting a Ready server comes with Phase 9).
• 429 (10/min for create + retry) → wait and retry.
• Done when: form validation, frontend email-verified block (user + owner), command copy + no leaks, every status with polling start/stop, Ready panel link, every failure code with Retry/Delete, 409 cases and permission hide/deny pass — and the OSS installer update is live.

#A. The six ways to add a server

#B. What every way shares

Update 2026-10-27 (Pair 2, local commit): every way that installs the OSS panel (cloud server, root password, install command, managed) accepts an optional panel administrator (username + password). If the user leaves both empty, Central creates one (admin + 24 random letters/digits) and returns it once in the create response. Show it on a one-time screen with copy buttons and a clear "save this now — it won't be shown again" note. Central no longer keeps the username, so the server page must not show a panel-admin username afterwards.

Who can do it: organization roles with server manage, from Phase 4.

#C. Still open after this phase

The backend listed five things as "not in this phase". Three matter to the screens:

• Refreshing server data — later updates from OSS, offline status and "needs new token" are decided later. This is the heart of Q3, and it leaves the server list's liveliness undefined: the one-time copy from 8.11 is all Central is promised to hold.
• Also parked: everything after a server exists (list, server page, power, resize, delete, disconnect, settings, apps, databases) — their own phases — and whether name and hostname can be edited separately.

#Existing users

V7 servers carry over and move to OSS, but how the move works is decided later. So the migration story this site has flagged since the first draft — that a V7 server only becomes manageable once OSS is installed on it — is still unwritten, and D-19 (installing OSS on a live V7 server is untested) still applies.

#What this phase answers