Skip to main content

Your first Tool

You might have noticed that so far there is not really a lot that we can do with the Arkitekt server so far. We can create datasets, but we cannot really do anything with them. Sure we might comment on them. But that's not really what we want to do. We want to use the data to create something. So its time to install our first App.

In this section we will explore:

  • What are Apps
  • What are Plugins
  • Install our first Arkitekt Plugin (A File Converter)
  • Understand Nodes and Reservations
  • Convert a file

Apps and Nodes​

Before we start using Apps, we need to understand what the term Apps means in the Arkitekt ecosystem. You already go to know "Orkestrator", which is the main app to interface with Arkitekt, it provides us with the graphical interface to tell arkitekt what to do. But who is going to do the work?

Well, that's also Apps. Apps are tools that do the image analysis work. They can be anything from a simple file converter script, to GUI Applications like FIJI or Napari, or complex machine learning algorithm. The only thing that they really have in common is that they interface with the Arkitekt server, and tell it what they can do. They do this by providing so called Nodes to the platform. A Node is a (conceptual defnition of a) functionality an app can provide. It can be as simple as "I can convert. Give me a file from format A and i convert it to format B" or "I can segment, track and analyze cells in a movie, and can give you the tracks as a Table", or a more complex "I can train a machine learning model to segment cells from your data".

The concept of a Node in Arkitekt. Nodes are abstract defintions of bioimage tasks, that help organize the functinality inside the Arkitekt platform. All outside functionality that can be used with Arkitekt must be defined as a node.
About Inputs and Outputs

The node inputs and outputs are of most important to understand. They define what the app expects as input, and what it will give you as output. It is exactly that information that will help us map the data in our server (e.g. a File, or a Dataset) to a correspoing functionality of the app.

Of course the name Node suggests that this is something that is part of a graph. And we will see about it when we start using a Workflow. But for now, lets start simple and find a tool that can convert our data. Well wouldn't it be nice if we had that convert node right now? Well, let's install it.

Installing our First App​

