Here is the link to the video demo of using Basil in the stand-alone, command line mode:
Additional video demos showing how to use Basil from this web-portal are available from the following link: https://ceiba.online/vdemos
Welcome to the iCompute.us web portal, your gateway to utilizing Basil, which is a powerful tool for semi-automatic containerization, deployment, and execution of applications and workflows on various cloud computing and supercomputing platforms. This user guide will walk you through the process of using Basil via the iCompute.us web portal.
Basil is a tool that simplifies the process of creating optimized and secure Docker images without requiring in-depth knowledge of Docker image creation. It accepts recipes for building code, generates Dockerfiles on the basis of the recipes, builds Docker images, scans for vulnerabilities, signs the images, and supports pushing images directly to DockerHub if needed. The Docker images generated using Basil can then be run on diverse hardware platforms that support Docker or Singularity. Basil also provides a mechanism for adding an appropriate license file to the Docker images before they are shared publicly. It generates README files as well which contain the instructions on using the Docker images generated by Basil.
The homepage of the Basil website has the information regarding the current functionalities available as well as new updates listed under the "Project News" section.
As of August 23, 2023, the first iteration of Basil development is complete and we are in the beta testing phase of our Minimum Viable Product (MVP) version. In the second iteration, we will add support for providing the software build recipes in additional formats such as: Makefiles and CMakefiles. Currently, Basil can accept the recipes for building the code in the form of bash scripts, commands pasted in the text box provided on its website, or by using predefined templates (provided as YML files). We will also provide the support for generating Singularity image files directly through Basil (currently Basil can generate Docker images which can then be pulled as Singulairy images).
In the third iteration of the Basil development, we will also provide the feature for running the generated Docker/Singularity images on remote supercomputing and cloud computing platforms from the convenience of the web browser.
Accessing iCompute.us: Visit icompute.us and login using your credentials. There are two ways to login, (1) you can either create a new account on the Basil web portal that is linked with your email address, or (2) you can login using CILogon and choose your existing accounts on GitHub, Google/Gmail, or your institutional account accounts to proceed.
Once logged in, navigate to either the "Terminal" tab or the "iSpec" tab.
In the "Terminal" tab, you can interactively provide specifications for building a Docker image by (1) uploading the necessary script and software files as a project folder or directory, (2) navigating to that directory and then, (3) typing basil -b. Complete the required input sections with the correct information regarding your software and a Dockerfile will be generated and shared with you right in your project directory. You can also choose to push the image to a Docker Hub account. If you choose to not push your image to Docker Hub then a link to download the image will be sent to you over email. There is a video demonstration of this process available under the “Help” tab (please select the “Video Demos” option).
In the "iSpec" tab, you can specify the recipe for image creation using scripts, commands, or predefined text templates. Upload any relevant files (source code and input files) needed for building the Dockerfile and follow along the process that involves filling out necessary input fields to build your Dockerfile. In the end you can choose to receive your Dockerfile in one of two ways:
a. Push the generated Docker image to a Docker Hub account by entering the username and access token
b. Receive an email with the link to download the generated Docker image
Generate Dockerfiles and images: After specifying the recipe, click the appropriate button to generate the Dockerfile. In the iSpec tab, you will be shown a completed YAML file based on your input, which is used by Basil to make the Dockerfile and generate the Docker image in the background. The customer will be sent an email regardless of the action taken and the email will contain information and steps on what to do next relevant to your choices.
Build Images again using the Dockerfiles generated by Bail: Basil will automatically build the image using the Dockerfile that it generates. The image will either be sent to a Docker Hub account or shared with you via a link to download the TAR file that contains the image. For more information on how to run the image using both methods, a video demonstration is available under the “Help” tab by selecting “Video Demos”.
Deployment: Images can be deployed or run on user's systems or in the cloud or on supercomputing platforms based on customer needs.
View Images: You can view your generated images in either the Docker Hub account it was pushed to, or you can check your emails for an email by (icomputeus@gmail.com) that will include some attachments as well as a link to download the TAR file, that is the image.
Scan for Vulnerabilities: Basil automatically scans generated images for vulnerabilities, you can review the scan results and address any issues. The vulnerability analysis run by SNYK is attached as a text file named ‘vulnerability_analysis.log’ in the email sent to you after generation.
Sign and Release: If desired, you can sign images and release them in public registries with appropriate licenses.
Add licenses: If desired, you can add a license to your Docker image.
If you wish to build a Docker image on the system of your choice using the Dockerfile generated by Basil, then please make sure that you have Docker or Singularity installed on the system.
Please review the steps below to install Docker. Docker is required even if you would just like to run the Docker image, so it is a good idea to install it beforehand.
Steps for installing Docker on Windows:
Steps for installing Docker on macOS:
Steps for installing Docker on Linux:
Case 1: Docker image available in Docker Hub account
Case 2: Docker image available in Project Basil's Docker Hub account
Case 3: Did not push the Docker image to Docker Hub
NOTE: You will need 'sudo', 'root', 'admin' level permissions on the system on which you need to build a Docker image.
You can interact with Basil via the command line using the "Terminal" tab. Execute commands to specify image specifications, generate files, build images, and more. To start this process, simply head to your project directory and type the command 'basil -b'.
If you encounter issues during any step, please refer to the following resources:
For frequently asked questions, visit the 'FAQ' section on the icompute.us website.
Congratulations! You've successfully learned the basics of using Basil through the iCompute.us web portal. With Basil's powerful capabilities, you can simplify the containerization, deployment, and/or execution of your applications and workflows on various computing platforms.