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.