xmigrate

A Python package to migrate projects from one XNAT to another

Getting Started

Installation

We recommend installing in a project specific virtual environment created using a environment management tool such as uv.

First, create a local clone of the repository:

git clone https://github.com/UCL-MIRSG/xmigrate.git
cd xmigrate

Then install xmigrate in editable mode using uv:

uv venv --python=3.13
source .venv/bin/activate
uv sync --group test

Running xmigrate

First, configure xmigrate using xmigrate.toml. See xmigrate.toml.sample for an example.

Also, configure secrets.toml for destination database connection. See secrets.toml.sample (sslcert and sslkey are optional depending on your sslmode).

Then run the migrate command to either migrate all projects (if source_projects argument is None) or migrate a subset of projects from source to destination (include_rsync can be set to true or false) using:

xmigrate migrate

You can also separately run the rsync command to either rsync all projects (if source_projects argument is None) or rsync a subset of projects from source to destination using:

xmigrate rsync

For testing, you may also want to set your environment variables using mise.

N.B. Having a project specific .netrc can be helpful instead of the default ~/.netrc which may contain localhost. This can override the specified ports in xnat4tests so source and destination XNATs are on same port rather than the necessary different ports.

You can set up a mise.toml as below:

[env]
XNAT4TEST_KEEP_INSTANCE=true #This speeds up developer time by keeping the docker containers live
NETRC="path/to/your/.netrc" #Project specific .netrc can be helpful instead of default ~/.netrc

and activate it as below:

mise en

For development if you want to install a new package, add it to pyproject.toml dependency-groups and then to update the uv.lock file run:

uv lock

To run the integration tests from the command line:

cd xmigrate
pytest tests/integration

N.B. Currently, the submission object of the custom forms PUT API call is hardcoded so if the custom forms API changes then this will also need to be changed.