#FE: Integrations (from backend Phase 5)
Frontend spec for backend Phase 5: Integrations — requirements complete 2026-10-03, not built. V8 requirement It covers three things that users think of as "connected accounts".
| Integration | Where it lives (backend decision "Option B", 2026-10-03) | What that means for the frontend |
|---|---|---|
| Cloud server providers — used to create servers | Central — backend says organization level, the frontend doc says account level (D-27) | A normal Central screen: list, connect, disconnect. Central stores the credentials encrypted |
| Git accounts — used to deploy applications | Each server's OSS panel | The form is in Central, but the token is passed through to the chosen servers. Central keeps only a note (name, provider, which servers). OSS never gives a saved secret back |
| Backup storage — used for backups | Each server's OSS panel | Same as Git |
i18n namespaces: integrations.providers.*, integrations.git.*, integrations.storage.*, integrations.create.*, integrations.errors.*.
Permissions: organization-level for the provider screens; the OSS git and storage permissions for the per-server parts (see Roles & permissions).
#A. Cloud server providers (Central) — /:locale/integrations
| # | Feature | Screen / control | Rules from backend doc | Frontend notes |
|---|---|---|---|---|
| 5.1 | List | Page: one card or row per connected provider account | Accounts belong to the organization | Show provider logo, account label, "Used by N servers". Never show the secret — provider + label only |
| 5.2 | Connect | "Connect provider" → picker → one short form | Give the account a name, then paste the token. Vultr, DigitalOcean, Linode, Hetzner: an API token (no OAuth login). AWS Lightsail: access key + secret key. Checked on save, stored encrypted. More than one account per provider is allowed V8 requirement 2026-10-03 | One flow for every provider — a modal with a name field and a token field (two for Lightsail), never a redirect. The name is what the user picks from later, so it is required and shown everywhere. Several accounts per provider means the list groups by provider and the picker shows names, not just logos. Help text: where to create the token. Saving shows "Checking…", then the provider's own error if the token is wrong. Write-only secret: after saving show only a masked hint |
| 5.3 | Edit | "Edit" on the account → same modal | Change the name or paste a new token V8 requirement 2026-10-03 | One modal for both: the name pre-filled, the token field empty with "leave blank to keep the current token". This replaces the separate "paste new token" dialog |
| 5.4 | Invalid token | Status on the account → Edit | No automatic renewal (API tokens, not OAuth). If the provider rejects the token, the account shows "Needs new token" → Edit V8 requirement 2026-10-03 | Show "Needs new token" clearly in the list, with the Edit button right there, and block creating servers with that account, with the reason |
| 5.5 | Disconnect | Confirm dialog, or a blocking message | Central first checks whether any server was created with this account. If yes, disconnect is blocked and the warning lists those servers ("remove these servers first"). Disconnect is allowed only when no server uses it V8 requirement 2026-10-03 | Show the blocked state before the click: the Disconnect button is disabled with "Used by N servers", and the dialog lists them with links. This replaces the earlier rule that servers keep running after disconnect |
#B. Create a server on a cloud provider — wizard + live progress (moved to the Servers phase)
The backend's draft describes one flow (steps 1–7). The frontend part is the wizard and the progress screen.
Wizard fields (all values come from the API — never typed into the frontend): provider account · region · size · Ubuntu version (22.04 / 24.04 / 26.04 — whatever OSS supports) · stack (Nginx + PHP · Apache + PHP · Nginx + Node (MERN) · OpenLiteSpeed + PHP) · server name · optional SSH key · root password for Linode (same as V7). Review step before the final button.
Progress screen — the backend's statuses are the only states the frontend shows:
CreatingInstalling OSSReady | Failed (reason)Retry | Delete the server at the provider
- Poll the server record while the status is Creating or Installing OSS; stop when it is Ready or Failed.
- Ready → go to the server page. Failed → show the reason the backend gives, plus Retry and Delete the server at the provider (the second is destructive: confirm dialog naming the server).
- Installing OSS can take a while (the backend's limit is around 30 minutes), so the screen must be safe to leave and come back to: show the same progress from the server record, and tell the user they can leave.
- The IP appears only after the provider reports it (step 4) — show "waiting for the IP" instead of an empty field.
- Two more things the backend parked with this flow: V7 servers on Ubuntu 20.04 can't run OSS (22.04+ only), and Hostinger servers come with Apache/MySQL pre-installed (V7 removed them first) — both belong to the Servers phase, not here.
#C. Git accounts & backup storage (stored on the servers)
Two ideas run through this whole section:
- The account is the thing the user manages, and a server is just somewhere it is installed. So the list groups by account ("used on: Server 1, Server 2"), not by server.
- Central keeps only a note — name, provider and which servers have it. No secret, ever. So the UI never offers "view token", and every action that needs the secret asks for it again.
| # | Feature | Screen / control | Rules | Frontend notes |
|---|---|---|---|---|
| 5.6 | Connect on a server | Server → Git (or Storage) → Connect, as a modal in Central | Give the account a name, then paste the token / keys V8 requirement 2026-10-03. The form is in Central because OSS never returns a saved secret | After saving, the field is gone for good — show only the account name afterwards, with "Replace token" instead of an edit field |
| 5.7 | Also add to other servers | Checkbox list inside the same modal: other servers / all servers | Only servers of the organization the user may manage | Default to just this server. Show how many servers are selected. Servers the user can't manage are not listed at all |
| 5.8 | Result per server | Result list per server | Done / offline → Retry — for connect, update and remove alike V8 requirement 2026-10-03. The token is saved in OSS, not in Central | One result table reused by all three actions: server · result · Retry. Partial success is normal, so never show a single "saved" toast for a multi-server action — including removals |
| 5.9 | Test | Test button per server | Checks that the account works on that server V8 requirement 2026-10-03 | Per-server test, not a Central-side test: show the result inline on the row (works / the error) and when it was last tested. This is what the old "no test from Central" note was waiting for |
| 5.10 | Update everywhere | "Replace token" modal | The user enters the new token once; Central updates all servers that have this account | Reuse the per-server result list from 5.8 |
| 5.11 | Remove | Confirm dialog with a choice | This server only or all servers | Two clearly-labelled buttons, not a dropdown; the "all servers" option lists the servers |
| 5.12 | New server later | Prompt on a newly-ready server | Central offers "Connect your accounts here too?" — the user pastes the token again (Central kept no secret) | Explain why it's asked again, in one line, or users will think it's a bug |
| 5.14 | Organization → Integrations page | One overview page | Cloud providers plus all Git and storage accounts, each with "Used on: Server 1, Server 2". Actions: add to more servers, update on all, remove from all | This is the main Integrations page: section A on top (Central-stored), then Git and Storage grouped by account, not by server |
| 5.13 | Accounts already on the server | Same list, marked as found | If the OSS panel already has Git or storage accounts, Central reads them from OSS and shows them. The same account on several servers is shown once — even if each server holds a different token ("GitHub jayshree — used on: Server 1, Server 2") V8 requirement 2026-10-03. To add it to more servers, the user pastes the token once | Two cases in one list: accounts Central set up, and accounts it found on a panel. Mark the found ones ("found on this server") and never pretend Central holds their secret. Grouping is by account, so the same name on two servers must not appear twice. Because the tokens behind one row can differ, the row must not imply one shared secret — see D-30 about what "update everywhere" then does. Matching (provider + account name) comes from the API; the frontend only displays what it is given |
| 5.16 | Activity log | Nothing to build here — the entries show up on the organization Activity log | Every integration action is recorded with who, which account, which servers and when: connect, edit, add to other servers, update everywhere, remove, disconnect. Tokens and keys are never logged V8 requirement 2026-10-03 | The frontend only renders these entries (see Audit log), but it must match the backend's wording: an entry can cover several servers, so show the server list inside one entry instead of one entry per server. Never display a secret even if one ever appeared in a payload |
| 5.15 | Providers offered | Pickers | Git: GitHub, GitLab, Bitbucket (access token). Storage: S3 (Amazon S3, Wasabi, custom S3), Google Drive (service account), FTP, SFTP | A self-hosted GitLab needs a URL field (V7 had it; the backend's short list no longer says so — worth confirming). S3-compatible needs endpoint + bucket + region. Field sets differ per provider, so drive them from one small config |
#Not in this phase (kept as our record)
- Regions & sizes of a provider (read live when creating a server) → Servers phase (moved out 2026-10-03).
- Repos & branches (account → repository → branch pickers, read from the server's OSS) → Applications phase (moved out 2026-10-03). The dependent-dropdown spec moves with it.
- Creating a server on a cloud provider and the automatic OSS install → Servers phase (moved out on 2026-10-03).
- Connecting an existing / own server (paste the install command) → Servers phase.
- Server list, server details and server actions → Servers phase.
#Who can do it
Connect, edit, test and remove follow the organization roles from Phase 4 (by Pair 1) V8 requirement 2026-10-03. So every button on these screens is permission-driven: hide what the role can't do, and never show an action that will come back as "not allowed". The exact permission names are still unpublished — build the checks from the API's catalog.
#Existing users
- Vultr, Hetzner and AWS Lightsail accounts move from V7 as they are — they were already key-based. V8 requirement 2026-10-03
- DigitalOcean and Linode used a provider login in V7, so after the move the user pastes an API token once. This answers D-29: those accounts arrive needing a token, which is exactly the "Needs new token" state (5.4) — so the first login must show them clearly, with Edit, and explain why in one line.
- V7's Git and Google Drive connections used one-click login; in V8 they become a pasted token / service account stored in OSS — accepted (Q9, 2026-10-03). How they move is decided later, with the migration phase (Q10), so the screens must cope with "no accounts yet" for a migrated user and say why.
- Dropbox is not supported in Phase 5 (Q11, skipped for now). V7 users who back up to Dropbox need a plain message and another destination in the storage picker.
- (The Ubuntu 20.04 limit moved to the Servers phase with the create-server flow.)
#Open points the frontend is waiting on
| ID | Question | Why the frontend cares |
|---|---|---|
| Q9 | One-click login → token / service account — answered 2026-10-03: accepted. Git uses an access token or app password, Google Drive a service account, as in OSS | No OAuth button anywhere in the integration screens. Every connect form is a token form |
| Q10 | Moving V7 Git / storage connections — parked: decided later, with the migration phase | Migrated users may arrive with nothing connected, so the empty state must explain that they need to reconnect |
| Q11 | Dropbox — skipped for now (2026-10-03): not supported in Phase 5 | Not in the storage picker. V7 Dropbox users need a message and an alternative |
| Q12 | Hostinger — answered 2026-10-03: no. It was never a connectable provider in V7 (only IP detection when adding an existing server, then removing its pre-installed Apache/MySQL). It belongs to the Servers phase | Nothing to add to the provider picker |
| Q13 | OSS registration is open after an automatic install until someone registers | A security hole in the create-server flow, not a screen — now a Servers phase point. If it stays, the progress screen should not show the panel URL before Central has claimed the admin account |
| Q14 | Should Central rotate the Central token after the first successful call (it sits in the provider's start-up script)? | Possibly a "key rotated" state on the server record — now a Servers phase point. No screen yet |
| D-27 | Are integrations account level (Bhavik) or organization level (backend Phase 5)? | Decides who owns a provider account and whose servers appear in the "add to other servers" list. The frontend keeps account level for now |