Skip to content

Instantly share code, notes, and snippets.

@openfirmware
Created February 18, 2021 18:45
Show Gist options
  • Save openfirmware/e669b7d19914f42bcada681900294a06 to your computer and use it in GitHub Desktop.
Save openfirmware/e669b7d19914f42bcada681900294a06 to your computer and use it in GitHub Desktop.
Restoring Confluence Backups to a VM

Restoring Confluence Backups to a VM

Do you have a Zip archive backup of your Confluence install you want to restore to a VM? This process below will let you log in and access the content. This uses the Confluence and PostgreSQL docker images with Docker Compose to make sure you have the right versions.

Requirements

  • A Confluence backup archive
  • A Linux Virtual Machine (Vagrant, VirtualBox, etc)
  • An Internet Connection (to get the Confluence trial license)

Versions

It is important to find the date for your backup and get the contemporary Confluence version, and the compatible PostgreSQL version. I recommend looking through the Confluence Release Notes and selecting versions until you find one that was released around the same time as your backup. I am not 100% sure if it matters if the version is a few days after or before your version, and I assume it should work unless there is a major version change (5 to 6 to 7 etc).

For the PostgreSQL version, the Confluence documentation lists the Supported Platforms as well. From that page you can change the Confluence version in the drop-down on the top-right to match your desired version.

Docker Image Versions

Check the Docker Hub for the Confluence Server Image and try to filter by a version closest to the one you need.

For PostgreSQL, you can assume the tag will be the short version number, e.g. 9.0, 9.6, 10, 11, etc. You do not need to include the patch versions as the minor versions will include the latest patch version.

VM Setup

Set up your virtual machine in your hypervisor of choice. I have attached a Vagrantfile that works with VirtualBox. I recommend using multiple CPUs to speed up any indexing that Confluence might do, and to allocate a few GB of RAM as Confluence runs on JVM. If your RAM allocation is too low, Confluence may feel "sluggish" and take longer to do certain tasks.

In my case, I found 4 GB of RAM to provide better performance than Confluence Cloud, but your mileage may vary.

Docker Installation

Follow the Docker and Docker-Compose installation instructions for your version of Linux on your VM. In my case I was using Ubuntu 20.04 in a Vagrant VM, but it should work with most recent distributions.

Docker Compose Usage

I have attached a sample Docker-Compose file that you will need to modify for your version of Confluence. Change the image tag from atlassian/confluence-server:6.8.1-alpine to your version; if you want to run 7.11 you would use atlassian/confluence-server:7.11.

While it is possible for some Confluence versions to pass in the database details in environment variables right here, it does not work with all versions. In all cases if the environment variable for database details is omitted you will be entering the details through the web setup wizard.

Note the usage of Datlassian.recovery.password. This will enable the recovery_admin account in Confluence, which you will need to login especially if you were using Confluence Cloud as you may not be able to access the original login system. This recovery_admin account will only be enabled after pre-setup is complete and restarting the Docker container.

Once you have edited the docker-compose.yaml file as you need, you can copy it into your VM. If you are using vagrant, placing docker-compose.yaml in the same directory as Vagrantfile will make it available in the VM at /vagrant/docker-compose.yaml. Copy it to a directory which will be used as the name for the containers:

$ mkdir confluence-compose
$ cd confluence-compose
$ cp /vagrant/docker-compose.yaml .
$ mkdir confluence

We create a directory here for storing Confluence configuration files, and this is mounted inside the Docker container. This is how we get the backup archive into Confluence. Don't copy the file in yet, we have to do that in a very specific step.

Start up the containers using Docker Compose, preferrably in the background. We will do the web setup wizard, restore the backup, restart the containers, and then have full access to Confluence.

$ sudo docker-compose up -d

Confluence Setup

Caution: If you make a mistake here, Confluence may become "stuck" and get in an unrecoverable state where you cannot continue or restart the web setup wizard. In this case, you have to stop the Confluence and Postgres containers, delete them and the confluence mounted directory, and start over.

Note: Some of the steps here are slightly different based on the version of Confluence. These steps are for version 6.8.1.

On your host machine, access the web server on port 8080 in your VM; if you used Vagrant, the private network address would be http://192.168.33.201:8090/. This site will load the Confluence setup wizard.

First step is add-ons. I did not use "Confluence Questions" or "Confluence Team Calendars" so I skipped these.

Second step is the license key. You can get a free evaluation license, but you will need an Atlassian account. Follow the instructions for a free Confluence Data Center trial license. I don't think you will have to worry about the 90 days of support running out. I highly recommend copying down the key that is generated and saving it, as if you have to restart this process you can re-use the key.

