Heroku Buildpack for BaseX

This is a 3rd party Heroku buildpack for BaseX based apps. It is based on the node.js buildpack and the common jvm parts used in Java buildpacks.

Documentation

For more information about using this Node.js buildpack on Heroku, see these Dev Center articles:

• Basex
• Heroku Buildpack for the JDK
• Heroku Node.js Support
• Getting Started with Node.js on Heroku
• Troubleshooting Node.js Deploys

For more general information about buildpacks on Heroku:

• Buildpacks
• Buildpack API

Using the Heroku BaseX buildpack

It's suggested that you use the latest version of the release buildpack. You can set it using the heroku-cli.

You need to use the git url. You can use the latest tag to make sure you always have the latest release. The main branch will always have the latest buildpack updates, but it does not correspond with a numbered release.

This buildpack is meant to be used with the gliderlabs/herokuish image primarily in the gitlab AutoDevOps Workflow. Obviously this is a buildpack for the herokuish workflow. You need to set AUTO_DEVOPS_BUILD_IMAGE_CNB_ENABLED to false.

You can emulate that workflow using just a local docker setup:

docker build --build-arg BUILDPACK_URL=https://github.com/simar0at/heroku-buildpack-basex -f ./test/gliderlabs/Dockerfile <your BaseX+nodejs based app>

It may also work with the original heroku service

heroku buildpacks:set https://github.com/simar0at/heroku-buildpack-basex#latest -a my-app

BaseX settings

BaseX uses settings persisted in a .basex file. The following settings can be specified in package.json so they will be set accordingly during build:

[...]
  "basex": {
    "parallel": "8",
    "parserestxq": "3",
    "cachetimeout": "3600",
    "timeout": "30",
    "gzip": "false",
    "fairlock": "false",
  }
[...]

For further documentation see "Options" in the BaseX documentation.

Populating the database during build

If you have a file deployment/initial.sh in your sources this will be executed during build.

• You can use basexclient and the BaseX commands in script form or as bxs XML files to import data.
• You can use for example git or curl to fetch the data from some repository or URL

deployment/initial.sh is called with tha BaseX distribution base directory as parameter and the environment variable BUILD_DIR set to the directory that contains the sources during the build process. (Note that this is not the final location of your app so if you set up anything prefer relative paths.) In this phase of the build process the password for the admin user is still admin.

Testing

This buildpack is meant to run tests using nodejs. This should make it especially easy to create API tests or end to end tests. If you want to run BaseX unit tests you can call basexclient and use the TEST command.

source .heroku/basex/data/credentials
basexclient -u admin -p$BASEX_admin_pw -c 'TEST /app'

The password of the admin user has been randomized. You can get it from the .heroku/basex/data/credentials file.

Persistent BaseX data base

If you want a persistent BaseX database across reboots of the container you have to attach a volume to /app/.heroku/basex/data If the attached volume is empty the initial state of BaseX from the build phase is copied to the mounted volume.

The admin password for BaseX

This buildpack does not use the standard admin password. Instead a randomly generated password is set.

• If you have a persistent data directory the admin password is stored in this directory. So it does not change.
• If you don't interact with the BaseX database in the container using basexclient or the dba BaseX app this does not matter to you. RestXQ apps for example run as admin user without needing to know the password.
• If you need the password it is stored in a text file within the container: /app/.heroku/basex/data/credentials That means: Access to the container means access to the DB so protect that.
• If you want to set a particular password pass the BASEX_admin_pw environment variable to the container and the admin password will be set accordingly.

If you don't set the password using the environment variable a new random password is set every time the container starts.

Using root ('') in your app

There is no way to have two RestXQ functions serving ''. So unfortunately if your app source contains code for '' it will not run in when you just check out the code into a webapp directory of an unzipped ZIP distribution of BaseX. Best practice is that your code usually is located in some "sub directory" /yourapi. In Kubernetes for example you can tell the ingress to automatically forward to /yourapi.

This buildpack provides a mechanism to put a disabled RestXQ function serving '' into your repository that then for example forwards to /yourapi. The idea is to write a usually very small module that as checked into the Git repository disables the %rest:* annotations by specifying a custom URI for the rest prefix.

xquery version "3.1";
module namespace _ = "uri:_";
declare namespace rest = "uri:rest";

(:~
 : Redirects to API path.
 : @return rest response
 :)
declare
  %rest:path('')
function _:index-file() as item()+ {
  <rest:response>
    <http:response status="302">
      <http:header name="Location" value="yourapi/"/>
    </http:response>
  </rest:response>
};

Admin interface and examples

In the ZIP distribution of BaseX there is an admin web UI and a few examples. These are deleted during build. So if you don't supply some sort of forwarding mechanism or your RestXQ code runs in '' a dysfunctional version of the web page you get in the ZIP distribution of BaseX is returned in when accessing ''.

Locking to a buildpack version

Even though it's suggested to use the latest release, you may want to lock dependencies - including buildpacks - to a specific version.

First, find the version you want from the list of buildpack versions. Then, specify that version with buildpacks:set:

heroku buildpacks:set https://github.com/heroku/heroku-buildpack-nodejs#v176 -a my-app

Development

Prerequisites

For local development, you may need the following tools:

• Docker
• Go 1.14
• upx

Deploying an app with a fork or branch

To make changes to this buildpack, fork it on GitHub. Push up changes to your fork, then create a new Heroku app to test it, or configure an existing app to use your buildpack:

# Create a new Heroku app that uses your buildpack
heroku create --buildpack <your-github-url>

# Configure an existing Heroku app to use your buildpack
heroku buildpacks:set <your-github-url>

# You can also use a git branch!
heroku buildpacks:set <your-github-url>#your-branch

Downloading Plugins

In order to download the latest plugins that have been released, run the following:

plugin/download.sh v$VERSION

Make sure the version is in the format v#, ie. v7.

Tests

The buildpack tests use Docker to simulate Heroku's stacks.

To run the test suite:

make test

Or to just test a specific stack:

make heroku-20-build
make heroku-22-build

The tests are run via the vendored shunit2 test framework.

Debugging

To display the logged build outputs to assist with debugging, use the "echo" and "cat" commands. For example:

test() {
  local log_file var

  var="testtest"
  log_file=$(mktemp)
  echo "this is the log file" > "$log_file"
  echo "test log file" >> "$log_file"

  # use `echo` and `cat` for printing variables and reading files respectively
  echo $var
  cat $log_file

  # some cases when debugging is necessary
  assertEquals "$var" "testtest"
  assertFileContains "test log file" "$log_file"
}

Running the test above would produce:

testtest
this is the log file
test log file

The test output writes to $STD_OUT, so you can use cat $STD_OUT to read output.