Local Development Setup

Overview

A guide to setting up and using VM Lab in a local environment.

Note

Approach recommended for the developement environment.

IDE Compatibility

VM Lab development works with popular Python IDEs, like:

• Visual Studio Code
• PyCharm

Prerequisites

Ensure you have the following installed on your machine:

• PostgreSQL
• Python 3.12.9

Warning

You must use the Python Version 3.12.

The latest minor version that I've tested is the number 9, but I'm not sure if it works even for the numbers above it.

Also, ensure that the two modules are active before building the main app:

• SSH Module
• SFTP Module

Steps

1. Clone the VM Lab main repository to your machine.

   git clone https://github.com/isislab-unisa/vm-lab.git

Database configuration

2. Connect to PostgreSQL using either of the following methods:

   • psql command line tool.
     • psql -U <user>
   • PyCharm's query console (after defining the PostgreSQL data source).

3. Create the database by executing this query:

   CREATE DATABASE "vm-lab"
       WITH
       OWNER = postgres -- or another user
       ENCODING = 'UTF8'
       LOCALE_PROVIDER = 'libc' -- omit this on Windows
       CONNECTION LIMIT = -1    -- omit this on Windows
       IS_TEMPLATE = False;

4. Create the tables by running the init-db.sql script, or pasting its content directly into your SQL console.

   • psql -U <user> -d "vm-lab" -f "path\to\init-db.sql"

Application configuration

4. Create the Python Virtual Environment:

   python -m venv .venv

5. Activate the Python Virtual Environment.

   Linux/macOS:

   source .venv/bin/activate

   Windows PowerShell:

   .venv\Scripts\Activate.ps1

6. Install the project dependencies from the requirements.txt file:

   pip install -r requirements.txt

7. Edit the first_users.yaml file to define initial users.

   first_users:
      # Example User 1
      - username: jsmith
         email: [email protected]
         first_name: John
         last_name: Smith
         password: abc
         role: admin
      
      # Example User 2
      - username: rbriggs
         email: [email protected]
         first_name: Rebecca
         last_name: Briggs
         password: def
         role: regular

Caution

Add at least an admin.

Warning

Do not include sensitive credentials. Use simple default values and change them later via the system UI.

8. Edit template_secrets.toml to match your local environment (e.g., database user, password, etc.).

Note

For more information on how to generate the keys, see here.

9. Rename the template_secrets.toml file to secrets.toml and move it to the .streamlit folder.

   mv template_secrets.toml .streamlit/secrets.toml

Running the application

You can run the application in several ways.

Tip

On the first run, when it promts for an email, press enter.

Streamlit CLI

Run the app directly with Streamlit:

streamlit run app.py

Provided Scripts

Use the provided platform-specific scripts to activate the environment and run the app.

Linux/macOS:

./run_unix.sh

Windows:

run_windows.bat

PyCharm

If you're using PyCharm, select the "Streamlit Run App" configuration found in the .idea directory.