Server

Getting started

Prerequisites

The Crane Server requires Java 11 (or later). Have a look at Adoptium.net or Zulu if you do not have a Java installed yet. Most Linux distributions also provide a Java version that can be used. For now, Crane has only been tested on Linux.

Crane requires an OpenID Connect Server (Identity Provider) that has support for the OAuth 2.0 Device Authorization Grant . We can recommend both Keycloak and Dex if you do not already have an OpenID Connect Server. Keycloak can be used as a standalone solution, where users are directly managed in its interface. Both Keycloak and Dex can also be used to bridge your existing authentication protocol (e.g. an LDAP server) with the OpenID Connect world.

Standalone deployment

This section explains how to use Crane on a fresh Ubuntu 22.04 server. The instructions should also work on Ubuntu 20.04. This section focuses on hosting a simple data directory. The next section shows how to integrate with RDepot.

  1. Install OpenJDK (Java):

    sudo apt update
sudo apt install openjdk-11-jdk

  2. Download Crane:

    sudo mkdir -p /opt/crane
sudo chown $(whoami)
cd /opt/crane
wget https://crane.rdepot.io/downloads/crane-0.1.0.jar

  3. Create a configuration file in /opt/crane/application.yml with the following contents:

    app:
   storage-location: /srv/crane/
   openid-issuer-uri: https://keycloak.example.com/auth/realms/master
   repositories:
      - name: project1
      - name: project2

spring:
   security:
      oauth2:
         client:
            registration:
               crane:
                  client-id: my-example-client-id
                  client-secret: my-example-secret
                  scope: openid
            provider:
               crane:
                  issuer-uri: https://keycloak.example.com/auth/realms/master

    Note: replace the issuer-uri by the issuer URI of your OpenID server as well as the client-id and client-secret.

  4. Create a data directory:

    sudo mkdir -p /srv/crane/project{1,2}
sudo chown -R $(whoami) /srv/crane/
echo "This is a demo file in the project1 directory" > /srv/crane/project1/file1.txt
echo "This is a demo file in the project2 directory" > /srv/crane/project2/file1.txt

  5. Start Crane:

    cd /opt/crane
java -jar crane-1.0.0.jar

  6. Try to access one of the protected files by opening http://my-server:8080/project1/file1.txt in your browser.

You now have Crane running. This is what is happening under the hood:

  • the files in the /srv/crane directory are served by Crane
  • two repositories are configured (project1 and project2). These are subdirectories of the main directory.
  • both repositories are internal repositories, this simply means that every authenticated user can access the files in these repositories.

Integration with RDepot

Follow the instructions on the Rdepot website for deploying RDepot. In case you are running RDepot from the JAR, you can use the instructions above (in the getting started section) to run Crane alongside with RDepot. Just change the app.storage-location property to point to the location of the repository server. Next, configure any repository you wish to expose.

Docker

When using RDepot using the docker-compose setup, you can add Crane by adding a new service to the docker-compose file:

  crane:
    image: openanalytics/crane:0.1.0
    restart: unless-stopped
    hostname: oa-crane
    container_name: oa-crane
    volumes:
      - repository:/srv/crane
      - ./crane.application.yml:/opt/crane/application.yml
    networks:
      - oa-rdepot
    ports:
      - "8080:8080"

Next, create a Crane configuration file at crane.application.yml (see above). Change the app.storage-location option to /srv/crane. After starting the docker-compose stack, you can reach crane at http://localhost:8080. If you configured a repo myrepo, you can reach this repo on http://localhost:8080/myrepo. As a test, you could download the http://localhost:8080/myrepo/VERSION file.

Kubernetes

See https://github.com/openanalytics/rdepot-kubernetes/tree/master/base/crane

Configuration

Repositories

Every single resource that Crane can serve to users is found in repositories app.repositories.

app:
  repositories:
    - name: public_repository
      public: true
      paths:
        - name: private_repository
        - name: restricted_repository
          access-users: demo
        - name: restricted_to_users_repository
          access-users: [demo, test]
    - name: private_repository

Most types of repositories can be configured using only a few lines, since all properties have proper default values. Nevertheless, the configuration can be extended to support more advanced use cases.

TBD

Architecture

TBD

Configuration

Authorization