Merge pull request #325 from florianm/324-docs-and-deps-upgrade

Upgrade installation docs and dependency versions

.dockerignore

@@ -13,3 +13,4 @@ build/
 .vscode/.git/
 .vscode/
 transfer/
+*.code-workspace

.gitignore

@@ -12,3 +12,4 @@ node_modules/
 build/
 .vscode/
 transfer/
+*.code-workspace

Dockerfile

@@ -4,7 +4,7 @@ LABEL maintainer="ODK Build maintainers"
 LABEL description="ODK Build, a drag-and-drop ODK Xforms designer"
 
 # Install system dependencies
-RUN curl -sL https://deb.nodesource.com/setup_14.x | bash - 
+RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
 RUN DEBIAN_FRONTEND=noninteractive apt-get update \
   && DEBIAN_FRONTEND=noninteractive apt-get install --yes \
   -o Acquire::Retries=10 --no-install-recommends \
@@ -14,7 +14,7 @@ RUN DEBIAN_FRONTEND=noninteractive apt-get update \
 
 # Install Ruby gems and ODK Build
 ENV RACK_ENV production
-# The build2xlsform hostname is "odkbuild2xlsform" when run with docker-compose, 
+# The build2xlsform hostname is "odkbuild2xlsform" when run with docker-compose,
 # not "localhost" (the default) as in a source install.
 ENV B2X_HOST odkbuild2xlsform
 WORKDIR /srv/odkbuild/current

Gemfile

@@ -1,12 +1,12 @@
 source 'https://rubygems.org'
 
-gem 'rake'
+gem 'rake', '13.0.6'
 
 gem 'ffi', '1.13.1'
 gem 'sequel', '>= 4.42'
 gem 'pg', '>= 0.18'
-gem 'sinatra', '2.1.0'
-gem "rack", ">= 2.1.4"
+gem 'sinatra', '2.2.0'
+gem "rack", ">= 2.2.3.1"
 gem 'pony', '1.3'
 gem 'warden', '1.0.6'
 gem 'deep_merge', '1.1.1'

Gemfile.lock

@@ -10,31 +10,31 @@ GEM
       mini_mime (>= 0.1.1)
     mini_mime (1.0.2)
     mocha (0.9.12)
-    mustermann (1.1.1)
+    mustermann (1.1.2)
       ruby2_keywords (~> 0.0.1)
     net-http-digest_auth (1.4)
     pg (1.2.3)
     pony (1.3)
       mail (> 2.0)
-    rack (2.2.3)
-    rack-protection (2.1.0)
+    rack (2.2.7)
+    rack-protection (2.2.0)
       rack
     rack-test (0.5.7)
       rack (>= 1.0)
     raindrops (0.19.1)
-    rake (13.0.1)
+    rake (13.0.6)
     riot (0.12.1)
       rr
       term-ansicolor
     rr (1.2.1)
-    ruby2_keywords (0.0.4)
+    ruby2_keywords (0.0.5)
     sequel (5.39.0)
     shotgun (0.9.2)
       rack (>= 1.0)
-    sinatra (2.1.0)
+    sinatra (2.2.0)
       mustermann (~> 1.0)
       rack (~> 2.2)
-      rack-protection (= 2.1.0)
+      rack-protection (= 2.2.0)
       tilt (~> 2.0)
     sync (0.5.0)
     term-ansicolor (1.7.1)
@@ -43,7 +43,7 @@ GEM
       daemons (~> 1.0, >= 1.0.9)
       eventmachine (~> 1.0, >= 1.0.4)
       rack (>= 1, < 3)
-    tilt (2.0.10)
+    tilt (2.1.0)
     tins (1.26.0)
       sync
     unicorn (5.7.0)
@@ -63,13 +63,13 @@ DEPENDENCIES
   net-http-digest_auth (= 1.4)
   pg (>= 0.18)
   pony (= 1.3)
-  rack (>= 2.1.4)
+  rack (>= 2.2.3.1)
   rack-test (= 0.5.7)
