Backing Up Central

ODK Central features an off-site backup system to keep your data safe. For each backup, we extract all your data (including user accounts, forms, and submissions), we encrypt it so that only you can access it, and we send the encrypted result to your Google Drive account for safekeeping.

To see your current backups status, navigate to ‣ System at the top of the Central management website. You should see a status page for backups that looks something like this:

../_images/panel-initial.png

Setting up backups

  1. To set up a new automated backup, click on the Set up now button on the right.

    Tip

    If you see a Terminate button instead of a Set up now button, you already have an automated backup configured. Right now, you can only have one automated backup scheduled at a time. If you wish to change where the backup is saved, you will need to terminate the old one before creating a new one.

  2. You'll be asked to enter an optional passphrase. This passphrase is what the server will use to encrypt your backups. You will be unable to restore the backup without the passphrase, exactly as you type it in here. If you leave this field blank, we will still encrypt your backup data but anybody will be able to decrypt it by doing nothing more than leaving the passphrase blank.

  3. The next step talks about connecting to your Google Drive account to store your backups. When you press Next again, a Google permissions page will appear in a popup. You will need to press Allow to proceed. If you are feeling unsure about granting access, please see the "About Google Drive account access" note at the top of this page.

    ../_images/google-auth.png
  4. Once you press Allow, you will see a screen in the popup which contains a lengthy code, and instructions to copy and paste it back into "your application." Copy the code, switch back to the ODK Central website, and paste it into the Confirmation text box. Press Next to confirm it.

    ../_images/code-google.png ../_images/code-central.png
  5. The setup box should close and you should see a message telling you Success! Automated backups are now configured.

  6. Backups are scheduled to run once a day, at 02:00 server local time. If more than 24 hours pass without a backup completing successfully, you'll want to double check that everything has been correctly set up.

Restoring a backup

Restoring a backup to an ODK Central instance will entirely replace all of its data with the backup. Please be very sure you are restoring to the right place with the right backup snapshot before proceeding.

  1. The first thing you'll have to do is download your backup from Google Drive, which you can do from the Google Drive website. You will find the backups in a folder called ODK Backups. Each file is a single backup snapshot, and each snapshot should be titled backup-{date}T{time}Z.zip.

  2. Once you have the file on your local computer, you will have to transfer that backup snapshot file to your ODK Central server. If you don't know how to do this, and you used our DigitalOcean installation guide, please see their instructions on how to transfer a file to a Droplet.

  3. Once the file is on the server itself, you'll need to log back into it, like you did when you first set up the server.

    Tip

    If you used our DigitalOcean installation steps but can't quite remember how to do this, we suggest reviewing steps 7 and 8 as a reminder, or if you can't remember your password to revisit steps 6, 7, and 8.

  4. Now you'll want to put it in a special place where it can be used by the restore tool: /data/transfer. If, for example, you uploaded the file to /root/backup-2018-01-01T00:00:00Z.zip, you'll want to run this command in order to move it:

    mv /root/backup-2018-01-01T00:00:00Z.zip /data/transfer/
    
  5. Now you need to run the restore script. Please note again that all data on this server is about to be replaced by the backup snapshot data! Anybody currently using the server will be kicked off and all changes made since the last backup will be lost. When you are sure you wish to proceed, run the following commands:

    cd
    cd central
    docker-compose exec node /usr/odk/lib/bin/restore.js /data/transfer/backup-2018-01-01T00:00:00Z.zip 'SECRET_PASSPHRASE'
    

    You'll have to replace the filename following /data/transfer with your own snapshot filename, and the text SECRET_PASSPHRASE with the passphrase you typed when backups were first set up. If you did not set up a passphrase, immediately press Enter after you have finished putting the :file`.zip` filename in:

    docker-compose exec node /usr/odk/lib/bin/restore.js /data/transfer/backup-2018-01-01T00:00:00Z.zip
    
  6. The server will think for a while, and then print some more instructions. You will have to refresh any browser windows you have open to ODK Central to proceed. If you run into error messages at this step, please read them carefully and then seek help on the ODK Forum if you are not sure what to do.