Skip to content

Major Versions Upgrade Informations

This page collects information about noticeable changes to take care when upgrading to Cells new major versions.

Cells v5

Cells v5 introduces a new runtime (plugin-based, driven by bootstrap.yaml), a redesigned cluster/Helm story, PostgreSQL as a first-class primary database, and a comprehensive v4 → v5 migration framework. The upgrade is performed by the In-App Tool, but a few changes require attention.

1 — Backup

As for any major version, take a fresh backup of:

  • your primary database (MySQL/MariaDB or PostgreSQL);
  • your CELLS_WORKING_DIR content (excluding actual user data but including the .minio.sys folder when present);
  • any external bootstrap.yaml you may have customized.

2 — Reverse URL is now compulsory behind a reverse proxy (breaking change)

In v4, Cells could partially derive the external URL from incoming request headers. In v5 this implicit detection has been removed. Before upgrading, make sure every site that sits behind a reverse proxy has an explicit External URL configured — via ./cells configure sites, the service.reverseproxyurl Helm value, or directly in bootstrap.yaml. Upgrades will succeed even if it is missing, but the server will refuse forwarded requests until you set it.

3 — Database migrations

The v4 → v5 migration framework runs automatically on first startup. It covers:

  • SQL schema migrations (idm, data, scheduler stores, including column-name changes);
  • Personal Access Tokens (PaT) — re-encoded to the new storage format;
  • Policies — a default policy is added to grant access to the v2 REST API;
  • Namespaces and user metadata — migrated to the new Entity Values store;
  • Snapshots / datasource initialization — middleware returns UNAVAILABLE while migrations are running.

The framework also disables AutoMigrate on a small number of legacy tables to avoid attempts to alter existing column collations. Allow a few extra minutes for the first startup, especially on large databases.

Tip — PostgreSQL upgraders: if you are switching from MySQL/MariaDB to PostgreSQL as part of the upgrade, do not combine the two operations. Upgrade to v5 on your current engine first, validate, then plan the engine switch as a separate migration.

4 — Authentication tokens refreshed

As in v4, Hydra JWKs are regenerated in the DB at upgrade time. Existing authentication tokens are invalidated — users will be logged out and any Personal Access Tokens used by scripts/clients will have to be regenerated.

5 — Kubernetes / Helm deployments

If you run Cells on Kubernetes, the v5 chart deprecates the bundled subcharts (MariaDB, MongoDB, Redis, NATS, etcd, MinIO, Vault). Bundled subcharts are kept only for quick local trials. Before upgrading a production cluster:

  • provision each backend as an external (managed or operator-deployed) service;
  • update your values.yaml to disable the matching .enabled flag and point Cells at the external service via its connection string;
  • be aware that a dedicated cells-controller workload is now deployed alongside the cells ReplicaSet — make sure your namespace RBAC allows it to manage ConfigMaps and Secrets.

6 — Removed and deprecated features

  • GCS datasources have been removed. If any of your datasources used the Google Cloud Storage backend, plan a migration (typically to an S3-compatible object store) before upgrading.
  • Structured datasources are now hidden behind an advanced configuration flag. Existing structured datasources continue to work; new ones must be enabled explicitly.
  • Legacy config migrations have been deprecated. Upgrades must go through the v5 migration framework — do not chain manual config migrations from older versions.

7 — Collation issues at upgrade (MySQL/MariaDB)

The v4 collation warnings described in the v4 section below still apply. If your database carries non-default collations on legacy tables, run the conversion script described in Cells v4 → step 5 before starting the v5 upgrade — the v5 migration framework explicitly halts when it detects mismatched collations.

Cells v4

Major codebase changes for embracing Go Modules, upgrading dependencies, and simplifying microservices framework to ease cluster deployments. Upgrade is done by In-App Tool, but there are a couple of important notes:

1 - Backup

As any major version, make sure to have a good backup of your MySQL database as well as your CELLS_WORKING_DIR content, except for the actual data but including the .minio.sys folder if possible.

2 - Authentification Tokens refreshed

Hydra JWKs will be regenerated in the DB, with the effect of invalidating all existing authentication tokens. As a result, you will be logged out after upgrade, and if you are using Personal Access Tokens, you will have to regenerate new ones. Other applications like CellsSync will require re-authentication as well (see below).

3 - Cells Sites configuration

