Install¶
Nebula ships as one Composer metapackage, nebula/admin. It installs nothing itself. It requires 26 modules (including UI Bridge) and the adminhtml theme, and Composer installs each from its own package.
Before installing: get your Composer key¶
First purchase Nebula Admin for €0.00 on qoliber.com. Complete the free checkout using your qoliber account, then open My Account → Nebula Keys (free) in your account to get the Composer key issued for composer.qoliber.com.
The zero-price order is required for Composer access. See Get Nebula for the steps. Nebula is distributed under the Nebula Community License.
Key generation is queued
Your key can take up to five minutes to appear after checkout. Refresh Nebula Keys (free) once the queue has processed your order. See where to find your key.
1. Add the packages¶
The 1.0.0 release is available from the authenticated Nebula Composer repository at https://composer.qoliber.com/r/nebula. Multiblog is a separate product and is not installed by this metapackage.
Tagged release¶
Configure the repository URL and the Composer key from Nebula Keys in your qoliber account. Replace YOUR_NEBULA_KEY below with that key. Keep credentials out of the project manifest and version control:
composer config repositories.nebula composer https://composer.qoliber.com/r/nebula
composer config --global --auth bearer.composer.qoliber.com "YOUR_NEBULA_KEY"
composer require nebula/admin:1.0.0 --with-all-dependencies
Keep minimum-stability: stable; released packages do not require changing it to dev. The repository must contain nebula/admin, all 26 module packages including UI Bridge, and nebula/theme-adminhtml-backend. If a package is missing, check repository access and indexing rather than loosening stability.
--with-all-dependencies (short form -W) lets Composer update dependencies already present in the store's lock file, within the constraints in composer.json. For example, Nebula Component requires justinrainbow/json-schema:^6.12; a store locked to 6.10.0 cannot install it through a partial update that keeps that dependency fixed. Review and commit the resulting composer.lock alongside composer.json.
If Composer still reports a conflict with -W, inspect the package constraints:
An exact version constraint in another package is a separate conflict that -W cannot override. See Composer's require options.
MageOS framework conflicts¶
MageOS satisfies Magento package requirements through Composer's replace metadata. Nebula 1.0.0 requires magento/framework:~103.0.9. MageOS framework releases 3.0.0–3.5.0 advertise 103.0.9 and satisfy that requirement; MageOS 2.x releases advertise 103.0.8-p* and do not. The tested MageOS release is 3.5.0. See the published MageOS framework metadata.
If Composer finds magento/framework 103.0.9 but cannot load it, inspect the installed platform and dependency conflict:
-W can unlock compatible dependency versions, but it cannot override the Magento framework version supplied by the installed MageOS release. Changing Nebula's version wildcard does not solve that conflict. A platform upgrade is a separate change to plan and test; Nebula 1.0.0 does not claim support for a MageOS 2.x installation.
Development from clones¶
Clone both the Admin source repository and nebula/ui-bridge. Configure the module, theme, UI Bridge and metapackage path repositories in the Magento project's root composer.json. Give each published path package an explicit options.versions entry of 1.0.0; this is a local development override, not a published tag. Generate the complete repository configuration from the checked release inventory:
Merge the printed entries into your Magento root's repositories, ahead of remote sources, then run composer require nebula/admin:1.0.0 --with-all-dependencies. The generated entries exclude the CRUD fixture. Path repositories symlink by default, so edits in the clones are live on the next request.
The release manifests declare 1.0.0; the explicit path mappings also support development branches after their manifests change. A versionless clone normally resolves to a development branch. Setting only minimum-stability: dev does not make dev-main satisfy a ^1.0 dependency; the explicit path version mappings are required. Never use these overrides in a production release installation.
2. Run the setup¶
The commands differ by mode. Run the block for the mode the store is in.
Do not run setup:static-content:deploy here. Static files are generated on demand, and a deployed copy shadows every later edit until you clear pub/static. setup:di:compile is not needed either, because the compiled definition manifest is read only in production mode, as step 4 explains.
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento nebula:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush
The deploy walks the theme's whole web/ tree, including the build tooling under web/node_modules. Nebula ships dev/js/minify_exclude/nebula_node_modules and dev/css/minify_exclude/nebula_node_modules set to /node_modules/ so that those files are skipped. If your pipeline resets dev/* configuration, the deploy fails with a JShrink "Unclosed string" error. The full deploy order is on Caching and production mode.
setup:upgrade creates the tables Nebula needs for saved grid views, the media index, the email builder, merchandiser preferences, passkeys and landing pages, and runs two data patches. One selects Nebula's Quill editor as the WYSIWYG editor and turns off Adobe's Page Builder. The other adds the nebula_must_change_password customer attribute, which marks a password an administrator set as temporary. The full list of side effects is on What changes on install.
3. Index the media library¶
The media browser reads an index of the files under pub/media, and nothing builds it until this command runs. Without it the library opens empty. Run it once after install and again after copying files into pub/media outside the admin.
4. Compile the definitions (production mode)¶
In production mode, the definition engine reads a compiled manifest at generated/nebula/definitions.php. Without it the admin no longer throws — the resolver warns once per definition and falls back to the cached live path — but that is a safety net, not a deploy plan: setup:di:compile does not write the manifest (the plugin earlier releases had on that command could never fire and has been removed), so the production block in step 2 runs nebula:compile explicitly. Run it again after enabling or disabling a module that ships definitions, or after editing a definition:
In developer and default mode the manifest is not read. Details on Caching and production mode.
5. Check the install¶
nebula:doctor prints a health report: how many Nebula modules and definitions are installed, whether the nebula_definitions cache type is enabled, and which storefront companion packages are missing and what they would add. nebula:lint validates every JSON definition on the install against its schema.
6. Sign in¶
Open /admin as usual. The login screen is Nebula's, and it offers passwordless passkey sign-in once a passkey is enrolled. The first administrator to sign in must enrol a second factor before the dashboard opens. Nebula forces a passkey and an authenticator app together, so the first screen only decides which of the two to set up first. That flow is on First sign-in.
The theme applies itself¶
There is no theme to select under Content › Design › Configuration. A plugin on Magento's design model forces Nebula/backend as the adminhtml theme on every admin request. To go back to the stock admin without uninstalling, use the theme switcher described on Upgrade, opt out, remove.
Developer mode notes¶
The compiled CSS and JavaScript bundles are committed under design/adminhtml/Nebula/backend/web/{css,js}/dist, so a plain install needs no Node step. In developer mode static files are generated on demand and no setup:static-content:deploy is needed. Rebuild the bundles only after editing the theme's TypeScript or Tailwind sources; see CSS and JavaScript in your module.