Initialise deployment notes for gn-auth.

1 files changed, 127 insertions, 0 deletions

diff --git a/topics/authentication/deploying-gn-auth.gmi b/topics/authentication/deploying-gn-auth.gmi
new file mode 100644
index 0000000..c92d06e
--- /dev/null
+++ b/topics/authentication/deploying-gn-auth.gmi
@@ -0,0 +1,127 @@
+# Deploying gn-auth
+
+## Tags
+
+* type: doc, docs, documentation
+* keywords: gn-auth, deployment
+* status:
+* priority:
+* assigned:
+
+## …
+
+︙
+
+### Run Migrations
+
+At this point, you have a container running, but the database is either empty, or the schema could be out of date. To fix that, we need to run some migrations on the database.
+
+1. Stop the service:
+
+```
+$ sudo systemctl stop genenetwork-container.service
+```
+
+2. Make a copy of the original file.
+
+```
+$ cp /export2/guix-containers/genenetwork/var/genenetwork/auth.db ./auth-run-migrations.db
+$ ls -al
+︙
+-rw-r--r--  1 fredm fredm     0 Mar  3 19:27 auth-run-migrations.db
+︙
+$ ls -al /export2/guix-containers/genenetwork/var/genenetwork/auth.db
+-rw-r--r-- 1 guixbuilder11 983 0 Mar  1 21:45 /export2/guix-containers/genenetwork/var/genenetwork/auth.db
+```
+
+***NOTE***: The path "/export2/guix-containers/genenetwork/var/genenetwork/auth.db" is an example. Do change it to suit what you are working on.
+
+Note, also, that the copy has different ownership than the original. We will need to fix that once we successfully run the migrations.
+
+3. Now we can clone gn-auth if we do not have a copy and cd into it:
+
+```
+$ git clone https://git.genenetwork.org/gn-auth/
+$ cd gn-auth
+```
+
+or change into it and update to the latest code:
+
+```
+$ cd gn-auth
+$ git pull origin main
+```
+
+4. Now get a guix shell:
+
+```
+$ ~/opt/guix/bin/guix shell --container --network --share=../auth-run-migrations.db=/home/fredm/auth-run-migrations.db --development --file=guix.scm
+…/gn-auth [env]$
+```
+
+***Note***: You can change the path "/home/fredm/auth-run-migrations.db" in the command to fit your situation.
+
+5. And run the migrations:
+
+```
+…/gn-auth [env]$ yoyo apply --database sqlite:////home/fredm/auth-run-migrations.db ./migrations/auth/
+
+[20221103_01_js9ub-initialise-the-auth-entic-oris-ation-database]
+Shall I apply this migration? [Ynvdaqjk?]: Y
+
+[20221103_02_sGrIs-create-user-credentials-table]
+Shall I apply this migration? [Ynvdaqjk?]:
+
+︙
+
+Selected 49 migrations:
+  [20221103_01_js9ub-initialise-the-auth-entic-oris-ation-database]
+  [20221103_02_sGrIs-create-user-credentials-table]
+
+  ︙
+Apply these 49 migrations to sqlite:////home/fredm/auth-run-migrations.db [Yn]: Y
+Save migration configuration to yoyo.ini?
+This is saved in plain text and contains your database password.
+
+Answering 'y' means you do not have to specify the migration source or database connection for future runs [yn]: n
+```
+
+As you can see from the above, you have to review what migrations you want to run. If you have previously reviewed the migration, you can run the migrations in batch by providing the "--batch" option, e.g.
+
+```
+…/gn-auth [env]$ yoyo apply --database sqlite:////home/fredm/auth-run-migrations.db --batch ./migrations/auth/
+```
+
+6. Leave the shell:
+
+```
+…/gn-auth [env]$ exit                                                                                 /
+exit
+…/gn-auth$
+```
+
+7. Make a backup of the original file:
+
+```
+…/gn-auth$ sudo cp /export2/guix-containers/genenetwork/var/genenetwork/auth.db /export2/guix-containers/genenetwork/var/genenetwork/auth.db.bkp$(date +"%Y%m%dT%H:%M%z")
+```
+
+8. Copy the file that has the migrations run on it onto the original:
+
+```
+…/gn-auth$ sudo cp ../auth-run-migrations.db /export2/guix-containers/genenetwork/var/genenetwork/auth.db
+…/gn-auth$ ls -al /export2/guix-containers/genenetwork/var/genenetwork/
+total 260
+drwxr-xr-x 2 guixbuilder11  983   4096 Mar  3 20:03 .
+drwxr-xr-x 4 root          root   4096 Mar  1 21:38 ..
+-rw-r--r-- 1 guixbuilder11  983 258048 Mar  3 20:06 auth.db
+-rw-r--r-- 1 root          root      0 Mar  3 20:03 auth.db.bkp20240303T20:03-0600
+```
+
+That should copy the file retaining the original permissions.
+
+9. Restart the service:
+
+```
+$ sudo systemctl start genenetwork-container.service
+```