Except for a TLS Let's Encrypt setup, Cells Sites "Bind Addresses" should now not use a domain name anymore.

A bind address requires a binding PORT which will be the port your application will listen to (use standard port for Let's Encrypt), and a binding HOST that will either be a Network Interface IP, hostname (or domain name in the case of Let's Encrypt). If you have connection issue after upgrade, make sure to edit sites to bind to e.g. 0.0.0.0:8080 instead of domain.name:8080 (using cells configure sites or by simply editing the pydio.json file).

For a TLS setup with Let's Encrypt, the domain name must be used with the standard port 443 (other addresses can be used for alternate access only), as required by the ACME challenge.

4 - CellsSync client compatibility

An important change introduced in v4 creates a compatibility issue between specific server versions and CellsSync versions. Please refer to the Connect Desktop Sync section to learn more.

TL;DR:

  • If you do not plan to upgrade, do not upgrade Cells Sync either.
  • If you do upgrade to v4, do upgrade Cells Sync, and you will also have to launch a specific processing on your server datasources.

5 - Collation issues at upgrade

While upgrading to Cells v4 from an older version, you might get this warning:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
WARN    pydio.grpc.policy   [SQL] *****************************************************************************
WARN    pydio.grpc.policy   [SQL] 
WARN    pydio.grpc.policy   [SQL]   The following tables have a character set that does not match the default character set for the database...
WARN    pydio.grpc.policy   [SQL]       {"name": "idm_policy_rel", "collation": "latin1_swedish_ci"}
WARN    pydio.grpc.policy   [SQL]       {"name": "ladon_policy_subject", "collation": "latin1_swedish_ci"}
WARN    pydio.grpc.policy   [SQL]       {"name": "idm_workspace_policies", "collation": "latin1_swedish_ci"}
# (... more warnings...)  
WARN    pydio.grpc.policy   [SQL]   It might be due to the database being migrated from another system or the default database having been updated.
WARN    pydio.grpc.policy   [SQL]   It could potentially lead to issues during upgrades so we you should pre-emptively fix the tables collations.
WARN    pydio.grpc.policy   [SQL]   You can find more information here : https://pydio.com/kb/...
WARN    pydio.grpc.policy   [SQL] 
WARN    pydio.grpc.policy   [SQL] *******************************************************************************

and/or this error:

1
ERROR   pydio.grpc.oauth    Stopping all migrations as some tables may have collations differing from the database defaults. This may break migrations and foreign keys.

This have been seen on some old instances that went through various OS upgrades and migrations and landed in a not very clean state in terms of character sets and collation. This had no impact on the running instance in v3- versions but is problematic while running DB migrations to upgrade to Cells v4.
Rather than risking to end up with a broken instance, we chose to prevent migration when we are in this case.

To solve this issue, you should:

  • Stop Cells,
  • Insure that no process is left (e.g. by running: ps -afe | grep cells),
  • Perform a backup of your DB,
  • Run following SQL commands:
1
2
3
4
5
6
# Create a custom script in /tmp folder
echo "SET FOREIGN_KEY_CHECKS=0;" > /tmp/upgrade.sql
mysql -N -upydio -p -e "SELECT CONCAT('ALTER TABLE ', tbl.TABLE_SCHEMA, '.', tbl.TABLE_NAME, ' CONVERT TO CHARACTER SET utf8mb4;') FROM INFORMATION_SCHEMA.TABLES tbl WHERE TABLE_SCHEMA='cells' AND TABLE_TYPE='BASE TABLE' AND TABLE_COLLATION NOT LIKE 'ascii%' AND TABLE_NAME NOT LIKE 'hydra_%';" >> /tmp/upgrade.sql
echo "SET FOREIGN_KEY_CHECKS=1;" >> /tmp/upgrade.sql
# Run it against you DB
mysql -upydio -p cells < /tmp/upgrade.sql

WARNING: Do not run this script until you see the warning or error described above: it might corrupt an otherwise perfectly fine instance.

You can then restart Cells, the errors and warnings should be gone and your migration should run without further issue.

Cells v3

Introducing new "Flat" datasource format and many Cells Flows new features.

Upgrade is straight-forward by using the In-App Tool.

Cells v2

Synchronization rebooted and standard authentication development.

Upgrade is straight-forward by using the In-App Tool.