Aller au contenu

Migrating from Misskey to Catodon

Faire tourner une instance 6 min de lecture Source sur codefloeEn anglais uniquement

Sur cette page

Catodon descends from Misskey through Sharkey, so a Misskey server's database can be carried over in place: your accounts, posts, files, follows and settings stay as they are, and Catodon's migrations bring the schema up to date. You switch the code and migrate. There is no need to pass through Sharkey, or to bring Misskey to a particular version first.

The source-install steps are adapted from Sharkey's guide for migrating from Misskey.

Which Misskey versions

Any Misskey release up to 2026.10.0, to Catodon 26.10.0 or later. Do not migrate from a newer Misskey until this page names it: a later release can add database changes that collide with Catodon's.

This path was rehearsed with Catodon 26.10.0 against databases built by Misskey's own migrations at fifteen releases from 2023.12.2 to 2026.10.0, and against a 2026.10.0 database with data in it, which Catodon then served. It has not yet been run on a production server with years of data, so take the backup, and tell us if a step does not work as written.

What does not come across

Nothing is deleted from the database, but Catodon does not use everything Misskey stores:

  • Drafts and scheduled posts (Misskey 2025.7 and later). Catodon does not read them, and a scheduled post will never be published. Ask your users to post or copy them out before the move.
  • Channels, Chat, Gallery, Clips and Play. Catodon removes these from the interface. Their data stays in the database, unused.
  • Settings Misskey added after 2025.4. Catodon ignores them, even where it has a feature of the same kind. This covers what signed-out visitors may see, single-user mode, the entrance page style, role badges on remote users, the external sensitive-media detection service, the URL preview redirect and sensitive-list settings, and the list of software to stop delivering to. After the move, go through the Control Panel, and check what your server shows to someone who is not signed in.
  • Remote note cleaning arrives switched off and in dry-run mode, even if it was on under Misskey. Catodon has its own version of the feature and never starts deleting because of an upgrade. Your expiry and duration values are kept.
  • Three settings Misskey moved into its control panel in 2025.5 live in the configuration file in Catodon. See step 3.

There is no supported way back to Misskey: the schema has diverged. The backup is the way back.

Before you start

  • Back up the database, the files and the .config directory, and keep the backup until you are sure you are staying. See Backing up before an upgrade; the same commands apply to a Misskey server.
  • Check the requirements in Installing and running Catodon: the Node.js version, PostgreSQL, Valkey (or Redis) and FFmpeg. Keep the PostgreSQL you have. Do not change its version as part of this move.
  • A source install needs pnpm 12. Corepack 0.34.5 or newer switches to it by itself. The first pnpm install rebuilds node_modules, and stops if it runs without a terminal unless you set CI=true, which the commands below do. The "Upgrading" notes at the top of CHANGELOG.md have the details.
  • Plan for downtime. The server is off from step 1 until the migrations finish, which takes minutes on a small server and much longer on a large one.

1. Stop Misskey

From source, stop the service, for example sudo systemctl stop misskey.

With Docker, stop only the application and leave the database running:

docker compose stop web

2. Switch the code to Catodon

From source

Assuming Misskey runs as user misskey from /home/misskey/misskey:

sudo -u misskey -i
cd misskey
git remote rename origin misskey
git remote add origin https://codefloe.com/catodon/catodon.git
git remote update -p
git checkout -b main --track origin/main
CI=true pnpm install --frozen-lockfile
pnpm run build

main is the latest stable release. To stay on an exact release, check out its tag instead of tracking main.

Your .config directory and files directory are not tracked by git, and the switch leaves them alone.

With Docker

Keep your own compose file, and change only the web service. Leave the db and redis services exactly as they are, image and volume lines included: a PostgreSQL of another major version, or one pointed at a different path, will not open your data. Moving the database to the PostgreSQL 18 image with PGroonga that Catodon's compose file uses is a step of its own, for once Catodon runs: see Upgrading PostgreSQL.

Use a published image by replacing build: . with an image: line. Pick the version from the list linked in Docker in install.md:

  web:
    image: codefloe.com/catodon/catodon:<version>

Or, to keep building from a checkout as Misskey's compose file does, switch the checkout with the git commands above (everything before pnpm install), then run docker compose build.

Either way, change the two volume paths from /misskey to /catodon, as Catodon's image serves the application from a directory of its own name:

    volumes:
      - ./files:/catodon/files
      - ./.config:/catodon/.config:ro

The user and group IDs are the same as in Misskey's image, so nothing on disk needs its owner changed.

Catodon ships Valkey rather than Redis, but Redis 7 keeps working, so leave the store alone during this move. To change it later, see Upgrading your in-memory store from Redis to Valkey.

3. Update the configuration file

Compare your .config/default.yml with Catodon's .config/example.yml. Do not change url, id, or the db and redis sections.

If you come from Misskey 2025.5 or later, three settings you last saw in Misskey's control panel are read from this file again:

# Proxy remote files. Without this line it is off.
proxyRemoteFiles: true

# Sign outgoing ActivityPub GET requests. On unless set to false.
#signToActivityPubGet: false

# Uncomment if you had "allow external ActivityPub redirects" switched off.
#disallowExternalApRedirect: true

Misskey's trustProxy is called trustedProxies in Catodon and has its own default. If your reverse proxy or CDN reaches the server from a public address, set it as example.yml describes. Catodon ignores Misskey's trustProxy, enableIpRateLimit and threadPoolSize keys.

Catodon also has settings Misskey does not. The "Upgrading" notes in CHANGELOG.md say which need a decision.

4. Migrate and start

From source:

pnpm run migrate

Then start the service again. Its name and unit file can stay as they are.

With Docker:

docker compose run --rm web pnpm run migrate
docker compose up -d

Let the migration finish, however long it takes. Run it under screen or tmux. Interrupting it is what causes damage; see Installing and running Catodon for what to do if a run fails or is interrupted.

If it stops with

column "enableRemoteNotesCleaning" of relation "meta" already exists

the checkout or image is older than Catodon 26.10.0. Switch to 26.10.0 or later and start the migration again. Nothing is lost: the migrations that had already finished are recorded and do not repeat.

Afterwards

  • Sign in and go through the Control Panel, as described under What does not come across.
  • Tell your users to reload. If the interface shows missing labels or stale screens, clearing the browser's cache and site data for your server fixes it, and signs that browser out.
  • Passwords and access tokens keep working, so apps stay signed in.

If the build misbehaves

If the service will not start, or the web UI shows missing labels, first make sure the build finished without errors, then build again from scratch:

pnpm run clean-all
CI=true pnpm install --frozen-lockfile
pnpm run build
pnpm run migrate