Keitaro 11 migration

Start with the general migration procedure: it describes the SFTP connection, confirming the summary and switching the domains. This page covers what is specific to a physical Keitaro 11 backup.

Which backup you need

The wizard accepts a complete, finished physical kctl backups backup from Keitaro 11.8.3 or 11.10.0, packed into a single .tar or .tar.gz. Verified physical storage versions: MariaDB 11.4.8 and ClickHouse 25.1.2.3. Other schemas are not considered compatible just because of the number “11”.

The archive root must contain applied.env, the .finished completion marker and the backup directories:

• mariadb/var/lib/mysql/ — settings and entities;
• clickhouse/var/lib/clickhouse/ — history;
• tracker-admin/var/www/keitaro/var/sites/ — hosted pages. An empty directory is fine if there really are no hosted pages.

Pack the contents of an already finished backup, not the live database directories. For example, from the chosen backup directory:

sudo tar -C /full/path/to/finished/copy -czf /root/keitaro11-full.tar.gz .
sudo chmod 600 /root/keitaro11-full.tar.gz

The archive contains visitor data, pages, settings and integration secrets. Keep it in a private directory and transfer it to your new server over SSH/SFTP. Do not publish it over HTTP. A standalone SQL dump, the folder of an unfinished backup and an export in the old kctl transfers dump format do not replace a full physical Keitaro 11 backup.

Migration in the wizard

1. Install a bundle with Keitaro 11 support on the new server. Specify the panel and tracking domains, and continue the setup over HTTPS.
2. At the owner creation step, open the migration from Keitaro. Specify the local path to the archive, or download it from your server over SFTP. With SFTP, check the server key fingerprint.
3. Wait for the preparation. Micator creates separate database copies, extracts the settings and the history, and checks their compatibility. A large history can take several hours to process; you can close the tab.
4. Choose campaigns with traffic for 30, 60, 90 or 180 days. The period is counted from the date of the source backup. The wizard shows the number of campaigns and pages, the volume and the reasons why individual streams are stopped.
5. Specify how to handle the unsupported corporate networks condition, whether to allow PHP offers to access the internet, and where Keitaro took the referrer from. Do not guess the referrer answer: it changes how traffic is routed.
6. Check the summary, type ПЕРЕНЕСТИ (Russian for “migrate”), set up the Micator owner and finish the installation.
7. Wait for the configuration to be published and the pages to be checked. The 90-day UTC history is loaded by a separate background job, and its readiness is checked separately from the panel opening. The 30–180 days chosen above define the set of campaigns, not the period of the background history.

Preparation requires Linux amd64 with Docker and at least 12 GiB of free space before you start. This is a lower bound, not an estimate for any backup: you also need space for the unpacked databases, the intermediate history and the pages. Before you confirm, the wizard checks the space for the selected pages and for one subsequent backup. The temporary database containers are limited to 1 and 2 GiB of memory, and the history preparation container to 2500 MiB. Choose a server with headroom for the regular Micator services.

What is preserved

• Campaigns, streams, sources, networks, domains, offers and landing pages go through the same plan and page compatibility checks as in a Keitaro 10 migration.
• A click keeps its original subid, time, cost, bindings and supported dimensions. Landing page click-throughs are counted separately.
• Conversions keep their tid, time, payout, raw type and their own bindings to the offer, stream and landing page. If a conversion belongs to another offer, its revenue is not automatically attributed to the offer of the original click.
• The Keitaro type flags “count conversion” and “count revenue” apply to the imported history regardless of the canonical Micator status. So a rejected type that Keitaro counts does not disappear from the conversion count, and the counted revenue of a lead is not reset to zero.
• For late postbacks of old clicks, the transition policy of the source types and the direction of the offer cap change are kept. A repeat of the same event does not create a second transaction or a repeat send.
• New clicks after the switch are processed by the current Micator rules. The policy of the source snapshot applies to migrated clicks; do not treat it as a global setting of the new tracker.

Loading the history does not send old S2S/CAPI events and does not create a queue for sending them. Checking and retrying the load must not add duplicates. Real late postbacks are processed separately, after they are received and checked.

Conversion types and limitations

Automatic mapping of system types:

The names, aliases, counting flags and allowed transitions of the source types are kept separately. Two source types with the same canonical status do not merge into one type when a late postback is processed.

Unknown custom types require an explicit mapping policy during the preliminary preparation; the wizard does not guess it. A conflict with existing Micator aliases or flags stops the apply before the configuration is written. An empty installation is preferable for the first migration.

The current path accepts a history where the base currency and the migrated money values are in USD. It does not invent historical exchange rates and refuses amounts that cannot be written to the Micator format without changes. Unknown types, ID collisions, an unsupported schema or exceeded safety limits mean a refusal, not a partially successful migration. Checking links and types is limited by memory; very large histories may need separate preparation.

Not every Keitaro feature has an equivalent. A missing page, an unsupported condition or the need for IP2Proxy is shown in the summary. Before you switch DNS, check the stream, the landing page, the redirect to the offer, the forms and a test postback. Page code runs in the Micator sandbox; it gets no access to the internal network or the tracker data.

Cancel, retry and diagnostics

Stopping the preparation does not change the source backup. A retry starts new isolated databases; a partial copy is never used as a finished one. After a restart, the wizard first cleans up its own unfinished temporary databases. If Docker does not let it stop them, the retry is aborted, and the files remain for the next attempt. Until the tracker is opened, the wizard can cancel the migration and open an empty installation.

After the load, the history has separate preparation, loading and verification states. You can retry the background load with the standard command:

sudo micatorctl keitaro-import --step status
sudo micatorctl keitaro-import --step tail

The source archive is not deleted automatically. The prepared archive is stored in the private run directory and is needed for history retries. Do not delete it until the history is verified. After the panel is opened, canceling the migration and deleting its history are different actions; a configuration rollback must not leave behind history rows bound to it. Once real new conversions appear, a separate protection against deleting live data applies.