Migrating Bookstack to another machine / domain

This post is a memo about how to move a Bookstack Docker container to another machine.

Moving a container to another machine is not hard and depends on how you set up your Docker installation on your host. In my case, each of my docker apps on a specific host are located in its own folder. Rsync’ing a folder to another server is easy.

But since Bookstack’s URLs (files / pages / etc..) are hardcoded in its database, you also need to update all the database entries containing your current machine IP / domain to the new domain URL. There are many ways to achieve this, and performing a SQL REPLACE command is certainly a good one.

If you don’t want or can’t perform such commands, here’s another method : dumping the database, modifying this file, and restoring it. A bit rough but it works.

1- Dumping Bookstack’s database

Log in your Bookstack DB container :

docker exec -it your_bookstack_db_container /bin/bash

Next, let’s perform the database dump. The root password is set in my docker-compose.yml file in my case :

mysqldump -u root -p bookstack_db_name > dbdump

Move the dump file to a mapped folder reachable from outside the container. In my case, /config is mapped as /data in my bookstack app folder :

mv dbdump config/

2- Editing the dump

Now that the dump file is reachable from your host, stop the container :

docker stop your_bookstack_db_container

Edit the file with an editor like nano :

cd your_container_data_folder && sudo nano dbdump

Then find and replace all the entries containing the old URL with the new one using the “replace” function of your editor (CTRL + \ in nano). Save the file and exit.

3- Restoring the edited dump file

Restart the Bookstack DB container and log into it once again :

docker start your_bookstack_db_container && docker exec -it your_bookstack_db_container /bin/bash

Go to the folder containing the edited file and perform the restore operation :

cd config/
mysql -p -u root bookstack_db_name < dbdump

You can now stop the container, as it’s ready to be moved.

docker stop your_bookstack_db_container

4- Moving the container to the new server

Move the container to your new server. In my case, I move it between two VMs in my lab, using RSYNC to keep files permissions and ownership :

sudo rsync -avog your_bookstack_folder/ user@destination:/some/location

Log in to the new server. I wrote a post a while ago about how to set up Bookstack using docker-compose. In the docker-compose.yml file, edit the “APP_URL” parameter with the new server’s IP or domain. Then bring up your stack :

docker-compose up -d

Once the images are downloaded and extracted, go to your Bookstack’s new URL and check if the all medias and files are available.

Conclusion

This dump-editing method is not as elegant as performing proper SQL commands, but it works well in this case, since Bookstack DB is small and easy to edit. I’m not an SQL guru at all, but if I find a way to do it with SQL commands, I’ll edit this post and I’ll add them here.

Leave A Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.