Backing up Data from your Juice Installation#

This guide provides detailed instructions for backing up your data from an OrangeQS Juice installation. The procedures outlined here help ensure data integrity, minimize downtime, and provide troubleshooting tips for common issues.

Summary#

Backup Order

  1. Back up config (/etc/juice by default)

  2. Back up InfluxDB ( Backing up InfluxDB2 Data or InfluxDB Docs)

  3. Back up data (/var/lib/juice by default, excluding /var/lib/juice/influxdb2)

Restore Order

  1. Stop all Juice services

  2. Restore config (/etc/juice by default)

  3. Restore data (/var/lib/juice by default)

  4. Start InfluxDB2 service

  5. Restore InfluxDB2 (Restoring InfluxDB2 Data or InfluxDB Docs)

  6. Start Juice services

Note

OrangeQS Juice stores operational and historic data in two locations:

  • The InfluxDB timeseries database

  • The filesystem

The configuration of these data stores for a given system can be viewed by loading the orchestration config with the following snippet:

from orangeqs.juice.orchestration.settings import OrchestrationSettings
cfg = OrchestrationSettings.load()

cfg hosts the full validated configuration of the setup. The relevant fields regarding data stores can be viewed as follows

print(cfg.data_folder)
print(cfg.influxdb2)

Backing Up Filesystem Data#

Since backing up data from the filesystem amounts to copying files, we leave it up to the user or administrator how to back this up. We recommend doing this at least once a week to ensure smooth operations in case of disastrous data loss on the setup.

Backing up InfluxDB2 Data#

Installing the Influx CLI#

Note

After #131, Influx CLI will be installed on Juice systems by default and this section will be removed from the documentation.

The influx CLI is necessary for all operations, first follow the official installation guide to install the CLI.

Next, verify the installation:

influx version

Configuring the Influx CLI#

Configure the CLI with your credentials so you don’t need to pass the host, API token, and organization with every command.

influx config create --config-name CONFIG_NAME \
  --host-url http://localhost:8086 \
  --org ORG_NAME \
  --token API_TOKEN \
  --active

  • CONFIG_NAME: A descriptive name (e.g., local-influx, production-server)

  • HOST_URL: URL of your InfluxDB instance (update if non-standard)

  • ORG_NAME: Your InfluxDB organization name

  • API_TOKEN: Your API authentication token

Verify your configuration with:

influx config list

Creating the Backup#

InfluxDB backups provide a consistent snapshot of your data without blocking ongoing operations.

Full Backup#

influx backup /path/to/backup/dir/

  • What it does: Backs up all organizations, buckets, and metadata at the provided path

Transferring Backups#

After backup creation, transfer the files to local or external storage. It is up to the user or administrator to transfer the data and store it safely.

Verifying Backup Integrity#

Before relying on a backup, test it in a non-production environment:

# On a test server
influx restore /path/to/backup/dir/ --new-bucket TEST_RESTORE

Then verify the data:

influx query 'from(bucket: "TEST_RESTORE") |> range(start: -30d) |> limit(n: 10)'

Restoring InfluxDB2 Data#

Data from an InfluxDB2 backup can be restored to many locations such as another Juice system, data hosting services or even locally hosted InfluxDB instances in case the data is shared with users. For these reasons, we provide some generic guidelines on restoring this data to another influxdb instance and leave it up to users how they would like to implement this.

Before restoring, it is good practice to double check the following:

  • Verify backup integrity

  • Ensure sufficient disk space

  • Test the restore process in a non-production environment

  • Prepare a fallback plan

Important Constraints:

  • Data cannot be restored to buckets with the same name. Use the --new-bucket flag to avoid conflicts.

  • Existing data is moved temporarily during restoration.

  • Restores may be resource-intensive for large datasets.

Performing Restores#

Full Restore#

influx restore /backup/directory/path/

  • What it does: Restores all organizations, buckets, and metadata.

Restore a Specific Bucket#

Using the bucket name:

influx restore /backup/directory/path/ --bucket SOURCE_BUCKET

Or using the bucket ID:

influx restore /backup/directory/path/ --bucket-id BUCKET_ID

  • SOURCE_BUCKET / BUCKET_ID: Specifies the bucket in the backup to restore

Restore to a New Bucket#

influx restore /backup/directory/path/ --bucket SOURCE_BUCKET --new-bucket TARGET_BUCKET

  • TARGET_BUCKET: New name for the restored bucket to prevent conflicts

Restore to a New Server#

  1. Retrieve the admin token from the source instance.

  2. Set up the new instance:

    influx setup --token ADMIN_TOKEN

  3. Perform the full restore:

    influx restore /backup/directory/path/ --full

Recovering from Failed Restores#

If a restore fails, InfluxDB preserves temporary files in the engine directory (default: ~/.influxdbv2/engine).

  1. Locate temporary files:

    find ~/.influxdbv2/engine -name "*.tmp" -type f

  2. Copy each temporary file back to its original location:

    for file in $(find ~/.influxdbv2/engine -name "*.tmp" -type f); do
  dest_file=${file%.tmp}
  cp $file $dest_file
done

  3. Remove the temporary files:

    find ~/.influxdbv2/engine -name "*.tmp" -type f -exec rm {} \;

  4. Restart InfluxDB:

    sudo systemctl restart influxdb

Verify the service status with:

sudo journalctl -u influxdb -f

Verification After Restore#

After restoring, confirm that data is accessible:

  • Query Restored Data:

    influx query 'from(bucket: "TEST_RESTORE") |> range(start: -30d) |> limit(n: 10)'

  • Check Bucket Details:

    influx bucket list

Additional Resources#