Login

Digital lab for Desktop

Constellab digital labs are also available for you on your private computer or server.
You can run the entire lab environment (including codelab) in any Windows, Mac or Linux machine.
Note : the desktop functionality is still in beta and there might be some issues that requires technical knowledge to be fixed. There also might be frequent changes that will require manual manipulations.
This page describes how to install digital lab instances on your computer.
Desktop digital labs can be installed from a private Constellab space or a collaborative space. It will therefore be attached to this space.
However, if it is installed from a collaborative space, you will only have access to this instance and will be responsible for its maintenance. Gencovery will ensure a limited support on desktop instances.
If you want to know more about our on-cloud solutions, please contact our Sales team at sales@gencovery.com.

Requirements

You need the Docker technology installed in you computer. This allows you to run the different required services (lab, codelab, databases, interface, etc.). You can install it here: https://www.docker.com/.
Here are the minimum recommended specifications for your computer to run the lab properly:

  • 4Go RAM
  • 50Go disk space

Note: by default, Docker Desktop will be started when you computer starts, you can disable that in the setting of Docker Desktop.

Windows

For windows, windows 10 or higher is required.
On windows, the first time you launch Docker Desktop there might be a warning about WSL that is not up to date. Please follow the instruction to update WSL. .
Follow the link and install the WSL kernel. Once its install, restart docker and the warning should have disappeared.
https://learn.microsoft.com/fr-fr/windows/wsl/install-manual#step-4---download-the-linux-kernel-update-package

Tutoriel en français pour installer un digital lab desktop

Create your own digital lab

⚠️ We strongly recommend to install only one desktop lab by user so far. Each user has a personal space and may have one or more collaborative spaces. Hence, be careful when choosing the space to connect your new desktop lab.
To create your own digital lab, log in your Constellab account, select the space where you want to connect your new lab.
Click on Add a new digital lab from the Dashboard or from the page "labs" and then select "Desktop".

This will open the lab detail page.

Add project (optional)

You can add the projects you want in your the lab, this will be useful if you want to upload experiment or report to your Space. If you haven't projets so far, you will be able to connect your project later, don't worry.

Configure your lab

Go to Configuration tab and add bricks to your lab. It must have the gws_core brick. Don't forget to save the configuration once you're done.
You must use a version of gws_core equals or higher than 0.5.0
Go back in the lab dashboard and click on Download lab config.
This will open a popup with an input. Leave the input empty and click on save. This will download a zip file that contains the configuration to start the lab on your computer.

Start the lab

Before starting the lab, make sure that Docker Desktop is running (you can execute the Docker Desktop app).
Unzip the file in a safe location where you will retrieve the folder when needed. We will call this folder the lab folder. We recommend to keep the original name of the zip for the folder : constellab-desktop.

Windows exe file

Once the file was unzipped, click on desktop-start.exe.
If you have windows defender the following warning might appear, please click on Additional information then Execute.
If windows detects a threat, clic on the notification, on the file that was just downloaded (check the date), expand the menu and select Autorise on device and validate.
It is also possible that your Antivirus block the file execution. Please remove this file from antivirus check or disable the antivirus. If the antivirus deletes the file, don't worry, you can download the zip file as many time as you want.

Mac and linux executable file

Once the file was unzipped, you should see the desktop-start-mac file. To make this file executable please execute the command line : chmod +x desktop-start-mac .
You can now execute the file : right click on desktop-start-mac and Open with terminal. You can also execute it by running the command : ./desktop-start-mac .

Open lab

The executable file will take some time as it download all the required database and app for the local lab. Once all the app are downloaded, it will start them and open a browser.
The lab is accessible on the url http://localhost:80
You can log in with your Constellab account 🎉. You will need a network connection to login

Start you existing desktop lab

  • Check that docker is running (see section in Troubleshooting)
  • There are 2 solutions to start all the apps of your lab
    • Recommended : Execute the executable file (the on that was in your lab folder). This will start all the apps for the lab and open the browser.
    • Open docker desktop click on the start button on the lab app folder (see 'Find lab app folder in docker desktop'). this will start all the app for the lab. Wait for the lab to be ready and open you browser.

