From dc6b2ce3aadb99f739027e367b60ab9a85c4cff6 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Wed, 25 Mar 2026 13:52:58 +1300 Subject: [PATCH 01/18] (feat): auto-detect cli params to force non-interactive installer --- src/Appwrite/Platform/Tasks/Install.php | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/src/Appwrite/Platform/Tasks/Install.php b/src/Appwrite/Platform/Tasks/Install.php index eab6babc66..c8f9af8400 100644 --- a/src/Appwrite/Platform/Tasks/Install.php +++ b/src/Appwrite/Platform/Tasks/Install.php @@ -211,7 +211,8 @@ class Install extends Action } // If interactive and web mode enabled, start web server - if ($interactive === 'Y' && Console::isInteractive()) { + // Skip the web installer when explicit CLI params are provided + if ($interactive === 'Y' && Console::isInteractive() && !$this->hasExplicitCliParams()) { Console::success('Starting web installer...'); Console::info('Open your browser at: http://localhost:' . InstallerServer::INSTALLER_WEB_PORT); Console::info('Press Ctrl+C to cancel installation'); @@ -767,7 +768,7 @@ class Install extends Action 'email' => $email, 'domain' => $domain, 'database' => $database, - 'hostIp' => $hostIp !== $domain ? $hostIp : null, + 'ip' => $hostIp !== $domain ? $hostIp : null, 'os' => php_uname('s') . ' ' . php_uname('r'), 'arch' => php_uname('m'), 'cpus' => ((int) trim((string) \shell_exec('nproc'))) ?: null, @@ -1261,6 +1262,22 @@ class Install extends Action $this->hostPath = $this->getInstallerHostPath(); } + /** + * Check if any installer-specific CLI params were explicitly passed. + * When params like --database or --http-port are provided, the user + * intends to run in CLI mode rather than launching the web installer. + */ + private function hasExplicitCliParams(): bool + { + $argv = $_SERVER['argv'] ?? []; + foreach ($argv as $arg) { + if (\str_starts_with($arg, '--') && !\str_starts_with($arg, '--interactive')) { + return true; + } + } + return false; + } + /** * Detect the database adapter from a pre-1.9.0 compose file by * checking which DB service exists or reading _APP_DB_HOST. From c72d438a104f45d007833e990d63b25c61d4cad3 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 30 Mar 2026 15:55:37 +0100 Subject: [PATCH 02/18] fix: remove INDEX_SPATIAL from DocumentsDB index creation --- .../Databases/Http/DocumentsDB/Collections/Indexes/Create.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Appwrite/Platform/Modules/Databases/Http/DocumentsDB/Collections/Indexes/Create.php b/src/Appwrite/Platform/Modules/Databases/Http/DocumentsDB/Collections/Indexes/Create.php index 3aee3ebcb1..dc3ce34605 100644 --- a/src/Appwrite/Platform/Modules/Databases/Http/DocumentsDB/Collections/Indexes/Create.php +++ b/src/Appwrite/Platform/Modules/Databases/Http/DocumentsDB/Collections/Indexes/Create.php @@ -58,7 +58,7 @@ class Create extends IndexCreate ->param('databaseId', '', fn (Database $dbForProject) => new UID($dbForProject->getAdapter()->getMaxUIDLength()), 'Database ID.', false, ['dbForProject']) ->param('collectionId', '', fn (Database $dbForProject) => new UID($dbForProject->getAdapter()->getMaxUIDLength()), 'Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection).', false, ['dbForProject']) ->param('key', null, fn (Database $dbForProject) => new Key(false, $dbForProject->getAdapter()->getMaxUIDLength()), 'Index Key.', false, ['dbForProject']) - ->param('type', null, new WhiteList([Database::INDEX_KEY, Database::INDEX_FULLTEXT, Database::INDEX_UNIQUE, Database::INDEX_SPATIAL]), 'Index type.') + ->param('type', null, new WhiteList([Database::INDEX_KEY, Database::INDEX_FULLTEXT, Database::INDEX_UNIQUE]), 'Index type.') ->param('attributes', null, fn (Database $dbForProject) => new ArrayList(new Key(true, $dbForProject->getAdapter()->getMaxUIDLength()), APP_LIMIT_ARRAY_PARAMS_SIZE), 'Array of attributes to index. Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' attributes are allowed, each 32 characters long.', false, ['dbForProject']) ->param('orders', [], new ArrayList(new WhiteList(['ASC', 'DESC'], false, Database::VAR_STRING), APP_LIMIT_ARRAY_PARAMS_SIZE), 'Array of index orders. Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' orders are allowed.', true) ->param('lengths', [], new ArrayList(new Nullable(new Integer()), APP_LIMIT_ARRAY_PARAMS_SIZE), 'Length of index. Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE, optional: true) From 4e71a54faefb891052910039c2b3f4b8a5aaf14f Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 31 Mar 2026 14:44:20 +1300 Subject: [PATCH 03/18] (fix): send SSE done event before tracking to prevent installer hang --- .../Installer/Http/Installer/Install.php | 40 ++++++++++++------- src/Appwrite/Platform/Tasks/Install.php | 25 +++++++++--- 2 files changed, 45 insertions(+), 20 deletions(-) diff --git a/src/Appwrite/Platform/Installer/Http/Installer/Install.php b/src/Appwrite/Platform/Installer/Http/Installer/Install.php index e29222a703..fa978892d3 100644 --- a/src/Appwrite/Platform/Installer/Http/Installer/Install.php +++ b/src/Appwrite/Platform/Installer/Http/Installer/Install.php @@ -321,6 +321,28 @@ class Install extends Action } }; + $responseSent = false; + $onComplete = function () use ($wantsStream, $swooleResponse, $response, $installId, $state, &$responseSent) { + if ($responseSent) { + return; + } + $responseSent = true; + $state->updateGlobalLock($installId, Server::STATUS_COMPLETED); + if ($wantsStream) { + $this->writeSseEvent($swooleResponse, 'done', ['installId' => $installId, 'success' => true]); + usleep(self::SSE_KEEPALIVE_DELAY_MICROSECONDS); + $swooleResponse->write(": keepalive\n\n"); + usleep(self::SSE_KEEPALIVE_DELAY_MICROSECONDS); + $swooleResponse->end(); + } else { + $response->json([ + 'success' => true, + 'installId' => $installId, + 'message' => 'Installation completed successfully', + ]); + } + }; + $installer->performInstallation( $httpPort ?: $config->getDefaultHttpPort(), $httpsPort ?: $config->getDefaultHttpsPort(), @@ -331,23 +353,11 @@ class Install extends Action $progress, $retryStep, $config->isUpgrade(), - $account + $account, + $onComplete, ); - if ($wantsStream) { - $this->writeSseEvent($swooleResponse, 'done', ['installId' => $installId, 'success' => true]); - usleep(self::SSE_KEEPALIVE_DELAY_MICROSECONDS); - $swooleResponse->write(": keepalive\n\n"); - usleep(self::SSE_KEEPALIVE_DELAY_MICROSECONDS); - $swooleResponse->end(); - } else { - $response->json([ - 'success' => true, - 'installId' => $installId, - 'message' => 'Installation completed successfully', - ]); - } - $state->updateGlobalLock($installId, Server::STATUS_COMPLETED); + $onComplete(); } catch (\Throwable $e) { $this->handleInstallationError($e, $installId, $wantsStream, $response, $swooleResponse, $state); } diff --git a/src/Appwrite/Platform/Tasks/Install.php b/src/Appwrite/Platform/Tasks/Install.php index eab6babc66..70862568b0 100644 --- a/src/Appwrite/Platform/Tasks/Install.php +++ b/src/Appwrite/Platform/Tasks/Install.php @@ -510,7 +510,8 @@ class Install extends Action ?callable $progress = null, ?string $resumeFromStep = null, bool $isUpgrade = false, - array $account = [] + array $account = [], + ?callable $onComplete = null, ): void { $isLocalInstall = $this->isLocalInstall(); $this->applyLocalPaths($isLocalInstall, false); @@ -633,8 +634,20 @@ class Install extends Action $this->createInitialAdminAccount($account, $progress, $apiUrl, $domain); } - // Track installs - $this->trackSelfHostedInstall($input, $isUpgrade, $version, $account); + // Signal completion before tracking so the SSE stream + // finishes and the frontend can redirect immediately. + // Tracking is best-effort and must never block the user. + if ($onComplete) { + try { + $onComplete(); + } catch (\Throwable) { + } + } + + try { + $this->trackSelfHostedInstall($input, $isUpgrade, $version, $account); + } catch (\Throwable) { + } if ($isCLI) { Console::success('Appwrite installed successfully'); @@ -753,7 +766,7 @@ class Install extends Action $name = $account['name'] ?? 'Admin'; $email = $account['email'] ?? 'admin@selfhosted.local'; - $hostIp = gethostbyname($domain); + $hostIp = @gethostbyname($domain); $payload = [ 'action' => $type, @@ -767,7 +780,7 @@ class Install extends Action 'email' => $email, 'domain' => $domain, 'database' => $database, - 'hostIp' => $hostIp !== $domain ? $hostIp : null, + 'hostIp' => ($hostIp !== false && $hostIp !== $domain) ? $hostIp : null, 'os' => php_uname('s') . ' ' . php_uname('r'), 'arch' => php_uname('m'), 'cpus' => ((int) trim((string) \shell_exec('nproc'))) ?: null, @@ -778,6 +791,8 @@ class Install extends Action try { $client = new Client(); $client + ->setConnectTimeout(5000) + ->setTimeout(5000) ->addHeader('Content-Type', 'application/json') ->fetch(self::GROWTH_API_URL . '/analytics', Client::METHOD_POST, $payload); } catch (\Throwable) { From dfb23612b0173aed5367077ef255f2ae88ab5363 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 31 Mar 2026 14:44:24 +1300 Subject: [PATCH 04/18] (docs): rewrite AGENTS.md with module structure and action patterns --- AGENTS.md | 185 +++++++++++++++++++++++++++++------------------------- 1 file changed, 99 insertions(+), 86 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bb24d9f4fe..4d11ff0ee3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,107 +1,120 @@ -# AGENTS.md +# Appwrite -Appwrite is an end-to-end backend server for web, mobile, native, and backend apps. This guide provides context and instructions for AI coding agents working on the Appwrite codebase. +Self-hosted Backend-as-a-Service platform. Hybrid monolithic-microservice architecture built with PHP 8.3+ on Swoole, delivered as Docker containers. -## Project Overview +## Commands -Appwrite is a self-hosted Backend-as-a-Service (BaaS) platform that provides developers with a set of APIs and tools to build secure, scalable applications. The project uses a hybrid monolithic-microservice architecture built with PHP, running on Swoole for high performance. +| Command | Purpose | +|---------|---------| +| `docker compose up -d --force-recreate --build` | Build and start all services | +| `docker compose exec appwrite test tests/e2e/Services/[Service]` | Run E2E tests for a service | +| `docker compose exec appwrite test tests/e2e/Services/[Service] --filter=[Method]` | Run a single test method | +| `docker compose exec appwrite test tests/unit/` | Run unit tests | +| `composer format` | Auto-format code (Pint, PSR-12) | +| `composer format ` | Format a specific file | +| `composer lint ` | Check formatting of a file | +| `composer analyze` | Static analysis (PHPStan level 3) | +| `composer check` | Same as `analyze` | -**Key Technologies:** -- **Backend:** PHP 8.3+, Swoole -- **Libraries:** Utopia PHP -- **Database:** MariaDB, Redis -- **Cache:** Redis -- **Queue:** Redis -- **Containers:** Docker +## Stack -## Development Commands +- PHP 8.3+, Swoole 6.x (async runtime, replaces PHP-FPM) +- Utopia PHP framework (HTTP routing, CLI, DI, queue) +- MongoDB (default), MariaDB, MySQL, PostgreSQL (adapters via utopia-php/database) +- Redis (cache, queue, pub/sub) +- Docker + Traefik (reverse proxy) +- PHPUnit 12, Pint (PSR-12), PHPStan level 3 -```bash -# Run Appwrite -docker compose up -d --force-recreate --build +## Project layout -# Run specific test -docker compose exec appwrite test /usr/src/code/tests/e2e/Services/[ServiceName] --filter=[FunctionName] +- **src/Appwrite/Platform/Modules/** -- feature modules (Account, Avatars, Compute, Console, Databases, Functions, Health, Project, Projects, Proxy, Sites, Storage, Teams, Tokens, VCS, Webhooks) +- **src/Appwrite/Platform/Workers/** -- background job workers +- **src/Appwrite/Platform/Tasks/** -- CLI tasks +- **app/init.php** -- bootstrap (registers services, resources, listeners) +- **app/init/** -- configs, constants, locales, models, registers, resources, span, database filters/formats +- **bin/** -- CLI entry points: `worker-*` (14 workers), `schedule-*`, `queue-*`, plus `doctor`, `install`, `migrate`, `realtime`, `upgrade`, `ssl`, `vars`, `maintenance`, `interval`, `specs`, `sdks`, etc. +- **tests/e2e/** -- end-to-end tests per service +- **tests/unit/** -- unit tests +- **public/** -- static assets and generated SDKs -# Format code -composer format +## Module structure + +Each module under `src/Appwrite/Platform/Modules/{Name}/` contains: + +``` +Module.php -- registers all services for the module +Services/Http.php -- registers HTTP endpoints +Services/Workers.php -- registers background workers +Services/Tasks.php -- registers CLI tasks +Http/{Service}/ -- endpoint actions (Create.php, Get.php, Update.php, Delete.php, XList.php) +Workers/ -- worker implementations +Tasks/ -- CLI task implementations ``` -## Code Style Guidelines +HTTP endpoint nesting reflects the URL path. Sub-resources get subdirectories. For example, within the Functions module: +`Http/Deployments/Template/Create.php` -> `POST /v1/functions/:functionId/deployments/template` -- Follow [PSR-12](https://www.php-fig.org/psr/psr-12/) coding standard -- Use PSR-4 autoloading -- Strict type declarations where applicable -- Comprehensive PHPDoc comments +File names in Http directories must only be `Get.php`, `Create.php`, `Update.php`, `Delete.php`, or `XList.php`. For non-CRUD operations, model the endpoint as a property update. For example, updating a team membership status lives at `Teams/Http/Memberships/Status/Update.php` (`PATCH /v1/teams/:teamId/memberships/:membershipId/status`). -### Naming Conventions +Register new modules in `src/Appwrite/Platform/Appwrite.php`. Detailed module guide: `src/Appwrite/Platform/AGENTS.md`. -#### `resourceType` Naming Rule +## Action pattern (HTTP endpoints) -When a collection has a combination of `resourceType`, `resourceId`, and/or `resourceInternalId`, the value of `resourceType` MUST always be **plural** - for example: `functions`, `sites`, `deployments`. - -Examples: ```php -'resourceType' => 'functions' -'resourceType' => 'sites' -'resourceType' => 'deployments' +class Create extends Action +{ + public static function getName(): string { return 'createTeam'; } + + public function __construct() + { + $this + ->setHttpMethod(Action::HTTP_REQUEST_METHOD_POST) + ->setHttpPath('/v1/teams') + ->desc('Create team') + ->groups(['api', 'teams']) + ->label('event', 'teams.[teamId].create') + ->label('scope', 'teams.write') + ->param('teamId', '', new CustomId(), 'Team ID.') + ->param('name', null, new Text(128), 'Team name.') + ->inject('response') + ->inject('dbForProject') + ->inject('queueForEvents') + ->callback($this->action(...)); + } + + public function action( + string $teamId, + string $name, + Response $response, + Database $dbForProject, + Event $queueForEvents, + ): void { + // implementation + } +} ``` -## Performance Patterns +Common injections: `$response`, `$request`, `$dbForProject`, `$dbForPlatform`, `$user`, `$project`, `$queueForEvents`, `$queueForMails`, `$queueForDeletes`. -### Document Update Optimization +## Conventions -When updating documents, always pass only the changed attributes as a sparse `Document` rather than the full document. This is more efficient because `updateDocument()` internally performs `array_merge($old, $new)`. +- PSR-12 formatting enforced by Pint. PSR-4 autoloading. +- `resourceType` values are always **plural**: `'functions'`, `'sites'`, `'deployments'`. +- When updating documents, pass only changed attributes as a sparse Document: + ```php + // correct + $dbForProject->updateDocument('users', $user->getId(), new Document([ + 'name' => $name, + ])); + // incorrect -- passing full document is inefficient + $user->setAttribute('name', $name); + $dbForProject->updateDocument('users', $user->getId(), $user); + ``` + Exceptions: migrations, `array_merge()` with `getArrayCopy()`, updates where nearly all attributes change, complex nested relationship logic requiring full document state. +- Avoid introducing dependencies outside the `utopia-php` ecosystem. +- Never hardcode credentials -- use environment variables. +- Code changes may require container restart. No central log location -- check relevant containers. -**Correct Pattern:** -```php -// Good: Pass only changed attributes directly -$user = $dbForProject->updateDocument('users', $user->getId(), new Document([ - 'name' => $name, - 'email' => $email, -])); -``` +## Cross-repo context -**Incorrect Pattern:** -```php -$user->setAttribute('name', $name); -$user->setAttribute('email', $email); - -// Bad: Passing full document is inefficient -$user = $dbForProject->updateDocument('users', $user->getId(), $user); -``` - -**Exceptions:** -- Migration files (need full document updates by design) -- Cases already using `array_merge()` with `getArrayCopy()` -- Updates where almost all attributes of the document change at once (sparse update provides little benefit compared to passing the full document) -- Complex nested relationship logic where full document state is required - -## Security Considerations - -### Critical Security Practices - -- **Never hardcode credentials** - Use environment variables -- **Rate limiting** - Respect abuse prevention mechanisms - -## Dependencies - -Avoid introducing new dependencies other than utopia-php. - -## Adding new endpoints - -When adding new endpoints, make sure to use modules and follow its patterns. Find instruction in [Modules AGENTS.md](src/Appwrite/Platform/AGENTS.md) file. - -## Pull Request Guidelines -### Before Submitting - -- Run `composer format` -- Update documentation if adding features -- Add/update tests for your changes -- Check that Docker build succeeds -`docs/specs/authentication.drawio.svg` - -## Known Issues and Gotchas - -- **Hot Reload:** Code changes require container restart in some cases -- **Logging:** There is no central place for logs, so when debugging, ensure to check all possibly relevant containers +Appwrite is the base server for `appwrite/cloud`. Changes to the Action pattern, module structure, DI system, or response models affect cloud. The `feat-dedicated-db` feature spans cloud, edge, and console. From 7bcd5b4ebca914b3e0561701b1bb3d40c25fcf31 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 31 Mar 2026 14:46:04 +1300 Subject: [PATCH 05/18] (fix): remove swallowed exception around tracking call --- src/Appwrite/Platform/Tasks/Install.php | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/src/Appwrite/Platform/Tasks/Install.php b/src/Appwrite/Platform/Tasks/Install.php index 70862568b0..2896ce98c4 100644 --- a/src/Appwrite/Platform/Tasks/Install.php +++ b/src/Appwrite/Platform/Tasks/Install.php @@ -636,7 +636,6 @@ class Install extends Action // Signal completion before tracking so the SSE stream // finishes and the frontend can redirect immediately. - // Tracking is best-effort and must never block the user. if ($onComplete) { try { $onComplete(); @@ -644,10 +643,7 @@ class Install extends Action } } - try { - $this->trackSelfHostedInstall($input, $isUpgrade, $version, $account); - } catch (\Throwable) { - } + $this->trackSelfHostedInstall($input, $isUpgrade, $version, $account); if ($isCLI) { Console::success('Appwrite installed successfully'); From a955dff55a5ecdf25c87db92ad47e1e39e1e4431 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 31 Mar 2026 14:49:04 +1300 Subject: [PATCH 06/18] (fix): run install tracking in coroutine to avoid blocking worker --- src/Appwrite/Platform/Installer/Server.php | 3 +++ src/Appwrite/Platform/Tasks/Install.php | 13 ++++++++++++- 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/src/Appwrite/Platform/Installer/Server.php b/src/Appwrite/Platform/Installer/Server.php index 17edfaac72..8996b9a4c3 100644 --- a/src/Appwrite/Platform/Installer/Server.php +++ b/src/Appwrite/Platform/Installer/Server.php @@ -6,6 +6,7 @@ use Appwrite\Platform\Installer\Http\Installer\Error; use Appwrite\Platform\Installer\Runtime\Config; use Appwrite\Platform\Installer\Runtime\State; use Swoole\Http\Server as SwooleServer; +use Swoole\Runtime; use Utopia\Http\Adapter\Swoole\Request; use Utopia\Http\Adapter\Swoole\Response; use Utopia\Http\Adapter\Swoole\Server as SwooleAdapter; @@ -129,6 +130,8 @@ class Server private function startSwooleServer(string $host, int $port, ?string $readyFile = null): void { + Runtime::enableCoroutine(SWOOLE_HOOK_ALL); + $this->state->clearStaleLock(); // Preload static files into memory diff --git a/src/Appwrite/Platform/Tasks/Install.php b/src/Appwrite/Platform/Tasks/Install.php index 2896ce98c4..418bd06a08 100644 --- a/src/Appwrite/Platform/Tasks/Install.php +++ b/src/Appwrite/Platform/Tasks/Install.php @@ -7,6 +7,7 @@ use Appwrite\Docker\Env; use Appwrite\Platform\Installer\Runtime\State; use Appwrite\Platform\Installer\Server as InstallerServer; use Appwrite\Utopia\View; +use Swoole\Coroutine; use Utopia\Auth\Proofs\Password; use Utopia\Auth\Proofs\Token; use Utopia\Config\Config; @@ -643,7 +644,17 @@ class Install extends Action } } - $this->trackSelfHostedInstall($input, $isUpgrade, $version, $account); + // Run tracking in a coroutine (web installer) so it + // doesn't block the worker. Safe because the installer + // has no shared mutable state across requests. + // CLI runs synchronously. + if (!$isCLI && Coroutine::getCid() !== -1) { + go(function () use ($input, $isUpgrade, $version, $account) { + $this->trackSelfHostedInstall($input, $isUpgrade, $version, $account); + }); + } else { + $this->trackSelfHostedInstall($input, $isUpgrade, $version, $account); + } if ($isCLI) { Console::success('Appwrite installed successfully'); From c7c59f4e7b7d2f9c7964f603934743db82f865e4 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 31 Mar 2026 15:04:04 +1300 Subject: [PATCH 07/18] Fix key --- src/Appwrite/Platform/Tasks/Install.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Appwrite/Platform/Tasks/Install.php b/src/Appwrite/Platform/Tasks/Install.php index 418bd06a08..7bc2f4d6e1 100644 --- a/src/Appwrite/Platform/Tasks/Install.php +++ b/src/Appwrite/Platform/Tasks/Install.php @@ -787,7 +787,7 @@ class Install extends Action 'email' => $email, 'domain' => $domain, 'database' => $database, - 'hostIp' => ($hostIp !== false && $hostIp !== $domain) ? $hostIp : null, + 'ip' => ($hostIp !== false && $hostIp !== $domain) ? $hostIp : null, 'os' => php_uname('s') . ' ' . php_uname('r'), 'arch' => php_uname('m'), 'cpus' => ((int) trim((string) \shell_exec('nproc'))) ?: null, From 8b7459f634694c1c996b7f4c9850cf5108697fe4 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 31 Mar 2026 15:15:51 +1300 Subject: [PATCH 08/18] =?UTF-8?q?(fix):=20address=20review=20comments=20?= =?UTF-8?q?=E2=80=94=20coroutine=20guard=20and=20hostIp=20key?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/Appwrite/Platform/Tasks/Install.php | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/src/Appwrite/Platform/Tasks/Install.php b/src/Appwrite/Platform/Tasks/Install.php index 971831bb4b..832e70fe05 100644 --- a/src/Appwrite/Platform/Tasks/Install.php +++ b/src/Appwrite/Platform/Tasks/Install.php @@ -645,11 +645,9 @@ class Install extends Action } } - // Run tracking in a coroutine (web installer) so it - // doesn't block the worker. Safe because the installer - // has no shared mutable state across requests. - // CLI runs synchronously. - if (!$isCLI && Coroutine::getCid() !== -1) { + // Run tracking in a coroutine when inside a Swoole + // request so it doesn't block the worker. + if (Coroutine::getCid() !== -1) { go(function () use ($input, $isUpgrade, $version, $account) { $this->trackSelfHostedInstall($input, $isUpgrade, $version, $account); }); @@ -788,7 +786,7 @@ class Install extends Action 'email' => $email, 'domain' => $domain, 'database' => $database, - 'ip' => ($hostIp !== false && $hostIp !== $domain) ? $hostIp : null, + 'hostIp' => ($hostIp !== false && $hostIp !== $domain) ? $hostIp : null, 'os' => php_uname('s') . ' ' . php_uname('r'), 'arch' => php_uname('m'), 'cpus' => ((int) trim((string) \shell_exec('nproc'))) ?: null, From 02d234ad3a4b68be80fff6aa5eb6237ec9267d44 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 31 Mar 2026 15:58:41 +1300 Subject: [PATCH 09/18] (fix): detect existing installation as upgrade for web installer --- src/Appwrite/Platform/Tasks/Install.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Appwrite/Platform/Tasks/Install.php b/src/Appwrite/Platform/Tasks/Install.php index 832e70fe05..95f2be521a 100644 --- a/src/Appwrite/Platform/Tasks/Install.php +++ b/src/Appwrite/Platform/Tasks/Install.php @@ -219,7 +219,7 @@ class Install extends Action Console::info('Press Ctrl+C to cancel installation'); $detectedDb = ($existingInstallation && isset($existingDatabase)) ? $existingDatabase : null; - $this->startWebServer($defaultHttpPort, $defaultHttpsPort, $organization, $image, $noStart, $vars, $isUpgrade, $detectedDb); + $this->startWebServer($defaultHttpPort, $defaultHttpsPort, $organization, $image, $noStart, $vars, $isUpgrade || $existingInstallation, $detectedDb); return; } From 5c84efdd7cd37b1433c4193fdda3774259933d4e Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 31 Mar 2026 15:58:45 +1300 Subject: [PATCH 10/18] =?UTF-8?q?(fix):=20upgrade=20UI=20=E2=80=94=20remov?= =?UTF-8?q?e=20min-height,=20hide=20secret=20key=20row,=20fix=20copy?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- app/views/install/installer/css/styles.css | 4 ++++ app/views/install/installer/templates/steps/step-4.phtml | 2 ++ app/views/install/installer/templates/steps/step-5.phtml | 2 +- 3 files changed, 7 insertions(+), 1 deletion(-) diff --git a/app/views/install/installer/css/styles.css b/app/views/install/installer/css/styles.css index 7f253eed46..eedce90834 100644 --- a/app/views/install/installer/css/styles.css +++ b/app/views/install/installer/css/styles.css @@ -478,6 +478,10 @@ body { overflow: hidden; } +.installer-page[data-upgrade='true'] .installer-step { + min-height: 0; +} + .action-shell { display: flex; flex-direction: column; diff --git a/app/views/install/installer/templates/steps/step-4.phtml b/app/views/install/installer/templates/steps/step-4.phtml index 07dc865257..8468de30f4 100644 --- a/app/views/install/installer/templates/steps/step-4.phtml +++ b/app/views/install/installer/templates/steps/step-4.phtml @@ -62,12 +62,14 @@ $badgeClass = $defaultSecretKey !== '' ? 'badge-success' : 'badge-warning'; Disabled
Appwrite Assistant
+
Secret API key
+ diff --git a/app/views/install/installer/templates/steps/step-5.phtml b/app/views/install/installer/templates/steps/step-5.phtml index cd5de5f4ab..c18c3ea748 100644 --- a/app/views/install/installer/templates/steps/step-5.phtml +++ b/app/views/install/installer/templates/steps/step-5.phtml @@ -6,7 +6,7 @@ $isUpgrade = $isUpgrade ?? false;
- +
From fe6f79c9c654a62471598acaba3d97cc33d474d6 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 31 Mar 2026 16:02:22 +1300 Subject: [PATCH 11/18] (fix): restore ip key in tracking payload --- src/Appwrite/Platform/Tasks/Install.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Appwrite/Platform/Tasks/Install.php b/src/Appwrite/Platform/Tasks/Install.php index 95f2be521a..a1cc1d094e 100644 --- a/src/Appwrite/Platform/Tasks/Install.php +++ b/src/Appwrite/Platform/Tasks/Install.php @@ -786,7 +786,7 @@ class Install extends Action 'email' => $email, 'domain' => $domain, 'database' => $database, - 'hostIp' => ($hostIp !== false && $hostIp !== $domain) ? $hostIp : null, + 'ip' => ($hostIp !== false && $hostIp !== $domain) ? $hostIp : null, 'os' => php_uname('s') . ' ' . php_uname('r'), 'arch' => php_uname('m'), 'cpus' => ((int) trim((string) \shell_exec('nproc'))) ?: null, From 4e32497be1ca26fe23cb04d161365984aef6f0e0 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 31 Mar 2026 16:26:20 +1300 Subject: [PATCH 12/18] (fix): increase GraphQL schema polling timeouts to match CI expectations Co-Authored-By: Claude Opus 4.6 (1M context) --- tests/e2e/Services/GraphQL/Legacy/AbuseTest.php | 2 +- tests/e2e/Services/GraphQL/Legacy/AuthTest.php | 2 +- .../e2e/Services/GraphQL/Legacy/DatabaseClientTest.php | 10 +++++----- tests/e2e/Services/GraphQL/TablesDB/AbuseTest.php | 2 +- tests/e2e/Services/GraphQL/TablesDB/AuthTest.php | 2 +- .../Services/GraphQL/TablesDB/DatabaseClientTest.php | 6 +++--- 6 files changed, 12 insertions(+), 12 deletions(-) diff --git a/tests/e2e/Services/GraphQL/Legacy/AbuseTest.php b/tests/e2e/Services/GraphQL/Legacy/AbuseTest.php index dfec046f55..46f39791a7 100644 --- a/tests/e2e/Services/GraphQL/Legacy/AbuseTest.php +++ b/tests/e2e/Services/GraphQL/Legacy/AbuseTest.php @@ -182,7 +182,7 @@ class AbuseTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ]); $this->assertEquals('available', $response['body']['status']); - }, 30000, 250); + }, 240000, 500); return [ 'databaseId' => $databaseId, diff --git a/tests/e2e/Services/GraphQL/Legacy/AuthTest.php b/tests/e2e/Services/GraphQL/Legacy/AuthTest.php index 4a3e49cc60..847a6d8820 100644 --- a/tests/e2e/Services/GraphQL/Legacy/AuthTest.php +++ b/tests/e2e/Services/GraphQL/Legacy/AuthTest.php @@ -149,7 +149,7 @@ class AuthTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ]); $this->assertEquals('available', $response['body']['status']); - }, 30000, 250); + }, 240000, 500); } public function testInvalidAuth() diff --git a/tests/e2e/Services/GraphQL/Legacy/DatabaseClientTest.php b/tests/e2e/Services/GraphQL/Legacy/DatabaseClientTest.php index 4d34dc6b23..4513644688 100644 --- a/tests/e2e/Services/GraphQL/Legacy/DatabaseClientTest.php +++ b/tests/e2e/Services/GraphQL/Legacy/DatabaseClientTest.php @@ -218,7 +218,7 @@ class DatabaseClientTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ]); $this->assertEquals('available', $response['body']['status']); - }, 30000, 250); + }, 240000, 500); $this->assertEventually(function () use ($data) { $response = $this->client->call(Client::METHOD_GET, '/databases/' . $data['database']['_id'] . '/collections/' . $data['collection']['_id'] . '/attributes/age', [ 'content-type' => 'application/json', @@ -226,7 +226,7 @@ class DatabaseClientTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ]); $this->assertEquals('available', $response['body']['status']); - }, 30000, 250); + }, 240000, 500); $projectId = $this->getProject()['$id']; $query = $this->getQuery(self::CREATE_DOCUMENT); @@ -333,7 +333,7 @@ class DatabaseClientTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ]); $this->assertEquals('available', $response['body']['status']); - }, 30000, 250); + }, 240000, 500); // Step 4: Create documents $query = $this->getQuery(self::CREATE_DOCUMENTS); @@ -635,7 +635,7 @@ class DatabaseClientTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ]); $this->assertEquals('available', $response['body']['status']); - }, 30000, 250); + }, 240000, 500); $this->assertEventually(function () use ($data) { $response = $this->client->call(Client::METHOD_GET, '/databases/' . $data['database']['_id'] . '/collections/' . $data['collection']['_id'] . '/attributes/age', [ 'content-type' => 'application/json', @@ -643,7 +643,7 @@ class DatabaseClientTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ]); $this->assertEquals('available', $response['body']['status']); - }, 30000, 250); + }, 240000, 500); $projectId = $this->getProject()['$id']; diff --git a/tests/e2e/Services/GraphQL/TablesDB/AbuseTest.php b/tests/e2e/Services/GraphQL/TablesDB/AbuseTest.php index 05185149fd..74ec12e623 100644 --- a/tests/e2e/Services/GraphQL/TablesDB/AbuseTest.php +++ b/tests/e2e/Services/GraphQL/TablesDB/AbuseTest.php @@ -182,7 +182,7 @@ class AbuseTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ])); $this->assertEquals('available', $response['body']['status']); - }, 30000, 250); + }, 240000, 500); return [ 'databaseId' => $databaseId, diff --git a/tests/e2e/Services/GraphQL/TablesDB/AuthTest.php b/tests/e2e/Services/GraphQL/TablesDB/AuthTest.php index 9c6910fb30..a798a4451f 100644 --- a/tests/e2e/Services/GraphQL/TablesDB/AuthTest.php +++ b/tests/e2e/Services/GraphQL/TablesDB/AuthTest.php @@ -150,7 +150,7 @@ class AuthTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ])); $this->assertEquals('available', $response['body']['status']); - }, 30000, 250); + }, 240000, 500); } public function testInvalidAuth() diff --git a/tests/e2e/Services/GraphQL/TablesDB/DatabaseClientTest.php b/tests/e2e/Services/GraphQL/TablesDB/DatabaseClientTest.php index 9a39db88f3..370aac2f12 100644 --- a/tests/e2e/Services/GraphQL/TablesDB/DatabaseClientTest.php +++ b/tests/e2e/Services/GraphQL/TablesDB/DatabaseClientTest.php @@ -217,7 +217,7 @@ class DatabaseClientTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ])); $this->assertEquals('available', $response['body']['status']); - }, 30000, 250); + }, 240000, 500); } $projectId = $this->getProject()['$id']; @@ -330,7 +330,7 @@ class DatabaseClientTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ])); $this->assertEquals('available', $response['body']['status']); - }, 30000, 250); + }, 240000, 500); // Step 4: Create rows $query = $this->getQuery(self::CREATE_ROWS); @@ -623,7 +623,7 @@ class DatabaseClientTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ])); $this->assertEquals('available', $response['body']['status']); - }, 30000, 250); + }, 240000, 500); } $projectId = $this->getProject()['$id']; From 7e49cf0bed203bd8724df28f5e72534b0e98b66e Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 31 Mar 2026 16:48:32 +1300 Subject: [PATCH 13/18] Revert "(fix): increase GraphQL schema polling timeouts to match CI expectations" This reverts commit 4e32497be1ca26fe23cb04d161365984aef6f0e0. --- tests/e2e/Services/GraphQL/Legacy/AbuseTest.php | 2 +- tests/e2e/Services/GraphQL/Legacy/AuthTest.php | 2 +- .../e2e/Services/GraphQL/Legacy/DatabaseClientTest.php | 10 +++++----- tests/e2e/Services/GraphQL/TablesDB/AbuseTest.php | 2 +- tests/e2e/Services/GraphQL/TablesDB/AuthTest.php | 2 +- .../Services/GraphQL/TablesDB/DatabaseClientTest.php | 6 +++--- 6 files changed, 12 insertions(+), 12 deletions(-) diff --git a/tests/e2e/Services/GraphQL/Legacy/AbuseTest.php b/tests/e2e/Services/GraphQL/Legacy/AbuseTest.php index 46f39791a7..dfec046f55 100644 --- a/tests/e2e/Services/GraphQL/Legacy/AbuseTest.php +++ b/tests/e2e/Services/GraphQL/Legacy/AbuseTest.php @@ -182,7 +182,7 @@ class AbuseTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ]); $this->assertEquals('available', $response['body']['status']); - }, 240000, 500); + }, 30000, 250); return [ 'databaseId' => $databaseId, diff --git a/tests/e2e/Services/GraphQL/Legacy/AuthTest.php b/tests/e2e/Services/GraphQL/Legacy/AuthTest.php index 847a6d8820..4a3e49cc60 100644 --- a/tests/e2e/Services/GraphQL/Legacy/AuthTest.php +++ b/tests/e2e/Services/GraphQL/Legacy/AuthTest.php @@ -149,7 +149,7 @@ class AuthTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ]); $this->assertEquals('available', $response['body']['status']); - }, 240000, 500); + }, 30000, 250); } public function testInvalidAuth() diff --git a/tests/e2e/Services/GraphQL/Legacy/DatabaseClientTest.php b/tests/e2e/Services/GraphQL/Legacy/DatabaseClientTest.php index 4513644688..4d34dc6b23 100644 --- a/tests/e2e/Services/GraphQL/Legacy/DatabaseClientTest.php +++ b/tests/e2e/Services/GraphQL/Legacy/DatabaseClientTest.php @@ -218,7 +218,7 @@ class DatabaseClientTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ]); $this->assertEquals('available', $response['body']['status']); - }, 240000, 500); + }, 30000, 250); $this->assertEventually(function () use ($data) { $response = $this->client->call(Client::METHOD_GET, '/databases/' . $data['database']['_id'] . '/collections/' . $data['collection']['_id'] . '/attributes/age', [ 'content-type' => 'application/json', @@ -226,7 +226,7 @@ class DatabaseClientTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ]); $this->assertEquals('available', $response['body']['status']); - }, 240000, 500); + }, 30000, 250); $projectId = $this->getProject()['$id']; $query = $this->getQuery(self::CREATE_DOCUMENT); @@ -333,7 +333,7 @@ class DatabaseClientTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ]); $this->assertEquals('available', $response['body']['status']); - }, 240000, 500); + }, 30000, 250); // Step 4: Create documents $query = $this->getQuery(self::CREATE_DOCUMENTS); @@ -635,7 +635,7 @@ class DatabaseClientTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ]); $this->assertEquals('available', $response['body']['status']); - }, 240000, 500); + }, 30000, 250); $this->assertEventually(function () use ($data) { $response = $this->client->call(Client::METHOD_GET, '/databases/' . $data['database']['_id'] . '/collections/' . $data['collection']['_id'] . '/attributes/age', [ 'content-type' => 'application/json', @@ -643,7 +643,7 @@ class DatabaseClientTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ]); $this->assertEquals('available', $response['body']['status']); - }, 240000, 500); + }, 30000, 250); $projectId = $this->getProject()['$id']; diff --git a/tests/e2e/Services/GraphQL/TablesDB/AbuseTest.php b/tests/e2e/Services/GraphQL/TablesDB/AbuseTest.php index 74ec12e623..05185149fd 100644 --- a/tests/e2e/Services/GraphQL/TablesDB/AbuseTest.php +++ b/tests/e2e/Services/GraphQL/TablesDB/AbuseTest.php @@ -182,7 +182,7 @@ class AbuseTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ])); $this->assertEquals('available', $response['body']['status']); - }, 240000, 500); + }, 30000, 250); return [ 'databaseId' => $databaseId, diff --git a/tests/e2e/Services/GraphQL/TablesDB/AuthTest.php b/tests/e2e/Services/GraphQL/TablesDB/AuthTest.php index a798a4451f..9c6910fb30 100644 --- a/tests/e2e/Services/GraphQL/TablesDB/AuthTest.php +++ b/tests/e2e/Services/GraphQL/TablesDB/AuthTest.php @@ -150,7 +150,7 @@ class AuthTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ])); $this->assertEquals('available', $response['body']['status']); - }, 240000, 500); + }, 30000, 250); } public function testInvalidAuth() diff --git a/tests/e2e/Services/GraphQL/TablesDB/DatabaseClientTest.php b/tests/e2e/Services/GraphQL/TablesDB/DatabaseClientTest.php index 370aac2f12..9a39db88f3 100644 --- a/tests/e2e/Services/GraphQL/TablesDB/DatabaseClientTest.php +++ b/tests/e2e/Services/GraphQL/TablesDB/DatabaseClientTest.php @@ -217,7 +217,7 @@ class DatabaseClientTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ])); $this->assertEquals('available', $response['body']['status']); - }, 240000, 500); + }, 30000, 250); } $projectId = $this->getProject()['$id']; @@ -330,7 +330,7 @@ class DatabaseClientTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ])); $this->assertEquals('available', $response['body']['status']); - }, 240000, 500); + }, 30000, 250); // Step 4: Create rows $query = $this->getQuery(self::CREATE_ROWS); @@ -623,7 +623,7 @@ class DatabaseClientTest extends Scope 'x-appwrite-key' => $this->getProject()['apiKey'], ])); $this->assertEquals('available', $response['body']['status']); - }, 240000, 500); + }, 30000, 250); } $projectId = $this->getProject()['$id']; From 1fa1aa862191262cc2c1f2c885fe7f49845c87af Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 31 Mar 2026 20:58:22 +1300 Subject: [PATCH 14/18] (fix): guard against missing Host header in dispatch --- app/http.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/http.php b/app/http.php index 517a1aa544..1742bc7cdd 100644 --- a/app/http.php +++ b/app/http.php @@ -103,7 +103,7 @@ function dispatch(Server $server, int $fd, int $type, $data = null): int $lines = explode("\n", $data, 3); $request = $lines[0]; if (count($lines) > 1) { - $domain = trim(explode('Host: ', $lines[1])[1]); + $domain = trim(explode('Host: ', $lines[1])[1] ?? ''); } // Sync executions are considered risky From 2f53d09c5b679d68bed17721b209f6e5a12de327 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 31 Mar 2026 20:58:33 +1300 Subject: [PATCH 15/18] (feat): add database migration step to upgrade installer --- app/views/install/installer.phtml | 2 +- app/views/install/installer/css/styles.css | 89 +++++++++++++++++++ app/views/install/installer/js/installer.js | 4 +- .../install/installer/js/modules/context.js | 8 +- .../install/installer/js/modules/progress.js | 20 ++++- app/views/install/installer/js/steps.js | 25 ++++++ .../installer/templates/steps/step-6.phtml | 37 ++++++++ .../Installer/Http/Installer/Install.php | 3 + .../Installer/Http/Installer/View.php | 7 +- src/Appwrite/Platform/Installer/Server.php | 1 + src/Appwrite/Platform/Tasks/Install.php | 51 +++++++++++ .../Platform/Modules/Installer/ModuleTest.php | 2 +- 12 files changed, 238 insertions(+), 11 deletions(-) create mode 100644 app/views/install/installer/templates/steps/step-6.phtml diff --git a/app/views/install/installer.phtml b/app/views/install/installer.phtml index 05bc1b80ed..d33838c8c6 100644 --- a/app/views/install/installer.phtml +++ b/app/views/install/installer.phtml @@ -13,7 +13,7 @@ $enabledDatabases = $enabledDatabases ?? ['mongodb', 'mariadb', 'postgresql']; $isLocalInstall = $isLocalInstall ?? false; -$cardStep = min(4, $step); +$cardStep = ($step === 5) ? 4 : $step; $stepFile = __DIR__ . "/installer/templates/steps/step-{$cardStep}.phtml"; if (!is_file($stepFile)) { $stepFile = __DIR__ . "/installer/templates/steps/step-1.phtml"; diff --git a/app/views/install/installer/css/styles.css b/app/views/install/installer/css/styles.css index eedce90834..8fd28a12a3 100644 --- a/app/views/install/installer/css/styles.css +++ b/app/views/install/installer/css/styles.css @@ -1812,3 +1812,92 @@ body { gap: var(--gap-s); } } + +.migration-option { + display: flex; + align-items: center; + justify-content: space-between; + gap: var(--gap-l); + padding: var(--space-6); + background: var(--bgcolor-neutral-default); + border-radius: var(--border-radius-m); + outline: var(--border-width-s) solid var(--border-neutral); + outline-offset: calc(var(--border-width-s) * -1); + cursor: pointer; + transition: outline-color 0.15s ease-in-out; +} + +.migration-option:hover { + outline-color: var(--border-neutral-stronger); +} + +.migration-option-content { + display: flex; + flex-direction: column; + gap: 2px; +} + +.migration-switch { + flex-shrink: 0; +} + +.migration-switch-track { + position: relative; + display: block; + width: 32px; + height: 20px; + border-radius: 10px; + background: var(--bgcolor-neutral-invert-weaker); + transition: background 0.15s ease-in-out; +} + +.migration-switch-thumb { + position: absolute; + top: 2px; + left: 2px; + width: 16px; + height: 16px; + border-radius: 50%; + background: var(--bgcolor-neutral-primary); + transition: transform 0.15s ease-in-out; +} + +#run-migration:checked ~ .migration-switch-track { + background: var(--bgcolor-neutral-invert-weak); +} + +#run-migration:checked ~ .migration-switch-track .migration-switch-thumb { + transform: translateX(12px); +} + +#run-migration:focus-visible ~ .migration-switch-track { + box-shadow: 0 0 0 var(--border-width-l) var(--border-focus); +} + +.migration-hint { + display: flex; + align-items: flex-start; + gap: var(--gap-s); + padding: 0 var(--space-2); +} + +.migration-hint-icon { + flex-shrink: 0; + width: 16px; + height: 16px; + color: var(--fgcolor-neutral-tertiary); + margin-top: 1px; +} + +.migration-hint-icon svg { + width: 100%; + height: 100%; +} + +.migration-code { + padding: 1px 4px; + border-radius: var(--border-radius-xs, 4px); + background: var(--bgcolor-neutral-secondary); + font-family: monospace; + font-size: inherit; +} diff --git a/app/views/install/installer/js/installer.js b/app/views/install/installer/js/installer.js index 463b7f6221..4433d67b99 100644 --- a/app/views/install/installer/js/installer.js +++ b/app/views/install/installer/js/installer.js @@ -12,7 +12,7 @@ const { validateInstallRequest } = window.InstallerStepsProgress || {}; const isUpgrade = document.body?.dataset.upgrade === 'true'; - const stepFlow = isUpgrade ? [1, 4, 5] : [1, 2, 3, 4, 5]; + const stepFlow = isUpgrade ? [1, 6, 4, 5] : [1, 2, 3, 4, 5]; const cardSteps = stepFlow.filter((step) => step !== 5); const normalizeStep = (step) => { @@ -53,7 +53,7 @@ let pendingStep = null; let pendingPushState = false; - const clampStep = (step) => Math.max(1, Math.min(5, step)); + const clampStep = (step) => Math.max(1, Math.min(6, step)); const isInstallLocked = () => Boolean(window.InstallerSteps?.isInstallLocked?.()); const scrollToFirstError = (panel) => { diff --git a/app/views/install/installer/js/modules/context.js b/app/views/install/installer/js/modules/context.js index 4917a1bfe9..6f215da899 100644 --- a/app/views/install/installer/js/modules/context.js +++ b/app/views/install/installer/js/modules/context.js @@ -14,6 +14,7 @@ ENV_VARS: 'env-vars', DOCKER_CONTAINERS: 'docker-containers', ACCOUNT_SETUP: 'account-setup', + MIGRATION: 'migration', SSL_CERTIFICATE: 'ssl-certificate', REDIRECT: 'redirect' }); @@ -52,6 +53,11 @@ id: STEP_IDS.DOCKER_CONTAINERS, inProgress: 'Restarting Docker containers...', done: 'Docker containers restarted' + }, + { + id: STEP_IDS.MIGRATION, + inProgress: 'Running database migration...', + done: 'Database migration completed' } ] : [ { @@ -95,7 +101,7 @@ const clampStep = (step) => { const numeric = Number(step); if (Number.isNaN(numeric)) return 1; - return Math.max(1, Math.min(5, numeric)); + return Math.max(1, Math.min(6, numeric)); }; window.InstallerStepsContext = Object.freeze({ diff --git a/app/views/install/installer/js/modules/progress.js b/app/views/install/installer/js/modules/progress.js index d066908b03..9087a192ef 100644 --- a/app/views/install/installer/js/modules/progress.js +++ b/app/views/install/installer/js/modules/progress.js @@ -373,7 +373,8 @@ opensslKey: (formState?.opensslKey || '').trim(), assistantOpenAIKey: normalizedAssistantKey, accountEmail: normalizedAccountEmail, - accountPassword: normalizedAccountPassword + accountPassword: normalizedAccountPassword, + runMigration: formState?.runMigration ?? false }; }; @@ -1069,14 +1070,25 @@ startInstallStream(newInstallId); }; + const recoverToLastStep = () => { + clearInstallId?.(); + clearInstallLock?.(); + const url = new URL(window.location.href); + const lastStep = url.searchParams.get('step'); + // Stay on the current URL so the user keeps their place; + // only navigate away if we're already on step 5 (the + // progress screen) since there's nothing to show. + if (!lastStep || String(lastStep) === '5') { + window.location.href = '/?step=1'; + } + }; + const lock = getInstallLock?.(); const existingInstallId = lock?.installId || getStoredInstallId?.(); if (existingInstallId) { resumeInstall(existingInstallId).then((resumed) => { if (!resumed) { - clearInstallId?.(); - clearInstallLock?.(); - window.location.href = '/?step=1'; + recoverToLastStep(); } }); } else { diff --git a/app/views/install/installer/js/steps.js b/app/views/install/installer/js/steps.js index c9430b7afd..fb76b5f72d 100644 --- a/app/views/install/installer/js/steps.js +++ b/app/views/install/installer/js/steps.js @@ -329,6 +329,30 @@ } }; + const initStep6 = (root) => { + if (!root) return; + syncInstallLockFlag?.(); + applyLockPayload?.(); + applyBodyDefaults?.(); + + const checkbox = root.querySelector('#run-migration'); + if (checkbox) { + if (formState.runMigration !== undefined) { + checkbox.checked = formState.runMigration; + } else { + formState.runMigration = checkbox.checked; + } + checkbox.addEventListener('change', () => { + formState.runMigration = checkbox.checked; + dispatchStateChange?.('runMigration'); + }); + } + + if (isInstallLocked?.()) { + disableControls?.(root); + } + }; + const initStep = (step, container) => { if (!container) return; const root = container.querySelector('.step-layout') || container; @@ -346,6 +370,7 @@ if (normalized === 3) initStep3(root); if (normalized === 4) initStep4(root); if (normalized === 5) Progress.initStep5?.(root); + if (normalized === 6) initStep6(root); }; window.InstallerSteps = { diff --git a/app/views/install/installer/templates/steps/step-6.phtml b/app/views/install/installer/templates/steps/step-6.phtml new file mode 100644 index 0000000000..ca253c9907 --- /dev/null +++ b/app/views/install/installer/templates/steps/step-6.phtml @@ -0,0 +1,37 @@ + +
+
+
+

