# Migrate from Nexus 2 to CloudRepo

> One command moves a Nexus 2 server's Maven repositories and every version of each npm package, with dist-tags, to CloudRepo.

`cloudrepo-migrate nexus2` copies the hosted Maven and npm repositories of a Nexus Repository 2 server into CloudRepo, then reads every file back from CloudRepo and checks it against the original. It moves every file of a Maven repository and, for npm, every version of each package with its dist-tags.

One command moves your Nexus 2 Maven and npm repositories into CloudRepo, every file checksum-verified.

A dry run lists what would move and uploads nothing.

**Terminal**

```bash
cloudrepo-migrate nexus2 \
  --nexus-url https://nexus.example.com/nexus \
  --org your-org \
  --dry-run
```

When the list looks right, run it for real:

**Terminal**

```bash
cloudrepo-migrate nexus2 \
  --nexus-url https://nexus.example.com/nexus \
  --org your-org \
  --report-json report.json
```

Nexus is only read. It keeps running, unchanged, until you repoint your builds. Using an agent? Go to [For agents](#for-agents).

## What you need

- A CloudRepo organization. No account yet? [Start free trial](https://www.cloudrepo.io/signup). 14 days free. No credit card required.
- A [repository](/docs/manage/repositories.html#creating-a-repository) in CloudRepo for each Nexus repository you move, of the same format. Give it the Nexus repository’s name, or map the names with `--repo`. A CloudRepo repository name has lowercase letters, digits, `_` and `-`, and at most 32 characters. Use a new, empty repository where you can: the tool puts each file at the path Nexus has it, and a repository that allows overwrites replaces a file already there.
- A [repository token](/docs/authenticate/repository-tokens.html) with **Download and publish packages** on those repositories.
- Python 3.8 or later with pipx (or pip), on a machine that can reach your Nexus server and your CloudRepo organization over the network.
- A Nexus login that can read the repositories, unless your Nexus allows anonymous reads.

## 1. Install the tool

`cloudrepo-migrate` is one command for Python 3.8 or later, with no dependencies. Install it from PyPI:

**Terminal**

```bash
pipx install cloudrepo-migrate
```

No pipx? `pip install cloudrepo-migrate` in a virtual environment works too. Then check that it runs:

**Terminal**

```bash
cloudrepo-migrate --version
```

Every version of each npm package moves from version 0.4.0. An older version moves only the latest version of each npm package, so run `pipx upgrade cloudrepo-migrate` if yours is older.

## 2. Run it

Put the credentials in the environment of the shell that runs the tool: `NEXUS_USERNAME` and `NEXUS_PASSWORD` for Nexus (leave both unset to read anonymously), and `CLOUDREPO_TOKEN` for CloudRepo. The tool reads them only from the environment, or asks for a missing one when it runs in a terminal. No option takes a credential, and the tool never prints one or writes one to the report.

The first command at the top of this page is the dry run. With `CLOUDREPO_TOKEN` set, it also checks the token and that each target repository exists. The second command is the real run.

| Option                               | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--nexus-url URL`                    | The base address of your Nexus 2 server, such as `https://nexus.example.com/nexus`.                                                                                                                                                                                                                                                                                                                                                       |
| `--org ORG` or `--cloudrepo-url URL` | Your CloudRepo organization, or its full `https` address.                                                                                                                                                                                                                                                                                                                                                                                 |
| `--repo SOURCE` or `SOURCE=TARGET`   | Move only this Nexus repository, to the CloudRepo repository `TARGET` (default: the same name). Repeat it for more. Default without it: every hosted Maven and npm repository.                                                                                                                                                                                                                                                            |
| `--dry-run`                          | List what would move. Upload nothing.                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--quote`                            | From version 0.10.0. Count what you have, to ask us for a quote. It prints only totals for Maven and npm: the repositories, the items (Maven files, npm versions) and the bytes (npm bytes are not measured), and how many repositories could not be listed. It names nothing about your server, so you can send it to us as it is. It only reads Nexus: it implies `--dry-run`, needs no `--org`, and stops if `CLOUDREPO_TOKEN` is set. |
| `--latest-only`                      | For npm, move only the version each package’s `latest` dist-tag names, as 0.2.0 did. Default without it: every version, with its dist-tags.                                                                                                                                                                                                                                                                                               |
| `--report-json PATH`                 | Also write the report to `PATH` as JSON.                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--json`                             | Print the report as one JSON document on standard output, and the text on standard error.                                                                                                                                                                                                                                                                                                                                                 |
| `--jobs N`                           | Upload `N` Maven files at a time (default 4). npm packages move one at a time.                                                                                                                                                                                                                                                                                                                                                            |
| `--work-dir DIR`                     | Where a Maven file is held while it moves (default: the system temporary directory).                                                                                                                                                                                                                                                                                                                                                      |
| `--nexus-ca-file PEM`                | A CA bundle, for a Nexus with a private certificate.                                                                                                                                                                                                                                                                                                                                                                                      |

## What moves, and what does not

| In Nexus 2                        | What happens                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hosted Maven repository           | Every file moves, POMs and checksum files included. The `maven-metadata.xml` files move last, so a build never reads a version whose files have not landed.                                                                                                                                                                                                                                                                                                                                                                                   |
| Hosted npm repository             | Every version of each package moves, oldest first, scoped packages included. Then each dist-tag Nexus has (`latest`, `next` and any other) that CloudRepo lacks is added. A dist-tag CloudRepo already holds is never moved or removed: if it names another version than Nexus does, or Nexus has no such tag, the report lists it as `kept`. A deprecated version keeps its message. A version unpublished from Nexus is not in its package, so it does not move. With `--latest-only`, only the version `latest` names moves, as 0.2.0 did. |
| Proxy repository                  | Skipped. Create a [proxy repository](/docs/consume/proxy-repositories.html) in CloudRepo if its upstream is one CloudRepo offers.                                                                                                                                                                                                                                                                                                                                                                                                             |
| Group repository                  | Skipped. Move the repositories it groups. For Maven, you can then create a [group repository](/docs/manage/repositories.html#creating-a-repository) in CloudRepo to serve them under one address.                                                                                                                                                                                                                                                                                                                                             |
| Virtual repository, other formats | Skipped. This version moves Maven and npm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Files Nexus generates itself      | Skipped: any file or folder whose name starts with a dot (such as `.index`, `.meta` and `.nexus`), and the root `archetype-catalog.xml`.                                                                                                                                                                                                                                                                                                                                                                                                      |

Every skipped repository is in the report with its reason. The tool deletes nothing.

Every other Nexus and Artifactory term, and what CloudRepo calls it, is on [Artifactory and Nexus terms in CloudRepo](/docs/migrate/artifactory-and-nexus-terms.html), which also says where CloudRepo has no equivalent.

## How every file is checked

1. **Before the upload.** A Maven file’s bytes must match the SHA-1 Nexus recorded for it. An npm tarball must match its package’s `dist.shasum` and, when the package has one, its `dist.integrity`. A file that does not match is not uploaded.
2. **After the upload.** The tool reads the file back from CloudRepo and compares its SHA-1 and SHA-256 with the bytes it took from Nexus.
3. **Checksum files.** A checksum file Nexus holds (`.sha1`, `.sha256`, `.sha512` or `.md5`) must name the digest of the file it sits beside.

Any mismatch fails the run and names the file. The run then exits with `1`, so a script or an agent cannot read a failed check as success.

## Resume after a failure

Run the same command again. A file CloudRepo already holds is counted as already present, and not uploaded again, only after the tool has read it back and found the same bytes. A repository that refuses to overwrite a release answers `409` for a file it holds. The tool counts that file as moved only when the bytes CloudRepo holds match the source.

## The end report

The last line of the output is the result:

```text
Moved N repositories, F files, B bytes in M minutes; V of F verified, K failed.
```

`N`, `F` and `B` are the repositories, files and bytes that moved, `M` is the elapsed time, `V` is the number of files read back and matching, and `K` is the number that failed. Above it is one line for each repository: its Nexus name, its CloudRepo name, its format, its counts and, for a skipped repository, why. A line `REPO PACKAGE: kept: TAG -> VERSION (source: VERSION or none)` names an npm dist-tag CloudRepo already holds that the tool left as it was. It is not a failure.

`--report-json` writes the same report as JSON, and `--json` prints it as one JSON document on standard output (the text then goes to standard error). A script reads these keys:

| Key                                    | Holds                                                                                                                                                                                                                                                   |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `exit_code`                            | The exit code of the run, as in [If something fails](#if-something-fails).                                                                                                                                                                              |
| `error`                                | The message of a run that stopped before its report, such as a refused token. Such a document holds only `exit_code` and `error`.                                                                                                                       |
| `totals.files`, `.verified`, `.failed` | The counts in the last line.                                                                                                                                                                                                                            |
| `failures`                             | One entry for each failed file, with its `repository`, `path` and `reason`. Empty when nothing failed.                                                                                                                                                  |
| `kept`                                 | One entry for each npm dist-tag CloudRepo already holds and the tool left as it was: its `repository`, `path` (the package), `tag`, `version` (CloudRepo’s) and `source` (the version Nexus tags, or `null` when Nexus has no such tag). Not a failure. |
| `repositories[].action`                | `moved`, `would move` (a dry run), `skipped`, `ready` or `blocked`.                                                                                                                                                                                     |
| `repositories[].reason`                | Why a repository was skipped or blocked, or, in a dry run, what moves from an npm repository.                                                                                                                                                           |

## If something fails

The exit code says which kind of failure it was:

| Exit code | Meaning                                                                                                          |
| --------- | ---------------------------------------------------------------------------------------------------------------- |
| `0`       | Everything moved, and every file was read back and matched.                                                      |
| `1`       | At least one file failed. The output lists each one with its path. Fix the cause and run the same command again. |
| `2`       | A problem before anything moved, such as a missing target repository or a refused token. Nothing was uploaded.   |
| `130`     | Stopped with Ctrl-C. Run the same command again to resume.                                                       |

The messages you are most likely to see:

| The output says                                                                | What to do                                                                                                                                                                                                                                          |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CloudRepo has no repository NAME: create it as ...`                           | Create the repository in CloudRepo, in the format named, then run again. Or map the Nexus repository to another with `--repo`.                                                                                                                      |
| `... is not a valid CloudRepo repository name`                                 | The Nexus name is not a valid CloudRepo name. Choose a name with `--repo SOURCE=TARGET`.                                                                                                                                                            |
| `CloudRepo refused the token`                                                  | Check `CLOUDREPO_TOKEN`, and that the token belongs to this organization.                                                                                                                                                                           |
| `the token cannot reach CloudRepo repository NAME`, or `cannot publish`        | Give the token **Download and publish packages** on that repository.                                                                                                                                                                                |
| `Nexus refused the login`                                                      | Set `NEXUS_USERNAME` and `NEXUS_PASSWORD` to a login that can read the repository.                                                                                                                                                                  |
| `the bytes Nexus served ... do not match the sha1 Nexus recorded`              | The copy in Nexus does not match its own record, so the tool did not upload it. Check that file in Nexus.                                                                                                                                           |
| `dist-tags the source has, not added: ...`                                     | A dist-tag Nexus has, and CloudRepo lacks, names a version that did not move, whose own failure is listed too: fix that one and run the same command again. A tag that names a version Nexus does not list stays unset until you retag it in Nexus. |
| `CloudRepo already holds different bytes for this path and refuses overwrites` | The file in CloudRepo is not the one in Nexus, and the repository will not replace it. Decide which copy is right, then email <support@cloudrepo.io> with the path.                                                                                 |
| `its sha1 checksum file ... says ...`                                          | The checksum file in Nexus disagrees with its file. The bytes moved unchanged. Only fixing the file in Nexus clears this, and the run keeps exiting 1 until you do.                                                                                 |
| `the bytes CloudRepo serves back differ from the source`                       | Run the same command again. If the same file fails twice, email <support@cloudrepo.io> with its path.                                                                                                                                               |

## After the move

The files are in CloudRepo: every Maven file, and every npm version with its dist-tags, so a build that pins an older npm version resolves it from CloudRepo too. Your builds still point at Nexus. Repoint them one project at a time, as step 5 of [Migrate from Sonatype Nexus Repository](/docs/migrate/from-nexus.html#5-repoint-your-builds) shows for each build tool, and leave Nexus running until your builds pass against CloudRepo.

## For agents

Give your agent this instruction. It carries the address of this page as plain text, so the agent reads this page and nothing else:

```text
Migrate my Nexus 2 to CloudRepo. Follow https://www.cloudrepo.io/docs/migrate/from-nexus-2.md. Read my credentials from the environment variables NEXUS_USERNAME, NEXUS_PASSWORD and CLOUDREPO_TOKEN, and ask me for the Nexus URL and the CloudRepo organization if you do not have them.
```

The invocation, in two runs. Replace the address and the organization with the owner’s:

**Terminal**

```bash
cloudrepo-migrate nexus2 --nexus-url https://nexus.example.com/nexus --org your-org --dry-run --json
cloudrepo-migrate nexus2 --nexus-url https://nexus.example.com/nexus --org your-org --json
```

Each run prints one JSON document on standard output, its result, and the text report on standard error. [The end report](#the-end-report) names the keys.

Steps:

1. Check that `python3 --version` is 3.8 or later. If `cloudrepo-migrate --version` does not answer, install the tool with the command in [Install the tool](#1-install-the-tool), and check again. If `cloudrepo-migrate nexus2 --help` does not list `--json`, run `pipx upgrade cloudrepo-migrate`. If it still does not, run each command with `--report-json report.json` in place of `--json`, and read `report.json`: the same document, without `exit_code`.

2. Check that `CLOUDREPO_TOKEN` is set without printing it, for example with `test -n "$CLOUDREPO_TOKEN"`. Do the same for `NEXUS_USERNAME` and `NEXUS_PASSWORD`, unless the owner says Nexus allows anonymous reads.

3. Run the first command, the dry run. It reads Nexus and writes nothing to CloudRepo. Expect exit code `0`, and in the document `exit_code` `0` and `dry_run` `true`. Each entry in `repositories` with the action `would move` is a repository that will move, with its `format` and `files`; each with the action `skipped` says why in its `reason`. On exit code `2`, read `error`, or the `reason` of each repository with the action `blocked`, in [If something fails](#if-something-fails). If a target repository is missing, ask the owner to create it in the portal, then repeat the dry run.

4. Run the second command.

5. Verify, all of these, in the document it printed:

   - `exit_code` is `0`, and so is the exit code of the command.
   - `failures` is empty, `totals.failed` is `0` and `totals.verified` equals `totals.files`.
   - No entry in `repositories` has the action `blocked`.

6. Tell the owner `totals.repositories`, `totals.files` and `totals.verified`, every repository with the action `skipped` and its reason, every entry in `kept` (a dist-tag CloudRepo already holds, left as it was), and, from a version older than 0.4.0 or with `--latest-only`, every npm repository whose reason counts versions that did not move.

If the exit code is `1`, read each entry in `failures`, with its `path` and `reason`, remove its cause, and run the second command again, which resumes. If the same file fails twice, stop and report its path and reason to the owner.

Do not put a credential on a command line, in a file or in your answer. Do not change anything in Nexus. Do not repoint builds or switch CI to CloudRepo until the owner tells you to.

---

The page: https://www.cloudrepo.io/docs/migrate/from-nexus-2.html
