Update contributing guidelines for CLI and Helm

[lbeckman314]

Overview ⚙️

This PR adds initial CONTRIBUTING.md guide with steps on installing, running, and updating the backup service.

[Copilot]

Pull Request Overview

This PR adds comprehensive contributing guidelines for a backup service, including setup instructions for both CLI and Helm deployment options.

Key changes:

• Added complete CLI installation and usage documentation with command examples
• Included Helm deployment instructions with Kubernetes setup steps
• Documented S3 backup verification process using MinIO client

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[matthewpeterkort]

Some Feedback:

• From this repo it's unclear how this is getting deployed. Link to https://github.com/ohsu-comp-bio/helm-charts/tree/main in the README would be useful!
• https://github.com/ohsu-comp-bio/helm-charts/blob/main/charts/backups/templates/cronjob.yaml It was talked about that there is some method of culling older backups, and keeping around weekly versions once backups are 3+ months older. This way of passively doing backups will be very space inefficient as more and more data enters into the dbs.
• You shouldn't have to keep a seperate secret with PGPASSWORD in it. That can be found base64encoded in local-postgresql secret.
• This should get integrated into our existing helm charts setup, this way it can be launched from a secrets file, and the user can configure which bucket to use for backups also in the secrets file. This way the user will only have to do a helm install.
• No secrets should need to get generated, write that into the helm chart.
• I like this kubectl create job example-job --from=cronjob/backup-service-cronjob --namespace backups job.batch/example-job created but there should also be a restore job too. Restoring a DB should be just as easy as backing one up. This is a good start https://github.com/calypr/backup-service/blob/main/entrypoint.sh but will need to get built out to support restore use case as well from helm environment. The user shouldn't have to exec into the pod to do an operation.
• Limit should be removed here https://github.com/ohsu-comp-bio/helm-charts/blob/main/charts/backups/templates/cronjob.yaml#L32-L33
• Grip graph name can be pulled from global helm config don't hardcode it: https://github.com/ohsu-comp-bio/helm-charts/blob/main/charts/backups/templates/cronjob.yaml#L28-L29. Same with the rest of the variables in this file.
• Putting this in a separate namespace doesn't make that much sense to me since it's pulling data directly from the other namespace: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces.
• You don't need to build a special gripql from a random grip branch anymore. Install latest in pypi: https://pypi.org/project/gripql/#history. There is a breaking change in the query language: all instanaces of G.query(). can be replaced with G. We removed the query(). since it was extra syntax in the query language that wasn't needed.

[lbeckman314]

Review Steps (WIP) 🌀

• 1. Deployment/repo link added to README.md

From this repo it's unclear how this is getting deployed. Link to https://github.com/ohsu-comp-bio/helm-charts/tree/main in the README would be useful!

Commit 4744e0b

• 2. Added culling command + config

https://github.com/ohsu-comp-bio/helm-charts/blob/main/charts/backups/templates/cronjob.yaml It was talked about that there is some method of culling older backups, and keeping around weekly versions once backups are 3+ months older. This way of passively doing backups will be very space inefficient as more and more data enters into the dbs.

Moved to Issue #5

• 3. Removed PGPASSWORD in favor of local-postgresql secret

You shouldn't have to keep a separate secret with PGPASSWORD in it. That can be found base64encoded in local-postgresql secret.

Commit 22357c4

• 4. Added Backup-Service to existing Gen3-Helm Charts setup

This should get integrated into our existing helm charts setup, this way it can be launched from a secrets file, and the user can configure which bucket to use for backups also in the secrets file. This way the user will only have to do a helm install.

PR #83

• 5. Secrets creation/management added to Backup-Service's Helm Chart

No secrets should need to get generated, write that into the helm chart.

Commit 22357c4 ️

• 6. Restore command (from outside K8s cluster) added

