Merge pull request #297 from dbca-wa/296-a-mount-to-bind-them-all

New: docker-compose bind mount to transfer db

Author: yanokwa

.dockerignore

@@ -12,3 +12,4 @@ node_modules/
 build/
 .vscode/.git/
 .vscode/
+transfer/

.gitignore

@@ -10,4 +10,5 @@ public/javascripts/build.js
 tmp/
 node_modules/
 build/
-.vscode/
+.vscode/
+transfer/

BUILDING.md

@@ -104,6 +104,45 @@ git pull
 docker-compose up -d --build
 ```
 
+### Transfer database snapshots
+Both `docker-compose` files mount a transfer directory. 
+On the host, `docker-compose` is run from the cloned Build repository. 
+A folder `transfer` is created inside the cloned repository, which is mounted inside the `postgres` container as `/var/transfer`.
+
+This bind mount can be used to either transfer a database dump from the host (or another machine) into the Docker container,
+or transfer a database dump from the container to the host (or another machine).
+
+```
+root@build-staging:/srv/odkbuild/current# pg_dump -h localhost -U odkbuild -d odkbuild -W -Fc > transfer/db.dump
+```
+
+To restore the database dump into the container:
+
+```
+# Find the container name: build_odkbuild_1
+> docker-compose ps
+        Name                       Command               State                    Ports                  
+---------------------------------------------------------------------------------------------------------
+build_build2xlsform_1   docker-entrypoint.sh node  ...   Up      0.0.0.0:8686->8686/tcp,:::8686->8686/tcp
+build_odkbuild_1        ./contrib/wait-for-it.sh p ...   Up      0.0.0.0:9393->9393/tcp,:::9393->9393/tcp
+build_postgres_1        docker-entrypoint.sh postgres    Up      5432/tcp                                
+
+# Attach to the running container
+> docker exec -it build_postgres_1 /bin/bash -c "export TERM=xterm; exec bash"
+
+# Option 1: Restore a database dump
+root@308c22617da1:/# pg_restore -U odkbuild -f /var/transfer/db.dump
+
+# Option 2: Save a database dump
+root@308c22617da1:/# pg_dump -U odkbuild -Fc > /var/transfer/db.dump
+```
+
+From the host system, the database dump is now accessible as `transfer/db.dump` in the cloned Build source repository.
+
+```
+root@build-staging:/srv/odkbuild/current# pg_restore -h localhost -U odkbuild -d odkbuild -W < transfer/db.dump
+```
+
 ## Source install
 The following sections document how to install Build and its dependencies from source.
 

docker-compose.dev.yml

@@ -2,12 +2,15 @@
 # and build the local version of ODK Build from the Dockerfile.
 # Use this file to test ODK Build during development.
 # Run: docker-compose -f docker-compose.dev.yml up -d --build
+# The bind mount "transfer" serves to transfer database snapshots in and out of the container.
+# This is useful to migrate deployment from source to docker-compose.
 version: "3"
 services:
   postgres:
     image: "postgres:14.1"
     volumes:
       - odkbuild:/var/lib/postgresql/data
+      - ./transfer:/var/transfer:rw
     environment:
       POSTGRES_USER: odkbuild
       POSTGRES_PASSWORD: odkbuild
@@ -33,4 +36,4 @@ services:
     # healthcheck:
     #   test: [ "CMD-SHELL", "nc -z localhost 9393 || exit 1" ]
 volumes:
-  odkbuild:
+  odkbuild:

docker-compose.yml

@@ -8,6 +8,7 @@ services:
     image: "postgres:14.1"
     volumes:
       - odkbuild:/var/lib/postgresql/data
+      - ./transfer:/var/transfer:rw
     environment:
       POSTGRES_USER: odkbuild
       POSTGRES_PASSWORD: odkbuild