This is an automated email from the ASF dual-hosted git repository. chibenwa pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/james-project.git
commit dc7bf0be4752f4c4803bab9011fd4abe45022553 Author: Benoit TELLIER <[email protected]> AuthorDate: Fri Aug 28 14:46:37 2026 +0700 [DOC] Mutualize migration page --- docs/modules/servers/nav.adoc | 4 +- .../pages/distributed/operate/migrating.adoc | 6 -- docs/modules/servers/pages/index.adoc | 11 ++++ docs/modules/servers/pages/jpa/index.adoc | 2 +- .../servers/pages/jpa/operate/migrating.adoc | 13 ---- docs/modules/servers/pages/migrating.adoc | 70 ++++++++++++++++++++++ .../servers/pages/postgres/operate/migrating.adoc | 6 -- docs/modules/servers/partials/operate/index.adoc | 2 +- .../servers/partials/operate/migrating.adoc | 31 ---------- 9 files changed, 84 insertions(+), 61 deletions(-) diff --git a/docs/modules/servers/nav.adoc b/docs/modules/servers/nav.adoc index 1271d7f252..f04bac2d22 100644 --- a/docs/modules/servers/nav.adoc +++ b/docs/modules/servers/nav.adoc @@ -67,7 +67,6 @@ **** xref:distributed/operate/logging.adoc[] **** xref:distributed/operate/webadmin.adoc[] **** xref:distributed/operate/metrics.adoc[] -**** xref:distributed/operate/migrating.adoc[] **** xref:distributed/operate/cli.adoc[] **** xref:distributed/operate/cassandra-migration.adoc[] **** xref:distributed/operate/backup.adoc[] @@ -130,7 +129,6 @@ **** xref:postgres/operate/logging.adoc[] **** xref:postgres/operate/webadmin.adoc[] **** xref:postgres/operate/metrics.adoc[] -**** xref:postgres/operate/migrating.adoc[] **** xref:postgres/operate/cli.adoc[] **** xref:postgres/operate/security.adoc[] *** xref:postgres/customization/index.adoc[] @@ -190,7 +188,6 @@ **** xref:jpa/operate/logging.adoc[] **** xref:jpa/operate/webadmin.adoc[] **** xref:jpa/operate/metrics.adoc[] -**** xref:jpa/operate/migrating.adoc[] **** xref:jpa/operate/cli.adoc[] **** xref:jpa/operate/security.adoc[] *** xref:jpa/customization/index.adoc[] @@ -201,3 +198,4 @@ **** xref:jpa/customization/webadmin-routes.adoc[] *** xref:jpa/smtp-only.adoc[] ** xref:test.adoc[] +** xref:migrating.adoc[] diff --git a/docs/modules/servers/pages/distributed/operate/migrating.adoc b/docs/modules/servers/pages/distributed/operate/migrating.adoc deleted file mode 100644 index c79a77a004..0000000000 --- a/docs/modules/servers/pages/distributed/operate/migrating.adoc +++ /dev/null @@ -1,6 +0,0 @@ -= Distributed James Server — Migrating existing data -:navtitle: Migrating existing data - -:xref-base: distributed -:server-name: Distributed James Server -include::partial$operate/migrating.adoc[] \ No newline at end of file diff --git a/docs/modules/servers/pages/index.adoc b/docs/modules/servers/pages/index.adoc index d0b69b746e..5ecf823eab 100644 --- a/docs/modules/servers/pages/index.adoc +++ b/docs/modules/servers/pages/index.adoc @@ -18,6 +18,9 @@ The available James Servers are: * <<jpa,James JPA Mail Server>> (deprecated) * <<test,James Test Server>> +Whichever one you pick, once it is up and running you will likely need to bring your existing emails into it: +xref:migrating.adoc[migrating existing data] is documented once for all the servers. + If you are just checking out James for the first time, then we highly recommend investigating the servers in this order: @@ -66,3 +69,11 @@ future release. Use the <<postgres,Postgres Server>> instead. == James Test Server The xref:test.adoc[*Test Server*] is, as the name suggests, for testing purposes. + + +[#migrating] +== Migrating to a James Server + +Adopting a James Server, or moving from one variant to another, means copying the mailboxes of your users over. +That procedure relies on IMAP and impersonation, and is therefore identical for every server presented above. It +is documented in xref:migrating.adoc[Migrating existing data]. diff --git a/docs/modules/servers/pages/jpa/index.adoc b/docs/modules/servers/pages/jpa/index.adoc index a7e3abe2d5..49d88780c2 100644 --- a/docs/modules/servers/pages/jpa/index.adoc +++ b/docs/modules/servers/pages/jpa/index.adoc @@ -48,7 +48,7 @@ maintained upstream. The xref:postgres/index.adoc[Postgres James server] supersedes it: it also targets small to medium SQL based deployments, but relies on the reactive `r2dbc` driver, is actively maintained, and supports the full James feature set. Read xref:postgres/objectives.adoc[its objectives] for further details, and -xref:jpa/operate/migrating.adoc[the migration guide] to move your data over. +xref:migrating.adoc[the migration guide] to move your data over. == Read further diff --git a/docs/modules/servers/pages/jpa/operate/migrating.adoc b/docs/modules/servers/pages/jpa/operate/migrating.adoc deleted file mode 100644 index a477af06d6..0000000000 --- a/docs/modules/servers/pages/jpa/operate/migrating.adoc +++ /dev/null @@ -1,13 +0,0 @@ -= JPA James Server — Migrating existing data -:navtitle: Migrating existing data - -:xref-base: jpa -:server-name: JPA James server - -include::partial$jpa/deprecated.adoc[] - -TIP: The very same procedure can be used to migrate *away* from the JPA James server: run it against a freshly -deployed xref:postgres/index.adoc[Postgres James server] to copy the mailboxes of your users over, which is the -recommended path given this application is deprecated. - -include::partial$operate/migrating.adoc[] diff --git a/docs/modules/servers/pages/migrating.adoc b/docs/modules/servers/pages/migrating.adoc new file mode 100644 index 0000000000..8beb5381c4 --- /dev/null +++ b/docs/modules/servers/pages/migrating.adoc @@ -0,0 +1,70 @@ += Migrating existing data into a James server +:navtitle: Migrating existing data + +This page presents how operators can migrate their users mailboxes and mails into a James server, in order to +adopt it. The procedure is the same whatever James server you chose, hence this page is common to all of them. + +We assume you have a well configured running James server at hand - +xref:distributed/configure/index.adoc[Distributed], xref:postgres/configure/index.adoc[Postgres] or +xref:jpa/configure/index.adoc[JPA] - and that the existing mails are hosted on a tier mail server, which can be +accessed via IMAP and supports impersonation. + +== Creating the domains and the users + +First, you want to create the domains handled by your server, as well as the users you will be hosting. This +operation can be performed via WebAdmin or the CLI. + +Using WebAdmin: + +* Creating domains: read this section for the +xref:distributed/operate/webadmin.adoc#_create_a_domain[Distributed], +xref:postgres/operate/webadmin.adoc#_create_a_domain[Postgres] or +xref:jpa/operate/webadmin.adoc#_create_a_domain[JPA] server. +* Creating users: read this section for the +xref:distributed/operate/webadmin.adoc#_create_a_user[Distributed], +xref:postgres/operate/webadmin.adoc#_create_a_user[Postgres] or +xref:jpa/operate/webadmin.adoc#_create_a_user[JPA] server. + +Using the CLI: + +* Managing domains: read this section for the +xref:distributed/operate/cli.adoc#_manage_domains[Distributed], +xref:postgres/operate/cli.adoc#_manage_domains[Postgres] or +xref:jpa/operate/cli.adoc#_manage_domains[JPA] server. +* Managing users: read this section for the +xref:distributed/operate/cli.adoc#_managing_users[Distributed], +xref:postgres/operate/cli.adoc#_managing_users[Postgres] or +xref:jpa/operate/cli.adoc#_managing_users[JPA] server. + +== Allowing impersonation + +Second, you want to allow an administrator account of your James server to have write access on other user +mailboxes. This is set up with the *administratorId* configuration option of the *usersrepository.xml* +configuration file, documented for the +xref:distributed/configure/usersrepository.adoc[Distributed], +xref:postgres/configure/usersrepository.adoc[Postgres] and +xref:jpa/configure/usersrepository.adoc[JPA] servers. + +== Copying the emails + +Then, it is time to run the https://github.com/imapsync/imapsync[imapsync] script to copy the emails from the +previous mail server into your James server. Here is an example migrating a single user, relying on impersonation: + +.... +imapsync --host1 previous.server.domain.tld \ + --user1 [email protected] --authuser1 [email protected] \ + --proxyauth1 --password1 passwordOfTheOldAdmin \ + --host2 james.domain.tld \ + --user2 [email protected] \ + --authuser2 [email protected] --proxyauth2 \ + --password2 passwordOfTheNewAdmin +.... + +== Migrating from one James server to another + +The very same procedure applies when moving from a James server to another one: both ends speak IMAP and support +impersonation. This is the recommended path to leave the deprecated xref:jpa/index.adoc[JPA James server] for the +xref:postgres/index.adoc[Postgres James server], which targets the same SQL based deployments. + +Note that this copies the mailboxes and their content only. Domains, users, recipient rewriting rules and +configuration files are to be recreated on the target server, as described above. diff --git a/docs/modules/servers/pages/postgres/operate/migrating.adoc b/docs/modules/servers/pages/postgres/operate/migrating.adoc deleted file mode 100644 index b00a838135..0000000000 --- a/docs/modules/servers/pages/postgres/operate/migrating.adoc +++ /dev/null @@ -1,6 +0,0 @@ -= Postgresql James Server — Migrating existing data -:navtitle: Migrating existing data - -:xref-base: postgres -:server-name: Postgresql James Server -include::partial$operate/migrating.adoc[] \ No newline at end of file diff --git a/docs/modules/servers/partials/operate/index.adoc b/docs/modules/servers/partials/operate/index.adoc index 84cb2dd372..aab1f0c804 100644 --- a/docs/modules/servers/partials/operate/index.adoc +++ b/docs/modules/servers/partials/operate/index.adoc @@ -19,7 +19,7 @@ graphs, that can be visualized, for instance in *Grafana*. We did put together a xref:{xref-base}/operate/guide.adoc[detailed guide] for {server-tag} James operators. We also propose a xref:{xref-base}/operate/performanceChecklist.adoc[performance checklist]. -We also included a guide for xref:{xref-base}/operate/migrating.adoc[migrating existing data] into the {server-tag} server. +We also included a guide for xref:migrating.adoc[migrating existing data] into the {server-tag} server. ifndef::no-opensearch[] Additional functional visualisations can be set up using OpenSearch dashboards as documented in link:https://github.com/apache/james-project/tree/master/examples/opensearch-dahsboard[this example]. diff --git a/docs/modules/servers/partials/operate/migrating.adoc b/docs/modules/servers/partials/operate/migrating.adoc deleted file mode 100644 index 643f9f5a9d..0000000000 --- a/docs/modules/servers/partials/operate/migrating.adoc +++ /dev/null @@ -1,31 +0,0 @@ -This page presents how operators can migrate your user mailbox and mails into the {server-name} in order to adopt it. - -We assume you have a xref:{xref-base}/configure/index.adoc[well configured] running {server-name} -at hand. We also assume existing mails are hosted on a tier mail server which can be accessed via IMAP and supports -impersonation. - -First, you want to create the domains handled by your server, as well as the users you will be hosting. This operation -can be performed via WebAdmin or the CLI. - - * Using webadmin : - ** Read xref:{xref-base}/operate/webadmin.adoc#_create_a_domain[this section] for creating domains - ** Read xref:{xref-base}/operate/webadmin.adoc#_create_a_user[this section] for creating users - * Using the CLI : - ** Read xref:{xref-base}/operate/cli.adoc#_manage_domains[this section] for creating domains - ** Read xref:{xref-base}/operate/cli.adoc#_managing_users[this section] for creating users - -Second, you want to allow an administrator account of your {server-name} to have write access on other user mailboxes. -This can be setted up this the *administratorId* configuration option of the xref:{xref-base}/configure/usersrepository.adoc[usersrepository.xml] configuration file. - -Then, it is time to run https://github.com/imapsync/imapsync[imapsync] script to copy the emails from the previous mail server -into the {server-name}. Here is an example migrating a single user, relying on impersonation: - -.... -imapsync --host1 previous.server.domain.tld \ - --user1 [email protected] --authuser1 [email protected] \ - --proxyauth1 --password1 passwordOfTheOldAdmin \ - --host2 distributed.james.domain.tld \ - --user2 [email protected] \ - --authuser2 [email protected] --proxyauth2 \ - --password2 passwordOfTheNewAdmin -.... \ No newline at end of file --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