-  rake
+  rake (= 13.0.6)
   riot (= 0.12.1)
   sequel (>= 4.42)
   shotgun
-  sinatra (= 2.1.0)
+  sinatra (= 2.2.0)
   thin
   unicorn
   warden (= 1.0.6)

docker-compose.dev.yml

@@ -1,9 +1,9 @@
-# This docker-compose file will deploy the latest tagged image for build2xlsform from ghcr.io,
+# This docker compose file will deploy the latest tagged image for build2xlsform from ghcr.io,
 # 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
+# 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.
+# This is useful to migrate deployment from source to docker compose.
 version: "3"
 services:
   postgres:

docker-compose.yml

@@ -1,7 +1,7 @@
-# This docker-compose file will deploy the latest tagged images from ghcr.io,
+# This docker compose file will deploy the latest tagged images from ghcr.io,
 # which are built and pushed whenever a new Git tag is pushed to GitHub.
 # Use this file to deploy ODK Build to a staging or production server.
-# Run: docker-compose up -d
+# Run: docker compose up -d
 version: "3"
 services:
   postgres:

docs/architecture.md

@@ -1,9 +1,9 @@
 # Architecture
 This document provides a high-level overview of how Build works.
 
-Build is a combination between a Ruby Rack-based application built on Sinatra and a large Javascript frontend. 
-Everything it needs is kicked off by the config.ru Rackup file. 
-We use [shotgun](https://github.com/rtomayko/shotgun) for local development and 
+Build is a combination between a Ruby Rack-based application built on Sinatra and a large Javascript frontend.
+Everything it needs is kicked off by the config.ru Rackup file.
+We use [shotgun](https://github.com/rtomayko/shotgun) for local development and
 [docker-compose](https://docs.docker.com/compose/) for staging and production deployment.
 
 ## Secrets
@@ -13,7 +13,7 @@ The file `config.yml` created from template `config.yml.sample` holds database c
 Ruby Rack, Sinatra
 The export to XLSForm depends on `build2xlsform`. Follow its README to install and run `build2xlsform` locally on its default port 8686.
 
-## Frontend 
+## Frontend
 The frontend is written in Vanilla JS, it uses no frameworks and no modern syntax.
 
 ## Database
@@ -23,11 +23,11 @@ A source install requires an existing Postgres database to be created with corre
 
 ## Dependencies
 <!-- Ruby, Ruby env, system libraries -->
-All Rubygem dependencies are managed by Ruby Bundler. There are config files present for `rbenv`/`rvm`. 
-Run bundle install in the application root to resolve and install the appropriate dependencies. 
+All Rubygem dependencies are managed by Ruby Bundler. There are config files present for `rbenv`/`rvm`.
+Run bundle install in the application root to resolve and install the appropriate dependencies.
 You can do `--without test` to skip some gems if you're short on bandwidth.
 
-We depend on one native binding, to connect to a PostgreSQL database. 
+We depend on one native binding, to connect to a PostgreSQL database.
 To satisfy the binding, you can install `libpq-dev` on apt, or `postgresql` on homebrew.
 
 ## Navigating the code
@@ -59,16 +59,16 @@ Otherwise, files of note include:
 Some changes, like adding support for a new field type, might require an addition to `build2xlsform`. Make sure to test that the export to XLSForm yields a valid XLSForm.
 
 ## Deployment architecture
-<!-- Docker-compose -->
-Build is most recently deployed via `docker-compose`, which brings its own database and `build2xlsform` containers.
+<!-- docker compose -->
+Build is most recently deployed via `docker compose`, which brings its own database and `build2xlsform` containers.
 A bind mount provides a pathway for database dumps to be transferred in and out of the container.
 
 <!-- Historical: ansible, source -->
-In the distant past, Build up to version 0.3.5 was deployed via 
+In the distant past, Build up to version 0.3.5 was deployed via
 [ansible](https://github.com/getodk/build/tree/ansible-deployment) as automated source install behind an nginx server.
 After the Great Spring Clean of 2021&trade;, Build 0.3.6 through 0.4.1 was deployed as a manual source install.
 
 ## Offline version
-<!-- Run docker-compose locally. -->
-The offline version consists of the Build code run through `docker-compose` on a local machine.
+<!-- Run docker compose locally. -->
+The offline version consists of the Build code run through `docker compose` on a local machine.
 

docs/deploy.md

@@ -1,21 +1,21 @@
 # Deployment
 This section contains instructions to deploy Build and the related service build2xlsform to a test or production server.
-The two alternatives are a deployment via `docker-compose` and a source install.
+The two alternatives are a deployment via `docker compose` and a source install.
 
-## docker-compose
-This section explains how to run ODK Build with `docker-compose`.
+## docker compose
+This section explains how to run ODK Build with `docker compose`.
 This is useful for several audiences:
 
 * End users can run this as an offline or self-hosted version of ODK Build. Note, the installation process requires internet connectivity.
 * Developers can verify that the Docker builds still work after code changes.
-* Maintainers can deploy Build with the same toolset (`docker-compose`) as Central.
+* Maintainers can deploy Build with the same toolset (`docker compose`) as Central.
 
 ### First time start-up
-With Docker and docker-compose installed, run
+With Docker and docker compose installed, run
 
 ```
 # via HTTPS
-git clone https://github.com/getodk/build.git 
+git clone https://github.com/getodk/build.git
 
 # or with SSH keys
 git clone git@github.com:getodk/build.git
@@ -25,15 +25,15 @@ git clone git@github.com:getodk/build.git
 The file `docker-compose.dev.yml` will deploy the latest tagged image for build2xlsform from ghcr.io,
 and build the current master as ODK Build image.
 Developers will use this option to test ODK Build during development.
-A copy of this command is also mentioned in `docker-compose.dev.yml`. 
+A copy of this command is also mentioned in `docker-compose.dev.yml`.
 
 ```
 cd build
 git pull
-docker-compose -f docker-compose.dev.yml up -d --build
+docker compose -f docker-compose.dev.yml up -d --build
 ```
 
-This will run ODK Build on `http://0.0.0.0:9393/`, together with its Postgres database 
+This will run ODK Build on `http://0.0.0.0:9393/`, together with its Postgres database
 and the related service `build2xlsform` providing an export to XLSForm.
 
 #### Latest official images
@@ -42,14 +42,14 @@ which are built and pushed whenever a commit is pushed to GitHub.
 Maintainers will use this option to deploy ODK Build to a staging or production server.
 
 ```
-docker-compose up -d
+docker compose up -d
 ```
 
 ### Stop Build
-To stop the images, run 
+To stop the images, run
 
 ```
-docker-compose stop
+docker compose stop
 ```
 
 The named database volume will survive even a destructive `docker-copmose down`, which removes
@@ -61,12 +61,12 @@ Pull the latest changes and rebuild/restart the images.
 ```
 cd build
 git pull
-docker-compose up -d --build
+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. 
+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,
@@ -80,12 +80,12 @@ To restore the database dump into the container:
 
 ```
 # Find the container name: build_odkbuild_1
-> docker-compose ps
-        Name                       Command               State                    Ports                  
+> 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                                
+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"
@@ -107,7 +107,7 @@ root@build-staging:/srv/odkbuild/current# pg_restore -h localhost -U odkbuild -d
 
 ## Production deployment from source
 This section documents how to deploy Build to a production server via a source install.
-This deployment method has been superseded by the docker-compose deployment.
+This deployment method has been superseded by the docker compose deployment.
 
 ### Deploy build2xlsform
 The symlink `/srv/xls_service/current` points to the unpacked and built production release.
@@ -191,4 +191,4 @@ irb
 irb(main):001:0> require 'digest/sha1'
 irb(main):002:0> Digest::SHA1.hexdigest "--[your_new_password]==[pepper]--"
 Put that hash in the password column in the DB.
-```
+```