Skip to content

GraceDB Local Istance

GraceDB is the GRAvitational-wave Candidate Event Database. For developing purpose one have two possibilities, deploy a basic working istance based on GraceDB Helm Charts or deploy a custom image.

In this page, we assume that kubernetes cluster is properly activated (see here).

GraceDB deployment

The deployment depends on the helm charts defined in GraceDB Helm Charts and Helm Charts defined in this repository.

In the following command substitute <username> with your albert.einstein username, while as password use the token string for a read_api scoped personal access (see Prerequisites ).

Depending on the architecture, additional setting may need to be passed to the Helm installation chart (see here for the possible configurations).

1. Hopskotch and GraceDB deployment

The first step is to add repository address to Helm.

helm repo add --force-update --username <username> gracedb-helm \
        https://git.ligo.org/api/v4/projects/15655/packages/helm/stable

for minikube only

Please not that minikube does not have the traefik service included. The gracedb chart will automaticaly instal this service, but requires the addition of the corresponding helm repository.

helm repo add --force-update traefik https://traefik.github.io/charts

Hopskotch and GraceDB charts can be installed in the default namespace obtaining a SandBoxed installation of the igwn-alert and gracedb services in this way:

helm  upgrade --install -n default \
    --set storageClassName=<standard|local-path> \
    hopskotch gracedb-helm/hopskotch   
helm  upgrade --install -n default \
    --set traefik.install=<true|false> \
    --set storageClassName=local-path \
    --set publicName="<hostname>" \
    gracedb gracedb-helm/gracedb
where parameters may change among the system

Parameter Name description
storageClassName name of the storage class, in minikube can be omitted while (may be omitted) while in k3s the only availabe storage class is the "local-path" ones
traefik.install select if traefik should be installed along with gracedb, default is true, for k3s this must be false
publicName logical name for gracedb web interface, this name must be resolved by nameserver
Example of tested configurations

The main difference of the K3S system is that the "standard" storage class is not defined and the only availabe storage class is the "local-path" ones. The hostname to be used in the fluxuser2 system is also different to allow to use the local DNS predefined address. That means that their valuse must be specified.

helm  upgrade --install -n default \
    --set storageClassName=local-path \
    hopskotch gracedb-helm/hopskotch   
helm  upgrade --install -n default \
    --set traefik.install=false \
    --set storageClassName=local-path \
    --set publicName="gracedb-dev.ldas.cit" \
    gracedb gracedb-helm/gracedb

To check Helm deployment status use the command

helm ls --namespace default

The main difference of the K3S system is that the "standard" storage class is not defined and the only availabe storage class is the "local-path" ones.

helm  upgrade --install -n default \
    --set storageClassName=local-path \
    hopskotch gracedb-helm/hopskotch   
helm  upgrade --install -n default \
    --set traefik.install=false \
    --set storageClassName=local-path \
    gracedb gracedb-helm/gracedb

To check Helm deployment status use the command

helm ls --namespace default

Hopskotch and GraceDB charts can be installed in the default namespace obtaining a SandBoxed installation of the igwn-alert and gracedb services in this way:

helm install -n default hopskotch gracedb-helm/hopskotch
helm install -n default gracedb gracedb-helm/gracedb
The installation status and the k8s cluster can be monitored using the k8s dashboard

the deployment of graceDB create a webserver to gracedb web interface at address https://. The web server is configured to answer to logical name set in publicName parameter. The default value is https://gracedb.default.svc.cluster.local/. In this case, and similar case where publicName is not mapped by any nameservers or DNS, the local nameserver should be able to resolve this logical name and link it to the localhost. This can be easily addressed by configuring /etc/hosts file both on Linux or MacOS system.

Example of lines to be addedd to /etc/hosts on minikube
127.0.0.1 gracedb.default.svc.cluster.local
127.0.0.1 hopskotch
127.0.0.1 redis-server

Tunnel need for minikube

A tunnel between the local machine and the k8s cluster have to be open with the command (execute in a separate terminal, closing it or killing the process will result in interruption of the tunnel connection):