Before we will use some functionality from an outside app (and another installation), lets start simple and let us install an Arkitekt PluginApp. PluginApps are just Apps that are installed and running inside the Arkitekt server. They are not different from any other app, except that they are easily installed through the Arkitekt interface, and can run completely veritualized seperate from your operating system (More about that in "Arkitekt and Containers". Installation of Plugin Apps is a prettry straightforward process and can be done in a few steps:

  1. Click on the Whale/Docker button in the left hand Navigation.

This opens the Plugin Store of Arkitekt. Currently it is completely empty, but we will change that soon. (We will probably add some default apps to easily install in the future, but for now lets do this manually, as it will also help you understand what is happening in the background).

  1. Click on the Add Repository button in the action bar.

This will prompt you for a repository URL. A repository is a collection of (versioned) apps, that can be installed on any Arkitekt server. These repositories represent git repositories, that contain some Arkitekt specific configurations provided by the app developer. You don't need to worry about this, just copy the following values into the prompt:

User: arkitektio-apps Repository: omero Branch: master

  1. Click on the Submit button.

This will add the repository to the list of available repositories. It should have popped up in your Repository list.

  1. Click on the repository

When clicking on the repository you should see a list of apps that are available in this repository. It is important to note that each app (or plugin) has a version number. This version number is an important element of the Arkitekt ecosystem. More about this in Why we version.

  1. Right click on the latest (highest version number) app and click on "Appify".

Now this is one of the most important steps. This will create a new App from the plugin. During this process you will be asked if you trust this app with your (and potential your teams) data, similar to how you trusted the Orkestrator app with your data. This App is trustworthy and we can trust it with our data. So click on "Appify". Then Return to the Plugin Store.

About Trust

Trust is a very important concept in Arkitekt. It seats at the core of the entire platform. Only through these elements of trust do we feel like we can build a platform that is truly open and collaborative, and protect users from potential harmfull apps.

  1. Right click on the newly created App and click on the "Deploy" button.

Last and final step, Deployment. Only when hitting deploy will Arkitekt actually download your app, and install it on the server. This procedure might take quite a while (depending on your internet connection), as it will download the app, and all its dependencies and run in inside a container on the server. Arkitekt will also ask you about an instance name. Just leave main as it is, and click on "Deploy". This will start the installation process.

But don't worry, you can continue working while this is happening in the background, and of course it only happens once.

About the Plugin system

The plugin system is still in its early stages. We are working on making this process more streamlined, and we will some default repositories that you can install from. But for now, this is the way to install apps on the Arkitekt server. Also note that the "progress" indicator is (even though) functional not really accurate. It will show you the progress of the download, and unzipping. But it will not show you the progress of the actual installation. This is something that we will improve in the future. If it seems like its freezing or not doing anything, just wait a little bit longer. It will eventually finish. (Sometime a refresh of the page can also help).

Why do we go through this hurdles.​

You might ask yourself, why do we need to have repositories and containers and why do we need to go through this process. Well, there are a few reasons for this:

  • Security: We want to make sure that the apps that you install on your server are trustworthy. We don't want to have apps that can potentially harm your data, or your server.
  • Updatability: We want to make sure that apps can be updated. This is important for security reasons, but also to make sure that you can always rely on the latest and greatest version of your app. Arkitekt will periodically check for updates of your apps, and will notify you if there are updates available.
  • Versioning: We want to make sure that you can always rely on the same version of an app. This is important for reproducibility, and to make sure that you can always rely on the same functionality. If you want to learn more about this, read Why we version.
  • Portability : Do you know that the App which we just installed had some very specific version requirements for the Java Virtual Machine? Well, you don't have to worry about this. As plugin can package all of that, you can be sure that the app is running in the correct environment, and you don't have to worry about any dependencies.

And we are almost done​

Now that was some steps but we are almost done. If you go back to the Plugin Store you should see that the app is now installed and running. If you click on the running Application you can inspect what is happening in the software container (it will show you the command line in that container), and you can also stop the app if you want to. But for now, lets leave it running.

So how do we use it?​

And this is the most important question. How do we use this app? Where are our nodes? Can we just start using it on our data? Well, not quite yet. There is one last step that we need to do. We need to tell Arkitekt that we want to use some of the functionality of this app. We do this by Reserving our desired nodes.

About Reservations

Reservations are a core concept of the Arkitekt platform. They represent a contract of use between you and the Arkitekt platform, which will try to provide you the reserved Node, and inform you if its currently not available, (Maybe because the connected application is not started yet). Reservations are always bound to a specific User and a specific Node, and connect the Node to one or multiple real-world implementation(s) (e.g. our plugin app). To learn more about reservations, read Reservations.

So lets see how we can reserve a node.

  1. Click the Dashboard button in the left hand navigation.

The Dashboard is another core view of the Arkitekt platform. It shows you all of your reservations (i.e. reserved functionality/node) that are currently active on the platform (you should see none display right now) and the status of the connected applications (you should now see the omero app being display). It will also show you the status of ongoing tasks that you have assigned to the platform.

  1. Open the Search Sidebar by clicking on the Search button in the button left corner.

The search sidebar allows for a platform wide search for functionality (i.e. nodes), irrespective of the applications. You can start typing in the search bar, and it will show you all the nodes that match your search. Search for "Convert" and you should see a node called "Convert Omero". This is the node that we want to reserve.

  1. Drag and Drop or Right Click on the node and click on "Reserve".

This will open a dialog that will ask you for some information about the reservation. Here you can tell Arkitekt specific requests for your reservation. Do you want to use on specific app, do you want to parellize it, do you want to give it a specific name. For now, just leave everything as it is, and click on "Reserve". This will use the "Auto", Scheduler and will reserve the node automatically on the first available app.

  1. You should now see a new Reservation on your dashboard under the "This app uses" section.

Congratulations, you have now reserved your first node. You have told Arkitekt that you want to use the "Convert Omero" node, and Arkitekt will inform you when it is ready to use. It should now appear green in your dashboard. If you click on it, you can see some more information about the reservation, and you can also cancel/unreserve it if you want to. But for now, lets leave it as it is.

Why Reservations

You might ask yourself, why do we need to reserve nodes? Why can't we just use them? Well, this is a highly involved topic and hopefully we will be able to explain it in more detail in the design section of this documentation. In short they help Arkitekt keep track of the dependencies of your function and later our workflows.. For now, just rest assured that you only have to reserve nodes once, Arkitekt will keep track of them until you tell it otherwise.

Convert a file​

But lets finally do the conversion. See you in the next section.