I like this kubectl create job example-job --from=cronjob/backup-service-cronjob --namespace backups job.batch/example-job created but there should also be a restore job too. Restoring a DB should be just as easy as backing one up. This is a good start https://github.com/calypr/backup-service/blob/main/entrypoint.sh but will need to get built out to support restore use case as well from helm environment. The user shouldn't have to exec into the pod to do an operation.

Moved to Issue #6

• 7. Limits removed

Limit should be removed here https://github.com/ohsu-comp-bio/helm-charts/blob/main/charts/backups/templates/cronjob.yaml#L32-L33

Commit 8473b3c

• 8. Removed hard-coded GRIP Graph name (and rest of variables) in favor of global Helm config

Grip graph name can be pulled from global helm config don't hardcode it: https://github.com/ohsu-comp-bio/helm-charts/blob/main/charts/backups/templates/cronjob.yaml#L28-L29. Same with the rest of the variables in this file.

Commit 22357c4

• 9. Moved Backup-Service to default Namespace

Putting this in a separate namespace doesn't make that much sense to me since it's pulling data directly from the other namespace: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces.

Tip

See Comment below for test steps to deploy Backup Service to the default namespace ️

• 10. Updated GRIP version to pull + install from PyPi and updated all calls from G.query().example to G.example

You don't need to build a special gripql from a random grip branch anymore. Install latest in pypi: https://pypi.org/project/gripql/#history. There is a breaking change in the query language: all instanaces of G.query(). can be replaced with G. We removed the query(). since it was extra syntax in the query language that wasn't needed.

Commit 483ee12

[lbeckman314]

Important

@matthewpeterkort's review already done. ✔️

@lbeckman314 (self) to implement changes and update here... ⚠️

[lbeckman314]

Deployment Steps

Important

Here we're deploying to the default Namespace in CALYPR-dev ⚙️

1. Update

➜ kubectl config current-context
calypr-dev

➜ kubectl get deployments -n backups
NAME      READY   UP-TO-DATE   AVAILABLE   AGE
backups   1/1     1            1           93d

➜ helm repo update ohsu
Update Complete. ⎈Happy Helming!⎈

➜ helm search repo ohsu 
NAME                    CHART VERSION   APP VERSION     DESCRIPTION
ohsu/backups            0.4.1           1.13.0          A Helm chart for Kubernetes

2. Deploy

Warning

TODO: Currently we are manually setting the S3 credentials for the Bucket the backups will be uploaded to

Ideally this would simply pull in credentials stored in the existing fence-config K8s secret

➜ kubectl create secret generic s3-credentials \
    --from-literal=ACCESS_KEY='example' \
    --from-literal=SECRET_KEY='example'

➜ helm upgrade --install backups ohsu/backups --values values.yaml

3. Create Example Job

➜ kubectl create job example-backup-job --from=cronjob/backup-service-cronjob
job.batch/example-backup-job created

# ~5 minute wait...

➜ kubectl get jobs/example-backup-job
NAME                 COMPLETIONS   DURATION
example-backup-job   1/1           4m34s

➜ kubectl logs jobs/example-backup-job
Backup Complete:
- ENDPOINT: https://aced-storage.ohsu.edu
- BUCKET: calypr-backups
- DIR: calypr-dev/2025-10-08T00:42:34

➜ kubectl delete jobs/example-backup-job
job.batch "example-backup job" deleted

4. Verify Example Backup

➜ mc ls <ALIAS>/calypr-backups/calypr-dev/2025-10-08T00:42:34
  214MiB  CALYPR.edges
  1.9GiB  CALYPR.vertices
     0B   CALYPR__schema__.edges
  1.4MiB  CALYPR__schema__.vertices
  111KiB  arborist_local.sql
  234KiB  fence_local.sql
  6.0KiB  gecko_local.sql
  23MiB   indexd_local.sql
  9.6KiB  metadata_local.sql
  2.9KiB  postgres.sql
   72KiB  requestor_local.sql
  8.0KiB  wts_local.sql

[github-actions]

🎉 This PR is included in version 1.14.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