Restart your lab

Open docker desktop, and click on restart on your lab app folder (see 'Find lab app folder' section).
This will restart all the apps of your labs. Wait for your lab to be ready (see 'Check that your lab is running' section) and open the browser.
You can also do the same in command line, open the lab folder and type : docker compose restart -d

Stop you lab

Open docker desktop, and click on the stop button on your lab app folder (see 'Find lab app folder' section).
You can also stop docker by stopping docker desktop. This will automatically stop all you lab apps.

Change brick version

To add a brick of update any brick version of your desktop lab, you must do the following:

  • Open your lab configuration page in Constellab
  • Add or update the brick version
  • Go back in the lab dashboard and click on 'Download lab config'
  • Unzip the file. Move the content of this new zip (3 files) into you lab folder (folder where you originally unzip the lab config). This will replace the 3 existing files in your lab folder, this is normal.
  • Restart your lab (see 'Restart you lab' Section)

Troubleshooting

Check that docker is running

The desktop lab required docker on your computer, to check that docker is running you have 2 solutions.

  • open docker desktop app (this will automatically start docker)
  • open a command line and type docker --version, check the output, an error should occured if docker is not started.

Find lab app folder in docker desktop

Once your lab was created you will find a new folder in docker desktop that contains all the app.
Open docker desktop. In Containers tab you should find a folder with the same name as your lab folder (start with constellab-desktop)

In this folder, you will see all the app (named container) that runs for the lab. You can check the status of the app (exited, running, error).
Here is the list of the apps and their role:

  • glab : this is the main app, this run all the python code, the lab and the experiments.
  • codelab : this is the dev environment that include the online VsCode
  • front : this is the web interface of the lab
  • gws_core_prod_db : database for the prod environment
  • gws_core_dev_deb : database for the dev envirnonment
  • test_gws_dev_db : database that is used when we run tests
  • gws_biota_db : biota database

You can manage all app as once by clicking on the button at the folder level (here constellab-desktop) . You can also manager them independently (not recommended)
To see log of an app (usefull if you lab is not starting) click of the app. The only app where you might need to check the log is the glab app.
You can also find all theses information with docker command lines.
docker ps to list containers
docker logs [container_name] to show log of a container

Check that the lab is running

When you click on the executable, it will wait for the lab to be ready and open the browser.
You can still check if the lab is correctly running manually. First check if docker is running (See 'Check that docker is running' section). Then find the app folder in docker desktop and check that all the app are running. It all app are running, open the url http://localhost:80 in your brower. Try to login or or do any action, if this is working, your lab is correclty started.
If you have an error, please check the logs of glab app. If your lab was correctly started, there should be the following line in the logs :
INFO:   Uvicorn running on http://0.0.0.0:3000 (Press CTRL+C to quit)
The start of the glab app might take a couple minutes (espacially if you have a lot of bricks)

Delete lab apps and data

Delete apps

If you have a problem with you lab you can delete all the lab apps and start your lab (the app will be re-created and you will not have lost your data).
To do this, open docker desktop, and click on the delete button on your lab app folder (see 'Find lab app folder' section)
This will delete the apps but the data will still be here. If you start a new lab, it will use the existing data.
You can also do this in command line, open a command line in your lab folder and execute the following command : docker compose down

Delete data

After deleting the apps, you can delete the data.
After this step, all the data (experiment, resource, dev environment...) will be deleted and cannot be retrieved.
Open the volume section in Docker desktop, search for constellab-desktop and delete all the volumes starting with constellab-desktop.

Troubleshoot

The connection has been lost

This error occurred when the glab app is not running or not ready yet. Please check the 'Check that the lab is running' section to understand what is happening.

Problem during biota download or unzipping

If you have any problem during the download or unzipping of the biota DB, you can delete the mariadb.zip and mariadb folder and re-execute the exe file.