Setup GitHub Codespaces
To get you started, we pre-configured a GitHub Codespaces [1] environment with Biodepot-workflow-builder (Bwb) and a test RNA-sequencing (RNA-seq) workflow so that you can run the RNA-seq workflow on the web without any set up on your local computer.
How to run our pre-configured environment on GitHub Codespaces?
To run this demo you will need a connection to the internet, a web browser, and a GitHub account. You don't need any credit card to use GitHub Codespaces, and can get 50 hours per month for free. GitHub Codespaces offers a free plan for personal accounts with a quota of 15 GB-month of storage per month, and 120 hours of compute time per month. See here if you'd like to learn more.
-
Run this workflow in GitHub Codespaces:
-
When opening the GitHub demo, please log into your GitHub account to be granted access to Codespaces services.
-
This should bring up the following screen:
There will be several drop-downs to select from. We decided to set the machine type to
4-core. Depending on the workflow you chose to run, you might need to change these options in the future. -
Click on the "Create Codespace" button to proceed to the Codespace IDE, as shown in the following screenshot:
Bwb auto-starts with Docker, please wait until Bwb starts before attempting to open Bwb. A codespace will take about a minute or two to install Bwb. If you don't see any activity in the ternimal after waiting, you will need to stop and restart your codespace instance.
-
Once the terminal stops scrolling during the Docker install of Bwb, click on the "Ports" tab above the terminal window which is right next to the "Terminal" tab. You should see a table with the following headers "Port", Forwarded Address", "Running Process", "Visibility", and "Origin". There should be an entry in the table.
-
Click on the URL or the globe icon that is associated with port 6080 in the "Forwarded Address" column to open Bwb in a new browser tab.
If a new browser window/tab does not open, make sure to uncheck the "Block pop-up windows" in your browser's security panel. Alternatively, at the end of the "Forwarded Address" column for the same entry, click on the globe icon, and this will open Bwb in a new browser tab. If your browser window is slim, the URL might now show, in which case the globe icon will still be displayed.
Note
If using the Firefox browser, the window that opens after clicking on the globe icon may be caught as a pop-up. When this happens, click on the pop-up blocker icon, then “Allow” the pop-up to be displayed.
Bwb has been extensively tested on Chrome and Firefox. Our tools are not yet optimized for mobile devices.
-
Congratulations! You have now successfully deployed the Bwb on GitHub Codespaces, as shown in the following screen.
Stop/Delete your instance when done
To avoid consuming your free hours on GitHub Codespaces, you will want to stop or delete your instance when you are done. If you do not explicitly stop a codespace, it will continue to run until it times out from inactivity (see GitHub Codecpaces Documentation).
To find the available codespace instances, navigate to https://github.com/codespaces or try one of the following options:
In the top-left corner of a codespace IDE page in your browser, click the menu button, then click "My Codespaces". A new page will appear with a list of available codespaces.
In the top-left corner of GitHub in your web browser, click the menu button, then click "Codespaces". A new page will appear with a list of available codespaces.
In a GitHub repository, click on the green "Code" button, then click the "Codespaces" tab. There will be a list of codespaces available in the box.
Stop a GitHub codespace instance - In "Your Codespaces" page, you will see a list of your codespace instances. Find the instance you want to stop, click the ellipsis (...), finally click "Stop codespace". There will be a message on the top of the screen when the instance has successfully stopped. The same workspace can be relaunched/restarted by clicking on the name.
Delete a GitHub codespace instance - In "Your Codespaces" page, you will see a list of your Codespace instances. Find the instance you want to stop, click the ellipsis (...), click "Delete". You will be prompted with a new window. Click the red button that says "Delete".
Resize Bwb Window - To auto resize the Bwb window in the browser, this will require editing the url in the address bar. If you're working on a workflow with changes, save the changes first as resizing will cause Bwb to reset. The current url should be something like this http://example_address/vnc.html?autoconnect=1, edit the address to http://example_address/?auto and press the enter key. After a few seconds Bwb will reload at the current size of your browser window.
Prevent Workspace Timeout - GitHub Codespaces has a timeout function. If no changes are made through the codespace IDE of the launched workflow, the codespace workspace could automatically close in 30 minutes. To prevent a timeout from happening, simply open a new terminal tab in the codespace IDE, and execute a simple command like ls. Repeat the command every 20 minutes or so to prevent a timeout while running a long workflow.
Troubleshooting
Ports tab doesn't show - If the port tab doesn't show, there may be a conflict with browser plugins or other tabs open. Try restarting your browser and opening the codespace instance without other tabs open.
Bwb shuts down when loading workflow - When opening a workflow on a codespace, sometimes Bwb will not re-launch with the workflow. If this happens, right click the desktop, select "Bwb" and load the workflow again.
Bwb does not load on start - When opening the Bwb window on a codespaces, sometimes Bwb will not have started. If this happens, right click the desktop, select "Bwb" and load the workflow again.
Follow this link for additional troubleshoot tips.
Reference
[1] https://docs.github.com/en/codespaces/about-codespaces/what-are-codespaces