Backup and Restore

The Enterprise Solid Server (ESS) uses a PostgreSQL database to store Resource Description Framework (RDF) data and non-RDF data. By default, ESS stores data in a database named ess.

Prerequisites

The following examples assumes the use of PostgreSQL environment variables for the various connection settings:

  1. Set the following PostgreSQL environment variables:

    • PGHOST for the database server hostname.

    • PGPORT for the database server port (default 5432).

    • PGDATABASE for the database name (default ess).

    • PGUSER for the username.

  2. Set the user password in a password file.

Refer to the your configuration settings to determine the values used for your deployment.

Note

  • For pg_dump and psql, you can specify command-line connection parameters instead.

  • For pod_datastore, you must specify the connection settings via the environment variables and password file.

Backup and Restore a Solid Pod

ESS stores each Pod in its own collection of tables in the ess database. ESS provides the pod_datastore to backup and restore a Pod.

pod_datastore --pod <pod_name> [--data-location <directory>] <backup|restore>
Backup a Pod using pod_datastore

To backup a Pod, you can use the pod_datastore command-line tool. For example, the following operation creates a backup of a Pod whose URL is https://pods.inrupt.com/mypod and places the backup in the /opt/backup/mypod directory:

pod_datastore --pod mypod --data-location /opt/backup/mypod/ backup

  • You must include the --pod option.

  • You can include the --data-location option, specifying the back up directory path. If unspecified, the default value of backup_<pod_name> is used for the directory path.

Restore a Pod using pod_datastore

To restore a Pod, you can use the pod_datastore command-line tool. For example, the following operation restores a Pod whose URL is https://pods.inrupt.com/mypod from the backup in the /opt/backup/mypod directory:

pod_datastore --pod mypod --data-location /opt/backup/mypod/ restore

  • You must include the --pod option.

  • You can include the --data-location option, specifying the back up directory path from which to restore the Pod. If unspecified, the default directory backup_<pod_name> is used.

See also: pod_datastore.

Backup and Restore the ESS Database (pg_dump/psql)

Backup using pg_dump

For PostgreSQL database, you can use the pg_dump command-line tool to extract the content of the specified database.

For example, to dump the ESS database named ess, you can use pg_dump with a compression tool to create a compressed database dump file backup.2020-11-30.sql.gz:

pg_dump ess | gzip > backup.2020-11-30.sql.gz
Restore using psql

For PostgreSQL database, you can use the psql command-line tool to restore the ESS database from the dump files. You can use psql with an unzip tool to restore from a compressed dump file backup.2020-11-30.sql.gz:

gunzip -c backup.2020-11-30.sql.gz | psql ess

For information on PostgreSQL database backup/restore, refer to the PostgreSQL documentation.

Backup and Restore via RDS

Backup

For PostgreSQL database instance managed by AWS Relational Database Service (RDS), you can configure the automatic backup policy at any time either from the AWS Console or Terraform scripts:

  • From the AWS Console:

    1. Open the AWS Management Console.

    2. Go to RDS → Databases → <DB name> → Maintenance and backups tab → Backup.

  • Via the Terraform scripts used in the Installation Guide.

Restore

Step 1 - Restore Database from Backup

The following highlights some key field values when restoring the RDS-Managed database instance. For a complete guide to restoring from a snapshot, refer to Amazon documentation.

  1. Open the AWS Management Console.

  2. Go to RDS → Databases → <DB name> → Maintenance and backups tab → Snapshots.

  3. Select the snapshot version to restore.

  4. Click the Restore button.

  5. In the Restore DB Instance page:

    1. In the Instance specifications, ensure that the DB Instance Class is same as the existing DB instance.

    2. In the Settings section, enter a unique DB Instance Identifier (e.g., ess-<ENV>-postgres-ldp-YYYY-MM-dd-HH-mm).

    3. In the Network & Security section:

      1. Select your ESS VPC and subnet group.

      2. For VPC security groups, select Choose existing VPC security groups.

      3. Remove default.

      4. Select ess-<ENV>-postgres-ldp (VPC).

  6. Scroll to the end and click Restore DB Instance.

Step 2 - Update Database Endpoint in SSM

Once the restored database has the status Available, configure ESS to use this restored database:

  1. Open the AWS Management Console.

  2. Go to RDS → Databases → <restored DB name> → Connectivity & security → Endpoint to find the new endpoint.

  3. In the AWS Systems Manager (SSM) Parameter Store, update the following SSM entries:

    • /ess-<ENVIRONMENT>/postgres-db

      Set to <JDBC URL of the restored DB>/postgres

      (e.g., jdbc:postgresql://ess-prod-postgres-ldp-restored.xxxxxxxx.eu-west-1.rds.amazonaws.com/postgres )

    • /ess-<ENVIRONMENT>/oidc-postgres-db

      If the deployed Solid OIDC Broker service is using the same AWS RDS instance as the LDP service, set to the <JDBC URL of the restored DB>/broker (e.g., jdbc:postgresql://ess-prod-postgres-ldp-restored.xxxxxxxx.eu-west-1.rds.amazonaws.com/broker).

      Note

      In a production deployment, it is highly recommended that you use a separate PostgreSQL instance for the Solid OIDC Broker Service.

Step 3 - Update DB Endpoint in ESS Configuration

  1. Edit 03_config/ess-config.yaml to update the following properties in the ESS ConfigMap with the new JDBC endpoint of the restored DB:

    • LDP_POSTGRES_ENDPOINT

      Existing Value

      New Value

      <old JDBC URL>/postgres

      e.g., jdbc:postgresql://ess-prod-postgres-ldp.xxxxxxxxx.eu-west-1.rds.amazonaws.com/postgres

      <new JDBC URL>/postgres

      e.g., jdbc:postgresql://ess-prod-postgres-ldp-restored.xxxxxxxxx.eu-west-1.rds.amazonaws.com/postgres

    • MONITOR_POSTGRES_ENDPOINT

      Existing Value

      New Value

      <old endpoint>/postgres

      e.g., ess-prod-postgres-ldp.xxxxxxxxx.eu-west-1.rds.amazonaws.com/postgres

      <new endpoint>/postgres

      e.g., ess-prod-postgres-ldp-restored.xxxxxxxxx.eu-west-1.rds.amazonaws.com/postgres

  2. Apply changes to the Kubernetes cluster. The RELEASE_DIR environment variable is set to the directory where you downloaded the ESS configuration files.

    cd ${RELEASE_DIR}/deployment/kubernetes/aws
kubectl apply -f 03_config/ess-config.yaml

Step 4 - Restart Services That Connect to the DB

Restart the services that need to connect to the restored DB:

  • LDP service:

    kubectl rollout restart deployment.apps/ess-ldp  -n ess

  • The backend postgres-metrics service:

    kubectl rollout restart deployment.apps/postgres-metrics -n ess

  • Solid OIDC Broker Service if the OIDC is setup to use the same DB instance as the LDP:

    kubectl rollout restart deployment.apps/inrupt-oidc-deployment -n oidc

Check the status:

  • LDP service:

    kubectl rollout status deployment.apps/ess-ldp -n ess

  • The backend postgres-metrics service:

    kubectl rollout status deployment.apps/postgres-metrics -n ess

  • Solid OIDC Broker Service if the OIDC is setup to use the same DB instance as the LDP:

    kubectl rollout status deployment.apps/inrupt-oidc-deployment -n oidc

Step 5 - Verify that ESS is Working

To verify the changes, see Verify ESS Deployment with Solid OIDC Broker Service.

Administration pod_datastore