Getting Started

Getting started

Prerequisites

Crane requires Java 17 (or later). We recommend the use of OpenJDK, using the packages of your Linux distribution, Eclipse Temurin (Adoptium), Zulu or Amazon Corretto.

To check whether your version of Java is at least version 17, run:

java -version

which should display something along:

openjdk 17.0.10 2024-01-16
OpenJDK Runtime Environment (build 17.0.10+7)
OpenJDK 64-Bit Server VM (build 17.0.10+7, mixed mode)

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 don’t 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 24.04 server. The instructions should also work on Ubuntu 22.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-17-jdk
   

2. Download Crane:

   sudo mkdir -p /opt/crane
   sudo chown $(whoami) /opt/crane
   cd /opt/crane
   wget https://craneserver.net/downloads/crane-1.0.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:
        project1:
          read-access:
            any-authenticated-user: true
        project2:
          read-access:
            any-authenticated-user: true
   
   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 contain the configuration any-authenticated-user: true, this simply means that every authenticated user can access the files in these repositories. See the Authorization page for more information.

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:1.0.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 preceding). 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 repository myrepo, you can reach this repository 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

An overview of all supported configuration properties can be found on the Configuration page.

All resources that Crane can serve are stored in one or more repositories, which must be configured in the configuration file. Each repository can have a different storage-location and different authorization rules. Inside a repository, the authorization can be further refined by using the paths property. This allows to specify different authorization rules for different ( nested) paths. See the Authorization page for more information.

app:
  repositories:
    public_repository:
      read-access:
        public: true
      paths:
        private_repository:
        authorized_repository:
          read-access:
            any-authorized-user: True
        restricted_repository:
          read-access:
            users: demo
        restricted_to_users_repository:
          read-access:
            users: [demo, test]
    authorized_repository:
      read-access:
        any-authorized-user: True

Most 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.