Migration from Commento(++)

Commento

Commento was once a popular open-source commenting system.

It is in fact a predecessor of Comentario, because Comentario 2.x started as a fork to Commento 1.8, reworking the user interface and the internals, but keeping the database structure intact.

The fact that Comentario 2.x database was 100% compatible with Commento made the migration very easy: it was basically a drop-in replacement, which only required adjusting some server parameters. It made also a reverse migration possible.

Comentario 3

The version 3 of Comentario is a major step forward: it addresses many inconsistencies and limitations of Commento data model, which slowed down the development of the latter and made solving some issues nearly impossible.

The data model was developed from scratch, and all the constituent components had to be overhauled and rewritten.

We’ve done our best to make the migration transparent, keeping Comentario “plug-n-play.” The database will be automatically migrated on first run.

Contrary to Comentario 2.x, it’s a one-way ticket though; once migrated, the original database will be deleted. The only way to revert that is restoring a back-up copy made prior to migration.

Commento++

Commento++ (a.k.a. Commentoplusplus) was another project stemming from Commento, which tried to resolve its most pressing problems and added some new functionality.

Since its database is very close to the original, it’s also possible to directly migrate to Comentario from Commento++.

Two ways to migrate

There are two ways to bring your data over from Commento or Commento++:

• Migrating the database: Comentario takes over the whole Commento database, with all its domains, users and settings.
• Importing a Commento export: the comments and commenters of a single domain are imported from an export file into a domain in Comentario. It works with any database, but transfers less data.

Migrating the database

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 Comentario and configure it to connect to the same PostgreSQL database Commento used (or a copy of it).

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

Comentario 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';

Since you’re migrating from Commento, you’d probably already have users, so you’ll need to use the last two options.

5. Update your code snippet

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

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.

There’s one exception to the data attributes: data-hide-deleted, which Commento used to hide deleted comments, isn’t supported by Comentario on the page level. Instead, you can switch off the Show deleted comments configuration parameter.

Importing a Commento export

Instead of migrating the whole database, you can import the data of a single domain from a Commento or Commento++ export file. This works regardless of the database Comentario runs on, and leaves the original Commento installation intact.

1. Export the data from Commento

In the Commento dashboard, select the domain and start a data export in its Export Data section. Commento prepares the export in the background and emails you a link to download it once it’s ready, so its email (SMTP) settings have to be configured. The downloaded file is a gzip-compressed JSON file.

2. Import the data into Comentario

1. Log into Comentario 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 downloaded in the previous step; there’s no need to unpack it.
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.

3. Update your code snippet

Replace the Commento snippet on your pages with Comentario’s, as described in Update your code snippet above.

What is and isn’t transferred

A Commento export contains the domain’s comments and the commenters who wrote them. Pages are created in Comentario from the paths of the comments, without titles. The domain’s settings aren’t part of the export, so the target domain has to be configured separately.

• Comments keep their text, their place in the thread, their creation time and their approval status: comments awaiting approval in Commento are pending in Comentario. Deleted comments are imported as deleted, without their text. The comment text is rendered anew from its Markdown, according to the domain’s settings in Comentario, and is truncated to the domain’s maximum comment length.
• Anonymous comments remain anonymous.
• Votes: each comment keeps its score, but the individual votes aren’t transferred. As a result, users who voted for a comment in Commento can vote for it again in Comentario.
• 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 commenter whose email address is already registered in Comentario is matched to that existing account. Otherwise a new local (password-based) account is created for them, without a password, so they will need to reset it (via the Forgot your password? link on the login page) before they can sign in. This includes commenters who signed in to Commento via a social provider: the export doesn’t say which one, so they become local users.
• Avatars and websites: a new user gets the website from the export. Their avatar is fetched in the background from the avatar URL in the export, if there’s one, or otherwise from Gravatar, if the Gravatar integration is enabled.