minikube -p igwn-kube tunnel 

Depending on the driver used when executing minikube this command may be required to be executed as sudo (see, e.g., this comment). If a password is required, use the actual user (sudoer) password (this should be required three times: for gracedb-traefik, hopskotch-server, and traefik). Without this tunnel active it is not possibile to access to webserver inside the cluster.

2. Setting the user permissions on grace DB

To add your username (e.g., albert.einstein@ligo.org) to the list of GraceDB users give the following command

ALL_PERMS=True ./utility/add-account.sh albert.einstein
In this way your local albert.einstein@ligo.org account will be active on the sandboxed installation (with all the permission). albert.einstein now can access the GraceDB database using its own X509 certificate (That can be created by the ligo-proxy-init -H 2400000 albert.einstein command) or using the web interface as described below.

The utility folder is inside the llai-deploy-sandboxed git folder.

3. installing the CA certificate in the browser

The access to GraceDB using the gracedb client needs to provide the signature of the CA autority used to create the certificate of the sandboxed instance. The needed certificate bundle cacerts.pem (defined in the default namespce) can be retrived using the command:

./utility/get_gracedb_ca default
That would create the certificate in the current directory. With this certificate bundle the following command will give access to the sandboxed GraceDB server:
REQUESTS_CA_BUNDLE=cacerts.pem  gracedb -s https://<publicName>/api credentials server
with <publicName> defined at step 1. Use link to import the certificates.

accessing to web interface on a remote host

In case you are using your personal mac/pc to access a gracedb instance on a remote host (like, e.g., on LDAS virtual machines), you will require port mapping. Let's assume you will be using Firefox to access the local SandBoxed GraceDB. Go to settings type 'proxy' in the search bar and open 'Network Settings'. Choose 'Manual proxy configuration', SOCKS Host: 127.0.0.1, Port: 8080 and leave everything else unchanged. Then in your mac/pc's terminal window run the dynamic port mapping command using port 8080. You should be able to access the local gracedb url now.

4. Finalize the user configuration

The last step is the finalization of the permission setting for your local albert.einstein@ligo.org account. Access the admin interface of local sandboxed deployment of GraceDB at the URL https://<localName>/admin/ (Username:admin, Password:mypassword). from Authentication and Authorization administration->Users search your local albert.einstein@ligo.org account. After entering in the Change user interface, in the permission section, choose all available groups, and Save.

Now you are an happy owner of a local instance of GraceDB

To see che global configuration deployed so far

kubectl get pods,svc,deployment,pv,pvc,secrets,jobs --all-namespaces

Advanced deployment

It is possible to deploy a different version of graceDB that may substitute the graceDB deployed with the procedure above.

Running a specific version of gracedb

If one wants to deploy back a different server version of GraceDB server, the command is (to deploy version 2.27.2):

helm upgrade --install gracedb gracedb-helm/gracedb --reuse-values \
            --set gracedb.image="containers.ligo.org/computing/gracedb/server:gracedb-2.27.2"

Running a custom image using minikube

To create a custum GraceDB image into the ignw-kube deployment (and using the tag:mytag) from a local fork of the gracedb server one has to run the followimg command:

minikube -p igwn-kube image build -t "gracedb-custom/development:mytag" .
To run this image in the minikube deployment:
helm upgrade --install gracedb gracedb-helm/gracedb --reuse-values   \ 
                    --set gracedb.image="gracedb-custom/development:mytag"

Clean-up a GraceDB deployment

To clean up a local deployment that general consis consist of the deployment of the three helm charts associate to gracedb, hopskotchm+, and meg. One need to unistall them and to delete the logical names associate to the permenent storage and the data on the permanent volumes associated and the secrets associated to these services.

#### hopskotch ####
helm uninstall hopskotch
#### gracedb ####
helm uninstall gracedb
kubectl delete pvc postgres-persistent-storage-gracedb-postgres-0 db-data-gracedb-0
kubectl delete secrets gracedb-cert-manager-webhook-ca gracedb-ca gracedb-cert-tls