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.
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:
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
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.
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.
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.
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.
Stop you lab
Open docker desktop, and click on the stop button on your lab app folder (see 'Find lab app folder' section).
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.
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)
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.
Delete data
After deleting the apps, you can delete the data.
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.
