Installation

Install conviro/module-aichat (Magento module Conviro_AiChat) with Composer from Conviro's package repository, then connect the store with the setup wizard. Plan §20 item 3.

Before you start

1. Add the Conviro package repository

From the Magento root:

composer config repositories.conviro composer https://repo.conviro.io
composer config http-basic.repo.conviro.io api <YOUR_CONVIRO_API_KEY>

The username is the literal word api; the password is your Conviro API key. A widget public key is not an API key: pasting one gives HTTP 401, which Composer reports as "You must be using the interactive console to authenticate".

repo.conviro.io is served by Conviro's API; every published version stays in the index, each zip has a checked SHA-1 (shasum), and a published version is never rebuilt with different bytes.

2. Install the module

composer require conviro/module-aichat
bin/magento module:enable Conviro_AiChat
bin/magento setup:upgrade

Production mode — also compile and deploy static content (1.4 changed class constructors; skipping setup:di:compile fails with "class does not exist" errors, skipping static content leaves the storefront and admin without the module's assets):

bin/magento maintenance:enable
composer require conviro/module-aichat
bin/magento module:enable Conviro_AiChat
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f en_US <your store locales, e.g. tr_TR>
bin/magento cache:flush
bin/magento maintenance:disable

Run it as the file owner of the Magento installation, never as root — see Upgrading for who that is and why each step is there.

Developer mode: setup:upgrade and cache:flush are enough. Default mode: also setup:static-content:deploy -f <locales> (default mode keeps the static files it copied into pub/static once).

If cron is not installed yet: bin/magento cron:install.

setup:upgrade creates the tables conviro_event_outbox, conviro_sync_job, conviro_inbound_event and conviro_webhook_log, and applies data patches that matter only when upgrading from 1.3.x (Upgrade guide). It makes no call to Conviro.

3. Check the install

bin/magento module:status Conviro_AiChat     # Module is enabled

In the admin you now have:

• Stores › Settings › Conviro Setup — the setup wizard.
• Stores › Configuration › Conviro › AI Chat — settings, with the Integration Health card at the top.

Measured on local stacks: fresh install and upgrade from an installed 1.3.5, each followed by setup:di:compile and setup:static-content:deploy in production mode, pass on 2.4.4-p13, 2.4.7-p4 and 2.4.9 (version matrix, 2026-09-26).

4. Connect

Open Stores › Settings › Conviro Setup and follow the setup wizard. Until the store is connected, the module queues nothing and the storefront widget stays off (it needs a widget public key, which the wizard fills in).

Manual install (without Composer)

Copy the module to app/code/Conviro/AiChat/ and run the same module:enable, setup:upgrade (and, in production mode, setup:di:compile and setup:static-content:deploy -f <locales>) sequence. The admin's "update available" notice still works; you upgrade by replacing the files.

Upgrading

The admin's "update available" notice, the Integration Health card and the setup wizard show this sequence as one line, built for your store: its Magento mode (read from the store) and the locales a static deploy has to build (every active store view's locale, every active admin user's interface locale, and en_US for the admin). Conviro's own "update available" answer to 1.3.x modules carries the same sequence (production mode, with the store-view locales Conviro knows). Here is each step and why it is there.

Who runs it

From the Magento root, as the user that owns the Magento files — the owner of var/, generated/ and pub/static/, usually the web-server user (www-data, nginx, apache) or a dedicated deploy user the web server's group can write for. Check with ls -ld var generated pub/static, then for example sudo -u www-data -s. Composer runs as the same user.

Never as root. Everything root creates in var/, generated/ or pub/static/ belongs to root afterwards; the web server can no longer write there, and the store fails on the next cache write, generated class or static file (symptom: "Permission denied" or a blank page right after the upgrade — Troubleshooting). If it already happened, give the files back to their owner (chown -R <user>:<group> var generated pub/static), as root once, and follow your hosting's file-permission guide for the modes.

Production mode

bin/magento maintenance:enable
composer require 'conviro/module-aichat:^<version>'     # or: composer update conviro/module-aichat
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f en_US <your store locales, e.g. tr_TR>
bin/magento cache:flush
bin/magento maintenance:disable

As one line (what the admin shows, here for a tr_TR store):

bin/magento maintenance:enable && composer require 'conviro/module-aichat:^1.4.1' && bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento setup:static-content:deploy -f en_US tr_TR && bin/magento cache:flush && bin/magento maintenance:disable

• Maintenance mode from the first step to the last. From the moment Composer replaces the module until the compile and the static deploy have finished, the code on disk, the generated code and the static files do not match; a request in that window errors. With maintenance on, shoppers see Magento's maintenance page instead. Allow your own IP to check the admin in the meantime: bin/magento maintenance:allow-ips <your ip>.
• A plain setup:upgrade. In production mode it deletes generated/ and the deployed static files — which is fine here, because the store is in maintenance mode and the next two steps rebuild both. Do not add --keep-generated to this in-place sequence: it keeps the previous release's compiled dependency-injection configuration, and setup:upgrade then runs the new release's data patches against it (constructors that changed are built with the old arguments). --keep-generated is correct only after a fresh compile — the release-directory method below. (An earlier 1.4.1 draft of this page put it here; that was wrong.) Measured on Magento 2.4.4-p13, 1.3.4 → 1.4.1, 2026-09-27: that order happened to exit without an error — a risk, not a certain failure — and the release-directory order (compile and static deploy first, --keep-generated only on the upgrade after them) left the store up to date and serving the new widget.
• setup:di:compile. 1.4 changed class constructors; without the compile a production store fails with "class does not exist" errors.
• setup:static-content:deploy -f with your locales. Production mode serves only static files that were deployed. Name en_US (the admin) and every store-view locale — the admin shows the list for your store. -f makes the command run in any mode. (Measured on 2.4.4-p13: with no locale named, Magento deployed the store view's tr_TR for the storefront by itself; naming them makes the result not depend on that.)
• cache:flush, then maintenance:disable. Then open the Integration Health card and click Check storefront: it reads the page visitors get and says whether it carries this release's widget. (Measured on a 2.4.9 test store: cache:flush did not remove the file-based full-page cache, and the old widget kept being served until var/page_cache/ was emptied — see Troubleshooting.)
• If a step fails, the && chain stops there and the store stays in maintenance mode — shoppers see the maintenance page, not errors. Read the message, fix the cause (disk space, permissions, a PHP memory limit: php -d memory_limit=2G bin/magento ...), run the remaining steps, then bin/magento maintenance:disable. To go back instead, see Rollback.

No single command here is "zero downtime": the store is in maintenance mode for the whole run — on a small store a few minutes, on a large catalogue with many locales longer. The compile and the static deploy take most of it.

Default and developer mode

• Developer mode: composer, bin/magento setup:upgrade, bin/magento cache:flush. Generated code and static files are built on demand (static files are symlinks).
• Default mode: the production sequence without setup:di:compile, but with the static deploy — default mode copies static files into pub/static on first use and would keep serving the old widget loader.

Check the mode with bin/magento deploy:mode:show.

Release-directory (copy, compile, swap) upgrades

The way to keep the maintenance window short is to do the slow work outside the live directory — the method the operator of the first production upgrade to 1.4.0 used (velgrina.com.tr, 1.3.4 → 1.4.0, 2026-09-26, switch ~1 s as reported by the operator):

1. Copy the live release to a new directory (or check out your deployment's next release), including app/etc/env.php and app/etc/config.php — but not generated/, pub/static/ or var/view_preprocessed/: they hold the old release's compiled code, static files and minified templates. (Measured 2026-09-27: a minified copy of the old widget template left in var/view_preprocessed kept rendering after an upgrade in which every step passed. From 1.4.1 on, every setup:upgrade removes the module's own preprocessed templates; other modules' stay.)
2. In the new directory, as the file owner: composer require 'conviro/module-aichat:^<version>', bin/magento setup:di:compile, bin/magento setup:static-content:deploy -f <locales>. The live store keeps running on the old directory meanwhile; nothing here touches the database.
3. bin/magento maintenance:enable (the flag lives in var/; if var/ is not shared between releases, enable it in both).
4. In the new directory: bin/magento setup:upgrade --keep-generated — here --keep-generated is right, the compile in step 2 already matches the new code — then switch the web root (symlink) to the new directory, bin/magento cache:flush, bin/magento maintenance:disable.
5. Keep the old directory until the store is verified; it is your rollback.

The window is step 3 to step 4 — the database upgrade and the switch — not zero: 1.4.x adds tables and columns, and the old code must not serve requests against the new schema unguarded. --keep-generated exists on every Magento version the module supports (2.4.4 and later).

Rollback

• Before setup:upgrade ran (a failed Composer or compile step): restore the previous code (composer require 'conviro/module-aichat:<previous version>', or switch back to the old release directory), bin/magento setup:di:compile, static deploy, cache:flush, maintenance:disable.
• After setup:upgrade ran: the database now carries the new module's schema version, and Magento refuses to run older module code against it ("Please update your modules"). Restore the database backup you took before the upgrade together with the old code. 1.4.x schema changes are additive (new tables and columns); nothing is dropped, so no Conviro data is lost by upgrading — but a downgrade without the backup is not supported.
• Take a database backup before every upgrade (mysqldump --single-transaction).

After the upgrade, open the Integration Health card (Stores › Configuration › Conviro › AI Chat): every row should be Pass or an understood Warning. Upgrading from 1.3.x: read the Upgrade guide first.

Next

• Setup wizard
• Configuration reference
• Integration Health