#title Migrations
#cat howto
#pubdate 2026-05-27
#teaser How to migrate one or more sites from an instance to another.

Before you start, **make sure you have a clean publishing queue**.
Changes which are sitting in the Pending revisions page will not
carried over.

You should migrate one site at time. In this guide we assume that you
are using a Debian package, and we are going to migrate the
documentation site, with ID =amw=.

You can start with an =rsync= against the TeX assets, which is
unlikely to change much over the migration chore. You will need to
jump to the =amusewiki= user from time to time (such commands are
prefixed by =$=, while root one with =#=). [1]

[1] The =amusewiki= binary is just a wrapper to make sure you're using
    the correct user in the correct directory.

{{{
# amusewiki shell
$ mkdir -p /var/lib/amusewiki/texmf/tex/generic/amusewiki/data/
}}}


{{{
# rsync -avh \
      oldbox:/var/lib/amusewiki/texmf/tex/generic/amusewiki/data/ \
             /var/lib/amusewiki/texmf/tex/generic/amusewiki/data/
# amusewiki shell
$ texhash `kpsewhich -var-value TEXMFHOME`
}}}

You should also copy the SSL certificates over for the site you are migrating:

{{{
# rsync -avh \
   root@oldbox:/var/lib/amusewiki/ssl/amusewiki.org/ \
   /var/lib/amusewiki/ssl/amusewiki.org/
}}}

As root on the old box, produce the export file:

{{{
# amusewiki clone-site export --directory /tmp/export-sites-$(date -I) amw
}}}

Copy that over and import it.

{{{
# amusewiki clone-site import /tmp/export-sites-$(date -I)/amw.yaml
}}}

Now clone the Git repository in =/var/lib/amusewiki/repo/amw=,
previously removing the tree if needed, so the best option is using
=rsync= and will save you the regeneration of all the existing files.
Using =git clone= is another legitimate option, if you want to start
from scratch.

{{{
# rsync -avh --delete root@oldbox:/var/lib/amusewiki/repo/amw/ /var/lib/amusewiki/repo/amw/
}}}

Update the nginx configuration:

{{{
# amusewiki generate-nginx-conf
}}}

executing the commands it produces to update the nginx configuration.


Finally, under =screen= or =tmux= (as it could take long) run:

{{{
# amusewiki bootstap-archive amw
}}}

This will reindex the site and generate the generated files if missing.

Suggested migration script, to be execute with site code and the
canonical name as arguments:

{{{
#!/bin/bash

set -e
set -x
code=$1
today=`date -I`
oldbox="root@oldbox"

if [ -z "$code" ]; then
    exit 2
fi

name=$2

if [ -z "$name" ]; then
    exit 2
fi

echo "Code: $code, Name: $name"

rsync -avh $oldbox:/var/lib/amusewiki/ssl/$name/ \
      /var/lib/amusewiki/ssl/$name/

ssh $oldbox amusewiki clone-site export --directory /tmp/export-sites-$today $code
mkdir -p /tmp/amusewiki-migration-$today
scp $oldbox:/tmp/export-sites-$today/$code.yaml \
    /tmp/amusewiki-migration-$today/$code.yaml
amusewiki clone-site import \
          /tmp/amusewiki-migration-$today/$code.yaml

rsync -avh --delete $oldbox:/var/lib/amusewiki/repo/$code/ /var/lib/amusewiki/repo/$code/

# silence the notification. You may want to re-enable them later
notify=$(amusewiki set-site-variable --get mail_notify $code)
amusewiki set-site-variable --set mail_notify="" $code


amusewiki generate-nginx-conf | while read line; do
    eval $line || echo ""
done

amusewiki bootstrap-archive $code

# reimport if there are collections/nodes
amusewiki clone-site import \
          /tmp/amusewiki-migration-$today/$code.yaml


amusewiki set-site-variable --set mail_notify="$notify" $code
amusewiki restart
}}}

If you need to move the book covers as well, you'll need to use the =amusewiki bookcover= utility (starting with version 2.615). See the =amusewiki bookcover --help= for details (it basically works the same way as the =clone-site= utility).