windauer / airlock

Take snapshots of Airtable bases for offline browsing and transformation

Airlock

Take snapshots of Airtable bases for offline browsing and transformation

Requirements

• eXist-db version: 5.3.0-SNAPSHOT or greater

• ant version: 1.10.7 (for building from source)

• node version: 12.x (for building from source)

Installation

This package is published to the eXist-db public repository. To install it from there:

1. Open Dashboard on your local eXist-db instance, log into Dashboard as an administrator (user admin and the password you set for this user; the password may be blank if you did not set one up after installing eXist) and click on Package Manager.

2. In the Package Manager window, click on the Available tab, where you will find the package listed. To download and install the package, click on the downward-facing arrow icon in the package description.

Or, if you prefer to download the package from GitHub Releases, follow these directions:

1. Download the airlock-2.1.0.xar file from GitHub Releases page.

2. Open Dashboard as described above, click on the Upload button in the upper left corner, and select the .xar file you just downloaded. (For a full offline installation, you will need to download the latest .xar release of: airtable.xq, Roaster, and exist-markdown too.)

Having installed Airlock, open http://localhost:8080/exist/apps/airlock, log into the app as a user in the airlock group (by default, the app creates a user airlock with password airlock), add your Airtable API Key, add a base ID, and take your first snapshot.

Building from source

1. Download, fork or clone this GitHub repository

2. There are two default build targets in build.xml:

   • dev including all files from the source folder including those with potentially sensitive information.

   • deploy is the official release. It excludes files necessary for development but that have no effect upon deployment.

3. Calling antin your CLI will build both files:

cd airlock
ant

1. to only build a specific target call either dev or deploy like this:

ant dev

If you see BUILD SUCCESSFUL ant has generated a airlock-*.xar file in the build/ folder. To install it, follow the instructions above.

Running Tests

To run tests locally your app needs to be installed in a running eXist-db instance at the default port 8080 and with the default dba user admin with the default empty password.

A quick way to set this up for Docker users is to simply issue:

docker run -dit -p 8080:8080 existdb/existdb:release

After you finished installing the application, you can run the full test suite locally.

Unit-tests

This app uses mochajs as a test-runner. To run both XQuery and Javascript unit-tests, type:

npm test

Integration-tests

This app uses cypress for integration tests, type:

npm run cypress

Alternatively, use npx:

npx cypress open

Contributing

You can take a look at the Contribution guidelines for this project

License

AGPL-3.0 © Joe Wicentowski