Next is setting up a cluster node. We only need a single cluster just to access the wiki backup, so enter whatever as the cluster name. For the Shared Home Directory, use /var/atlassian/application-data/confluence/shared-home. This directory is also mounted on the VM running Docker Compose, and we will need that in a moment. For the interface, the default eth0 is adequate; again as we are only running a single node it should not matter what you choose. To keep this simple, use multicast and automatically generate the multicast address.

Next is setting up the database. As the containers aren't linked or using a Docker network, we can use the VM's address to access PostgreSQL here. Select "by connection string", and use the following parameters:

  • Database URL: jdbc:postgresql://192.168.33.201:5432/confluencedb
  • Username: confluencedb
  • Password temppassword

Hit "Test Connection" and make sure it works, then hit the Next button. This step will take a minute or two to complete.

Load Content

It is important not to select the wrong option here, or else you have to restart the process.

Select "Restore from Backup". As your wiki backup is probably larger than 30MB, you should not use the upload option. Instead we will restore from the Confluence Home Directory. This creates a restore directory that we need to copy the Zip file into.

If you are using Vagrant, you can put your Zip file in the directory with the Vagrantfile and make it available in the VM. It is very important to copy it to the correct directory, which can be different depending on your Confluence version.

Make sure you find the correct path to the restore directory!

Also we need to make sure the ownership is correct for Confluence to read the backup file. We can use ls -lh to see the UID and GID.

$ cd /home/vagrant/confluence-compose
$ sudo ls confluence
bundled-plugins  confluence.cfg.xml  index  journal  lock  logs  plugins-cache  plugins-osgi-cache  plugins-temp  shared-home  temp  webresource-temp
$ sudo ls -lh confluence/shared-home
total 28K
drwxr-xr-x 2 2002 2002 4.0K Feb 18 18:23 analytics-logs
drwxr-xr-x 2 2002 2002 4.0K Feb 18 18:23 attachments
drwxr-xr-x 2 2002 2002 4.0K Feb 18 18:23 backups
drwxr-xr-x 2 2002 2002 4.0K Feb 18 18:22 config
drwxr-xr-x 2 2002 2002 4.0K Feb 18 18:23 imgEffects
drwxr-xr-x 2 2002 2002 4.0K Feb 18 18:24 restore
drwxr-xr-x 3 2002 2002 4.0K Feb 18 18:23 viewfile

$ sudo cp /vagrant/wiki_yyyymmdd.zip confluence/shared-home/restore/.
$ sudo chown 2002:2002 confluence/shared-home/restore/wiki_yyyymmdd.zip

Now the file should be available in the web interface. However it is still not listed in the restore box. DO NOT reload the page using your browser. Select "No files in directory." and hit the "Restore" button, and it will safely reload the page.

On reload, you should see your Zip file as an option; select it and hit the "Restore" button again.

This next page will take a few minutes or longer depending on the size of your archive.

After the restore, you can "Start" or select "Further configuration". It doesn't matter what you choose because the recovery admin still needs to be enabled. You will notice that Confluence should reflect the look and feel you had in your backup.

Restart and Access

Back on the VM, restart the containers and the Recovery Admin will be enabled.

$ docker-compose restart

After about a half-minute, Confluence should be back online. Log in with the Username recovery_admin and the Password adminpassword.

Once logged in, you will probably get a few warning and notifications. You can ignore the Java Version and End of Life warnings. If you are warned about Collaborative Editing, you can turn that off in admin settings as you probably aren't going to need it.

Do not drop access for the recovery admin until you are sure you have extracted all the content you need from your backup.

If you cannot see your Spaces in the spaces directory, instead go to the admin page and select Space Permissions, and access them from there.

Hopefully now you have access to your Confluence backup! You may see issues loading macros and plugins, or content that linked to Jira; I'm not sure how to fix this without also restoring a contemporary Jira backup.

version: '2'
services:
confluence:
depends_on:
- db
image: atlassian/confluence-server:6.8.1-alpine
volumes:
- ./confluence:/var/atlassian/application-data/confluence
environment:
- "JVM_MAXIMUM_MEMORY=2048m"
- "JVM_SUPPORT_RECOMMENDED_ARGS=-Datlassian.recovery.password=adminpassword"
ports:
- "8090:8090"
- "8091:8091"
db:
image: postgres:9.6
environment:
- "POSTGRES_USER=confluencedb"
- "POSTGRES_PASSWORD=temppassword"
- "POSTGRES_DB=confluencedb"
ports:
- "5432:5432"
# -*- mode: ruby -*-
# vi: set ft=ruby :
Vagrant.configure("2") do |config|
config.vm.box = "bento/ubuntu-20.04"
config.vm.network "private_network", ip: "192.168.33.201"
config.vm.provider "virtualbox" do |vb|
vb.memory = "4096"
vb.cpus = 4
end
end
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment