Skip to main content

Migration guide

Foreseerr

Foreseerr is a Seerr fork. Config paths stay Seerr-compatible (CONFIG_DIRECTORY, Docker /app/config).

Migrating from Seerr to Foreseerr​

Foreseerr can use an existing Seerr configuration because it uses the same config-directory layout and database settings. This preserves users, authentication, media-server integrations, Radarr/Sonarr settings, requests, and preferences.

The procedure does not change for each Seerr release: stop Seerr, back up, then point Foreseerr at the same config volume. Compatibility is maintained by Foreseerr’s migration history and upgrade tests against a pinned Seerr merge-base, not by a published Seerr-version matrix.

danger

Back up the complete Seerr config directory and database before migrating. Do not use your only production Seerr config or database for initial testing. Keep the original instance and backup until you have confirmed that Foreseerr is working correctly.

Alpha Foreseerr builds (0.1.0-alpha.x) are not a supported upgrade source. Migrate from Seerr, or start from a fresh Foreseerr v0.1.0 (or later stable) install.

warning

The safest way to evaluate Foreseerr is to clone your Seerr data and run Foreseerr against the clone on a different port. Do not run Seerr and Foreseerr against the same config directory or database at the same time. A different port does not make shared application data safe.

Supported sources​

Foreseerr supports migrating in place from:

  1. A Seerr configuration and database whose schema is at or behind the Seerr merge-base this Foreseerr release was last synced from. Upgrade coverage is validated in CI against that baseline (see maintainer notes in the repository’s stable contract).
  2. A fresh Foreseerr installation, with no prior data.
  3. A previous stable Foreseerr release (v0.1.0 or later). Alpha builds are not included.

If your Seerr instance is newer than Foreseerr’s last upstream sync, migration is not guaranteed. Prefer waiting for a Foreseerr release that includes that Seerr sync, or clone-test at your own risk and keep the original Seerr instance and backup.

This guide does not list Seerr version numbers. There is also no supported downgrade path: if an upgrade fails, restore the pre-migration backup. See Backups.

Before changing the live Seerr instance:

  1. Stop Seerr briefly while making the copy. This prevents the database from changing during the backup.
  2. Back up the complete config directory and database. See Backups.
  3. Create a clone of the config directory and, if applicable, restore a database dump into a separate database.
  4. Start Foreseerr using the cloned config/database and a different host port, such as 5056:5055.
  5. Verify login, users, requests, media-server connections, Radarr/Sonarr settings, notifications, and any reverse-proxy configuration.

For SQLite, copy the config directory only while Seerr is stopped. For PostgreSQL, use a dump and restore it into a separate database; do not point Foreseerr at the live Seerr database.

The cloned instance may contain real user information and credentials, so protect it in the same way as the original config and do not expose it publicly during testing.

Use this method only after the cloned instance has been tested successfully and Foreseerr is going to take over from Seerr:

  1. Back up the Seerr config directory and database. For Docker, the config is the host directory mounted to /app/config.
  2. Stop Seerr. Do not run Seerr and Foreseerr against the same config directory or database at the same time.
  3. Start Foreseerr using the same config directory mounted at /app/config.
  4. Open Foreseerr and verify the imported users, login/authentication, media-server connections, request history, and download settings.
  5. After confirming everything works, remove the old Seerr container if desired. Keep the backup for rollback.

For Docker Compose, the service can be changed from Seerr to Foreseerr while keeping the existing volume path:

services:
  foreseerr:
    image: ghcr.io/selmant/foreseerr:v0.12.0
    container_name: foreseerr
    init: true
    restart: unless-stopped
    ports:
      - "5055:5055"
    volumes:
      - /path/to/existing/seerr-config:/app/config

If the config directory is not writable by the container, update its ownership first:

sudo chown -R 1000:1000 /path/to/existing/seerr-config

The first Foreseerr startup may run database and settings migrations automatically. These can change the schema, so a backup and a stopped old instance are essential. If anything looks wrong, stop Foreseerr and restore the original Seerr instance and backup instead of continuing to use the modified data.

Running Foreseerr alongside Seerr for testing​

This is a different setup. Use a new config directory and, when using PostgreSQL, a separate database. Change only the host-side port mapping; the container can continue listening on port 5055:

services:
  foreseerr-test:
    image: ghcr.io/selmant/foreseerr:v0.12.0
    container_name: foreseerr-test
    init: true
    restart: unless-stopped
    ports:
      - "5056:5055"
    volumes:
      - ./foreseerr-test-config:/app/config

This creates a separate Foreseerr instance, so a brand-new config will not automatically contain the Seerr users or settings. To test with existing data, use a copy of the backed-up config/database—not the live Seerr data.

Do not point both running instances at the same /app/config directory or database. A different port alone does not make shared application data safe.

What to choose​

  • To evaluate Foreseerr safely: use a different port and a cloned config/database.
  • To replace Seerr after testing: stop Seerr, take one final backup, and migrate Foreseerr onto the existing config/database.

The migration path is not a substitute for a backup or a complete compatibility test. Keep the original Seerr instance and backup available until the migration has been verified.