Migration from another Comentario

This page explains how to bring your data over from another Comentario: by moving a domain from one Comentario instance to another, or by upgrading a 2.x installation to version 3.

Moving a domain to another instance

A domain’s data can be moved between Comentario instances, for example to switch from PostgreSQL to SQLite, or to move a domain to a different server. It’s done by exporting the data from the domain on the original instance and importing it into a domain on the new one.

1. Export the data

1. Log into the original Comentario instance as a domain owner or a superuser.
2. Select the domain using the Domain selector.
3. In the sidebar, click Operations and select Export data.
4. Switch on Export avatars if you want users’ custom avatars included in the export.
5. Click Export and save the downloaded file.

2. Import the data

1. Log into the new Comentario instance as a domain owner or a superuser.
2. Create a new domain, or select an existing one using the Domain selector.
3. In the sidebar, click Operations and select Import data.
4. Select Commento/Comentario as the source format.
5. Select the file you exported in the previous step.
6. Click Import.
7. Once the import is complete, you’ll get an overview with numbers of imported, skipped and failed items.

It’s recommended to import a file only once: importing it repeatedly may have unintended effects.

What is and isn’t transferred

An export contains the domain’s pages, comments, and the users who have a role on the domain, along with their avatars if you chose to export them. The domain itself isn’t part of the export: its settings, webhooks, audit log entries and so on remain on the original instance, so the target domain has to be configured separately.

The import isn’t a one-to-one copy of the original data either:

• Votes: each comment keeps its score, but the individual votes aren’t transferred. As a result, users who voted for a comment on the original instance can vote for it again on the new one.
• Roles: imported users are added to the domain as commenters only; moderators need to be appointed again. Users who already have a role on the target domain keep it.
• Users: a user whose email address is already registered on the new instance is matched to that existing account; otherwise a new account is created for them. A local (password-based) account is created without a password, so the user will need to reset it (via the Forgot your password? link on the login page) before they can sign in.
• Federated accounts (those signing in via a social provider or SSO) can’t be transferred properly: the link to the user’s account at the identity provider isn’t part of the export. On their first sign-in, such a user is matched to the imported account by email alone, which only works if the same identity provider is configured on the new instance and still reports the same email address. Otherwise they can’t sign in to the imported account.

Upgrading from 2.x

The most important part of the upgrade is the database conversion, which happens automatically on the first run. This process is irreversible; once migrated, the original database will be deleted. The only way to revert that is making a back-up copy prior to migration.

1. Back up your data

The migration can fail, go wrong, or wipe the original data. This is especially true due to the quirks of the original Commento data model.

2. Check your backup

3. Deploy Comentario

Install the new version over the existing one: the exact steps will depend on how your Comentario is installed.

The database should be automatically migrated on the first run. If everything goes smoothly, the server will just run without any error or warning message in the console.

And if you start it with the -v command-line switch, you should have seen the following lines in the log:

2023/08/20 11:49:38 INFO  persistence Connected to database
2023/08/20 11:49:38 INFO  persistence Discovered 1 database migrations in resources/db/postgres
2023/08/20 11:49:38 INFO  persistence 0 migrations already installed
2023/08/20 11:49:38 INFO  persistence Successfully installed 1 migrations

4. Appoint a superuser

The 3.x Comentario version introduces the concept of superuser: it’s essentially an instance admin. Only superusers can manage (edit, ban, delete) other users and change configuration parameters. You’ll definitely need at least one for your installation.

There are the following four ways to become a superuser:

1. Superuser privilege can be granted a user by another superuser. It can only work if you already have a superuser.
2. The first local user (i.e. one signing up with email and password) registered on the server automatically gets a superuser privilege.
3. Using the --superuser=<ID-or-email> command-line switch to turn a user into a superuser.
4. Updating the database directly with a UI tool or the following SQL statement:

update cm_users set is_superuser = true where email = 'YOUR@EMAIL';

If you migrated from an existing Comentario install, you’d probably already have users, so you’ll need to use the last two options.

5. Update your Comentario snippet

Comentario 3 is embedded on a web page as a web component, and not via a <div> tag as before.

In practice, it only means updating the code snippet you place on your web pages, replacing the <div> with <comentario-comments>. You can look the snippet up in the Administration console, under Domain properties ⇒ Installation, and it looks like this:

<script defer src="https://example.com/comentario.js"></script>
<comentario-comments></comentario-comments>

If you used data-* attributes, you’ll need to change those, too:

• Firstly, they now have to be put on the <comentario-comments> tag (not on the <script>).
• Secondly, the data- prefix should be removed.