relax-docker

Table of Contents

• What Is relax-docker?
• Requirements
• Quick Start
• How To Add Custom Configuration
• How To Build It (For Development)
• How To Publish It
• How To Contribute
• License
• Support

What Is relax-docker?

A multi-platform/arch Docker version of RelaX - relational algebra calculator. Moreover, this build provides a workaround to facilitate the integration of RelaX Query API with third-party applications/systems. More information regarding this can be found here.

Requirements

• Install Git (only for building and publishing);
• Install Docker Desktop.

Quick Start

• Open a Terminal window and log in into GitHub’s Container Registry using your username and personal access token (details here);

  docker login ghcr.io

• Once you logged in, start the container using the following command:

  docker run -i --init --rm -p 80:8080 -p 3000:3000 ghcr.io/rlaiola/relax:1.1.0

  NOTE: The container uses ports 8080 (RelaX Web app) and 3000 (RelaX API). Port mapping is mandatory for the desired service to work (i.e., the argument '-p HOST_PORT:3000' is needed only if you plan to use RelaX API, and vice-versa).

• Open a Web browser window and visit the URL http://localhost. Voilà! RelaX Web application should work properly;

  

• Run the following command to test the RelaX API. You should get the query result encoded in JSON format;

  curl http://127.0.0.1:3000/relax/api/local/uibk/local/0?query=UiBqb2luIFMgam9pbiBU

  

How To Add Custom Configuration

Increasing Github Rate Limit For API Requests Using Basic Authentication

RelaX Web application and API may need to make calls to GitHub API (i.e., to download datasets specified in GitHub Gists). According to the documentation, "for unauthenticated requests, the rate limit allows for up to 60 requests per hour. Unauthenticated requests are associated with the originating IP address, and not the user making requests." On the other hand, "for API requests using Basic Authentication ..., you can make up to 5,000 requests per hour." Follow the steps below in order to take advantage of a larger request limit:

• Read these instructions to create a personal access token to authenticate with GitHub API;

• Then, start the container setting the GITHUB_ACCESS_TOKEN environment variable (replace the word 'my_token' with the actual personal access token generated in the previous step).

  docker run -i --init --rm -p 80:8080 -p 3000:3000 -e GITHUB_ACCESS_TOKEN=my_token ghcr.io/rlaiola/relax:1.1.0

NOTE: You can check the current and remaining limits using the following command (replace the word 'my_token' with the actual personal access token created before). For details check the documentation.

curl -H "Authorization: token my_token" -I https://api.github.com/users/octocat/orgs

Running On Different Ubuntu Release Images

To run relax-docker built on top of different versions of Ubuntu images, refer to the tags from the table below.

Tag name	Ubuntu version	Code name	Architecture
latest, 1.1, 1.1-jammy, 1.1.0, 1.1.0-jammy	22.04 LTS	Jammy Jellyfish	amd64, arm/v7, arm64/v8, ppc64le, s390x
1.1-focal, 1.1.0-focal	20.04 LTS	Focal Fossa	amd64, arm/v7, arm64/v8, ppc64le, s390x
nightly, nightly-jammy	22.04 LTS	Jammy Jellyfish	amd64, arm/v7, arm64/v8, ppc64le, s390x
nightly-focal	20.04 LTS	Focal Fossa	amd64, arm/v7, arm64/v8, ppc64le, s390x

For example, to use it running on Ubuntu 20.04 LTS (Focal Fossa) on any supported architecture:

docker run -i --init --rm -p 80:8080 -p 3000:3000 ghcr.io/rlaiola/relax:1.1.0-focal

Deprecated Image Tags

The following image tags have been deprecated and are no longer receiving updates:

• 1.0.2
• 1.0.1
• 1.0.0

How To Build It (For Development)

• Clone this repository and set it as your working directory:

  git clone https://github.com/rlaiola/relax-docker.git
  cd relax-docker

• Then, use the commands below to build the image:

  # List downloaded images
  docker images -a
  
  # Build image
  docker build --build-arg REF_BRANCH=main -f Dockerfile -t relax .

How To Publish It

NOTE: These instructions take into account the Docker image generated in the previous section (no multi-platform support).

• After building, set the user and image tags accordingly. The IMAGE_ID's will show up with the docker images -a;

  docker tag IMAGE_ID ghcr.io/rlaiola/relax:1.1.0

• Log in into GitHub's Container Registry using your username and personal access token (details here);

  docker login ghcr.io

• Push the container image to registry.

  docker push ghcr.io/rlaiola/relax:1.1.0

How to Contribute

If you would like to help contribute to this project, please see CONTRIBUTING.

Before submitting a PR consider building and testing a Docker image locally and checking your code with Super-Linter:

docker run --rm \
           -e ACTIONS_RUNNER_DEBUG=true \
           -e RUN_LOCAL=true \
           -e DEFAULT_BRANCH=main \
           --env-file ".github/super-linter.env" \
           -v "$PWD":/tmp/lint \
           ghcr.io/super-linter/super-linter:latest

License

Copyright Universidade Federal do Espirito Santo (Ufes)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

This program is released under license GNU GPL v3+ license.

Support

Please report any issues with relax at https://github.com/rlaiola/relax-docker/issues