Database migration

+

+ Run database migration after the update to apply schema changes. +

+
+ +
+ + +
+ + + + + To run manually later: docker compose exec appwrite migrate + +
+
+
+
diff --git a/src/Appwrite/Platform/Installer/Http/Installer/Install.php b/src/Appwrite/Platform/Installer/Http/Installer/Install.php index fa978892d3..482a30eab4 100644 --- a/src/Appwrite/Platform/Installer/Http/Installer/Install.php +++ b/src/Appwrite/Platform/Installer/Http/Installer/Install.php @@ -43,6 +43,7 @@ class Install extends Action ->param('database', '', new WhiteList(['mongodb', 'mariadb', 'postgresql']), 'Database adapter', true) ->param('installId', '', new Text(64, 0), 'Installation ID', true) ->param('retryStep', null, new Nullable(new WhiteList([Server::STEP_DOCKER_COMPOSE, Server::STEP_ENV_VARS, Server::STEP_DOCKER_CONTAINERS], true)), 'Retry from step', true) + ->param('runMigration', false, new \Utopia\Validator\Boolean(true), 'Run database migration after upgrade', true) ->inject('request') ->inject('response') ->inject('swooleResponse') @@ -64,6 +65,7 @@ class Install extends Action string $database, string $installId, ?string $retryStep, + bool $runMigration, Request $request, Response $response, SwooleResponse $swooleResponse, @@ -355,6 +357,7 @@ class Install extends Action $config->isUpgrade(), $account, $onComplete, + $runMigration, ); $onComplete(); diff --git a/src/Appwrite/Platform/Installer/Http/Installer/View.php b/src/Appwrite/Platform/Installer/Http/Installer/View.php index ce308aa906..dea356eaaf 100644 --- a/src/Appwrite/Platform/Installer/Http/Installer/View.php +++ b/src/Appwrite/Platform/Installer/Http/Installer/View.php @@ -24,7 +24,7 @@ class View extends Action ->setHttpMethod(Action::HTTP_REQUEST_METHOD_GET) ->setHttpPath('/') ->desc('Serve installer UI') - ->param('step', 1, new Integer(true), 'Step number (1-5)', true) + ->param('step', 1, new Integer(true), 'Step number (1-6)', true) ->param('partial', null, new Nullable(new Text(1, 0)), 'Render partial step only', true) ->inject('request') ->inject('response') @@ -52,10 +52,13 @@ class View extends Action $defaultEmailCertificates = 'walterobrien@example.com'; } - $step = max(1, min(5, $step)); + $step = max(1, min(6, $step)); if ($isUpgrade && ($step === 2 || $step === 3)) { $step = 4; } + if (!$isUpgrade && $step === 6) { + $step = 4; + } $partialFile = $paths['views'] . "/installer/templates/steps/step-{$step}.phtml"; if (!is_file($partialFile)) { diff --git a/src/Appwrite/Platform/Installer/Server.php b/src/Appwrite/Platform/Installer/Server.php index 8996b9a4c3..6d9cd5412f 100644 --- a/src/Appwrite/Platform/Installer/Server.php +++ b/src/Appwrite/Platform/Installer/Server.php @@ -29,6 +29,7 @@ class Server public const string STEP_DOCKER_COMPOSE = 'docker-compose'; public const string STEP_DOCKER_CONTAINERS = 'docker-containers'; public const string STEP_ACCOUNT_SETUP = 'account-setup'; + public const string STEP_MIGRATION = 'migration'; public const string STEP_SSL_CERTIFICATE = 'ssl-certificate'; public const string STATUS_IN_PROGRESS = 'in-progress'; diff --git a/src/Appwrite/Platform/Tasks/Install.php b/src/Appwrite/Platform/Tasks/Install.php index a1cc1d094e..95846aad87 100644 --- a/src/Appwrite/Platform/Tasks/Install.php +++ b/src/Appwrite/Platform/Tasks/Install.php @@ -514,6 +514,7 @@ class Install extends Action bool $isUpgrade = false, array $account = [], ?callable $onComplete = null, + bool $runMigration = false, ): void { $isLocalInstall = $this->isLocalInstall(); $this->applyLocalPaths($isLocalInstall, false); @@ -636,6 +637,16 @@ class Install extends Action $this->createInitialAdminAccount($account, $progress, $apiUrl, $domain); } + if ($isUpgrade && $runMigration) { + // Allow the containers-completed SSE event to flush + // before blocking on migration exec + usleep(200_000); + $currentStep = InstallerServer::STEP_MIGRATION; + $this->runDatabaseMigration($progress, $isLocalInstall); + } elseif ($isUpgrade) { + $this->updateProgress($progress, InstallerServer::STEP_MIGRATION, InstallerServer::STATUS_COMPLETED, messageOverride: 'Migration skipped'); + } + // Signal completion before tracking so the SSE stream // finishes and the frontend can redirect immediately. if ($onComplete) { @@ -745,6 +756,46 @@ class Install extends Action } } + private function runDatabaseMigration(?callable $progress, bool $isLocalInstall): void + { + $this->updateProgress( + $progress, + InstallerServer::STEP_MIGRATION, + InstallerServer::STATUS_IN_PROGRESS, + messageOverride: 'Running database migration...' + ); + + // Allow the SSE chunk to flush before the blocking exec + usleep(100_000); + + // Static command — no user input involved + $command = $isLocalInstall + ? 'docker compose exec appwrite migrate 2>&1' + : 'docker exec appwrite migrate 2>&1'; + + $output = []; + \exec($command, $output, $exit); + + if ($exit !== 0) { + $message = trim(implode("\n", $output)); + $this->updateProgress( + $progress, + InstallerServer::STEP_MIGRATION, + InstallerServer::STATUS_ERROR, + details: ['output' => $message], + messageOverride: 'Migration failed: ' . ($message ?: 'exit code ' . $exit) + ); + throw new \RuntimeException('Database migration failed', 0, $message !== '' ? new \RuntimeException($message) : null); + } + + $this->updateProgress( + $progress, + InstallerServer::STEP_MIGRATION, + InstallerServer::STATUS_COMPLETED, + messageOverride: 'Database migration completed' + ); + } + private function trackSelfHostedInstall(array $input, bool $isUpgrade, string $version, array $account): void { if ($this->isLocalInstall()) { diff --git a/tests/unit/Platform/Modules/Installer/ModuleTest.php b/tests/unit/Platform/Modules/Installer/ModuleTest.php index 0b7e7effcb..ff77a7d010 100644 --- a/tests/unit/Platform/Modules/Installer/ModuleTest.php +++ b/tests/unit/Platform/Modules/Installer/ModuleTest.php @@ -134,7 +134,7 @@ class ModuleTest extends TestCase $this->assertActionParams($action, [ 'appDomain', 'httpPort', 'httpsPort', 'emailCertificates', 'opensslKey', 'assistantOpenAIKey', 'accountEmail', 'accountPassword', 'database', - 'installId', 'retryStep', + 'installId', 'retryStep', 'runMigration', ]); $this->assertActionInjects($action, ['request', 'response', 'swooleResponse', 'installerState', 'installerConfig', 'installerPaths']); } From b47ac00ca8161b1a73fa2c7c933a9a4f220f57ef Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 31 Mar 2026 21:08:29 +1300 Subject: [PATCH 16/18] (refactor): rename migrate param and add --migrate flag to upgrade task --- app/views/install/installer/js/modules/progress.js | 2 +- app/views/install/installer/js/steps.js | 10 +++++----- .../install/installer/templates/steps/step-6.phtml | 2 +- .../Platform/Installer/Http/Installer/Install.php | 6 +++--- src/Appwrite/Platform/Tasks/Install.php | 7 ++++--- src/Appwrite/Platform/Tasks/Upgrade.php | 5 ++++- tests/unit/Platform/Modules/Installer/ModuleTest.php | 2 +- 7 files changed, 19 insertions(+), 15 deletions(-) diff --git a/app/views/install/installer/js/modules/progress.js b/app/views/install/installer/js/modules/progress.js index 9087a192ef..868f820c95 100644 --- a/app/views/install/installer/js/modules/progress.js +++ b/app/views/install/installer/js/modules/progress.js @@ -374,7 +374,7 @@ assistantOpenAIKey: normalizedAssistantKey, accountEmail: normalizedAccountEmail, accountPassword: normalizedAccountPassword, - runMigration: formState?.runMigration ?? false + migrate: formState?.migrate ?? false }; }; diff --git a/app/views/install/installer/js/steps.js b/app/views/install/installer/js/steps.js index fb76b5f72d..b34389b561 100644 --- a/app/views/install/installer/js/steps.js +++ b/app/views/install/installer/js/steps.js @@ -337,14 +337,14 @@ const checkbox = root.querySelector('#run-migration'); if (checkbox) { - if (formState.runMigration !== undefined) { - checkbox.checked = formState.runMigration; + if (formState.migrate !== undefined) { + checkbox.checked = formState.migrate; } else { - formState.runMigration = checkbox.checked; + formState.migrate = checkbox.checked; } checkbox.addEventListener('change', () => { - formState.runMigration = checkbox.checked; - dispatchStateChange?.('runMigration'); + formState.migrate = checkbox.checked; + dispatchStateChange?.('migrate'); }); } diff --git a/app/views/install/installer/templates/steps/step-6.phtml b/app/views/install/installer/templates/steps/step-6.phtml index ca253c9907..9a8838ae3a 100644 --- a/app/views/install/installer/templates/steps/step-6.phtml +++ b/app/views/install/installer/templates/steps/step-6.phtml @@ -17,7 +17,7 @@ $isUpgrade = $isUpgrade ?? false; Recommended when upgrading to a new version - + diff --git a/src/Appwrite/Platform/Installer/Http/Installer/Install.php b/src/Appwrite/Platform/Installer/Http/Installer/Install.php index 482a30eab4..8aaaf621bb 100644 --- a/src/Appwrite/Platform/Installer/Http/Installer/Install.php +++ b/src/Appwrite/Platform/Installer/Http/Installer/Install.php @@ -43,7 +43,7 @@ class Install extends Action ->param('database', '', new WhiteList(['mongodb', 'mariadb', 'postgresql']), 'Database adapter', true) ->param('installId', '', new Text(64, 0), 'Installation ID', true) ->param('retryStep', null, new Nullable(new WhiteList([Server::STEP_DOCKER_COMPOSE, Server::STEP_ENV_VARS, Server::STEP_DOCKER_CONTAINERS], true)), 'Retry from step', true) - ->param('runMigration', false, new \Utopia\Validator\Boolean(true), 'Run database migration after upgrade', true) + ->param('migrate', false, new \Utopia\Validator\Boolean(true), 'Run database migration after upgrade', true) ->inject('request') ->inject('response') ->inject('swooleResponse') @@ -65,7 +65,7 @@ class Install extends Action string $database, string $installId, ?string $retryStep, - bool $runMigration, + bool $migrate, Request $request, Response $response, SwooleResponse $swooleResponse, @@ -357,7 +357,7 @@ class Install extends Action $config->isUpgrade(), $account, $onComplete, - $runMigration, + $migrate, ); $onComplete(); diff --git a/src/Appwrite/Platform/Tasks/Install.php b/src/Appwrite/Platform/Tasks/Install.php index 95846aad87..1be10f537f 100644 --- a/src/Appwrite/Platform/Tasks/Install.php +++ b/src/Appwrite/Platform/Tasks/Install.php @@ -36,6 +36,7 @@ class Install extends Action private const string GROWTH_API_URL = 'https://growth.appwrite.io/v1'; protected bool $isUpgrade = false; + protected bool $migrate = false; protected string $hostPath = ''; protected ?bool $isLocalInstall = null; protected ?array $installerConfig = null; @@ -323,7 +324,7 @@ class Install extends Action $shouldGenerateSecrets = !$existingInstallation && !$isUpgrade; $input = $this->prepareEnvironmentVariables($userInput, $vars, $shouldGenerateSecrets); - $this->performInstallation($httpPort, $httpsPort, $organization, $image, $input, $noStart, null, null, $isUpgrade); + $this->performInstallation($httpPort, $httpsPort, $organization, $image, $input, $noStart, null, null, $isUpgrade, migrate: $this->migrate); } @@ -514,7 +515,7 @@ class Install extends Action bool $isUpgrade = false, array $account = [], ?callable $onComplete = null, - bool $runMigration = false, + bool $migrate = false, ): void { $isLocalInstall = $this->isLocalInstall(); $this->applyLocalPaths($isLocalInstall, false); @@ -637,7 +638,7 @@ class Install extends Action $this->createInitialAdminAccount($account, $progress, $apiUrl, $domain); } - if ($isUpgrade && $runMigration) { + if ($isUpgrade && $migrate) { // Allow the containers-completed SSE event to flush // before blocking on migration exec usleep(200_000); diff --git a/src/Appwrite/Platform/Tasks/Upgrade.php b/src/Appwrite/Platform/Tasks/Upgrade.php index 1d61180963..6ef9c7134d 100644 --- a/src/Appwrite/Platform/Tasks/Upgrade.php +++ b/src/Appwrite/Platform/Tasks/Upgrade.php @@ -30,6 +30,7 @@ class Upgrade extends Install ->param('interactive', 'Y', new Text(1), 'Run an interactive session', true) ->param('no-start', false, new Boolean(true), 'Run an interactive session', true) ->param('database', 'mongodb', new Text(length: 0), 'Database to use (mongodb|mariadb|postgresql)', true) + ->param('migrate', true, new Boolean(true), 'Run database migration after upgrade', true) ->callback($this->action(...)); } @@ -40,9 +41,11 @@ class Upgrade extends Install string $image, string $interactive, bool $noStart, - string $database + string $database, + bool $migrate = true, ): void { $this->isUpgrade = true; + $this->migrate = $migrate; $isLocalInstall = $this->isLocalInstall(); $this->applyLocalPaths($isLocalInstall, true); diff --git a/tests/unit/Platform/Modules/Installer/ModuleTest.php b/tests/unit/Platform/Modules/Installer/ModuleTest.php index ff77a7d010..507a4e25f6 100644 --- a/tests/unit/Platform/Modules/Installer/ModuleTest.php +++ b/tests/unit/Platform/Modules/Installer/ModuleTest.php @@ -134,7 +134,7 @@ class ModuleTest extends TestCase $this->assertActionParams($action, [ 'appDomain', 'httpPort', 'httpsPort', 'emailCertificates', 'opensslKey', 'assistantOpenAIKey', 'accountEmail', 'accountPassword', 'database', - 'installId', 'retryStep', 'runMigration', + 'installId', 'retryStep', 'migrate', ]); $this->assertActionInjects($action, ['request', 'response', 'swooleResponse', 'installerState', 'installerConfig', 'installerPaths']); } From 037878cc751aaa9d4d3248d9fddd9a6036135576 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Tue, 31 Mar 2026 15:11:11 +0530 Subject: [PATCH 17/18] fix: use correct defaults for spec generation Use https://appwrite.io and team@appwrite.io as defaults for _APP_HOME and _APP_SYSTEM_TEAM_EMAIL in spec generation, instead of [HOSTNAME] and team@localhost.test placeholders. --- src/Appwrite/Platform/Tasks/Specs.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Appwrite/Platform/Tasks/Specs.php b/src/Appwrite/Platform/Tasks/Specs.php index 6453977a39..a6a5284fb0 100644 --- a/src/Appwrite/Platform/Tasks/Specs.php +++ b/src/Appwrite/Platform/Tasks/Specs.php @@ -347,8 +347,8 @@ class Specs extends Action $keys = $this->getKeys(); $generatedFiles = []; - $endpoint = System::getEnv('_APP_HOME', '[HOSTNAME]'); - $email = System::getEnv('_APP_SYSTEM_TEAM_EMAIL', APP_EMAIL_TEAM); + $endpoint = System::getEnv('_APP_HOME', 'https://appwrite.io'); + $email = System::getEnv('_APP_SYSTEM_TEAM_EMAIL', 'team@appwrite.io'); $specsDir = __DIR__ . '/../../../../app/config/specs'; if (!is_dir($specsDir) && !@mkdir($specsDir, 0755, true) && !is_dir($specsDir)) { From f9aee4de5d67efb8e8f43b8f9ca30c4b7adcaa4c Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Tue, 31 Mar 2026 23:08:31 +1300 Subject: [PATCH 18/18] (fix): clear stale install data before starting new installation --- app/views/install/installer/js/installer.js | 15 ++++++--- .../install/installer/js/modules/progress.js | 32 ++++++++++++++----- 2 files changed, 35 insertions(+), 12 deletions(-) diff --git a/app/views/install/installer/js/installer.js b/app/views/install/installer/js/installer.js index 4433d67b99..07ec7bb1ef 100644 --- a/app/views/install/installer/js/installer.js +++ b/app/views/install/installer/js/installer.js @@ -399,11 +399,18 @@ } } } - if (action === 'next' && String(target) === '5' && typeof validateInstallRequest === 'function') { - const isValid = await validateInstallRequest(); - if (!isValid) { - return; + if (action === 'next' && String(target) === '5') { + if (typeof validateInstallRequest === 'function') { + const isValid = await validateInstallRequest(); + if (!isValid) { + return; + } } + // Clear stale install data from previous runs so initStep5 + // starts a fresh install instead of trying to resume. + const { clearInstallLock, clearInstallId } = window.InstallerStepsState || {}; + clearInstallLock?.(); + clearInstallId?.(); } if (isInstallLocked() && Number(target) !== 5) { requestStep(5, true); diff --git a/app/views/install/installer/js/modules/progress.js b/app/views/install/installer/js/modules/progress.js index 868f820c95..7c36fd7951 100644 --- a/app/views/install/installer/js/modules/progress.js +++ b/app/views/install/installer/js/modules/progress.js @@ -722,7 +722,8 @@ }); startSyncedSpinnerRotation(list); - notifyInstallComplete(activeInstall?.installId, sessionDetails).finally(() => { + const completeId = activeInstall?.installId || getStoredInstallId?.(); + notifyInstallComplete(completeId, sessionDetails).finally(() => { setTimeout(() => redirectToApp(protocol), TIMINGS?.redirectDelay ?? 0); }); }; @@ -912,21 +913,28 @@ }; const isSnapshotTerminal = (snapshot) => { - if (!snapshot?.steps) return true; + if (!snapshot?.steps) return 'empty'; const stepEntries = Object.values(snapshot.steps); - if (stepEntries.length === 0) return true; + if (stepEntries.length === 0) return 'empty'; const hasError = stepEntries.some((s) => s.status === STATUS.ERROR); - if (hasError) return true; + if (hasError) return 'error'; const allCompleted = INSTALLATION_STEPS.every((step) => { const detail = snapshot.steps[step.id]; return detail && detail.status === STATUS.COMPLETED; }); - return allCompleted; + if (allCompleted) return 'completed'; + return false; }; const resumeInstall = async (installId) => { const snapshot = await fetchInstallStatus(installId); - if (!snapshot || isSnapshotTerminal(snapshot)) return false; + const terminal = isSnapshotTerminal(snapshot); + if (!snapshot || terminal) { + if (terminal === 'completed') { + return 'completed'; + } + return false; + } activeInstall = { installId, controller: new AbortController(), @@ -1086,8 +1094,16 @@ const lock = getInstallLock?.(); const existingInstallId = lock?.installId || getStoredInstallId?.(); if (existingInstallId) { - resumeInstall(existingInstallId).then((resumed) => { - if (!resumed) { + resumeInstall(existingInstallId).then((result) => { + if (result === 'completed') { + // Install already finished — redirect to console + // instead of bouncing back to step 1. + stopSyncedSpinnerRotation(); + setUnloadGuard(false); + clearInstallLock?.(); + clearInstallId?.(); + startSslCheck(null); + } else if (!result) { recoverToLastStep(); } });