1. Setup Project

Vagrant is a tool for managing VMs. We will be using Vagrant to spin up a virtual machine with:

  • Ubuntu 20.04/ python 3.8 / Django 3.2.x,

  • all the project dependencies installed installed inside a virtual environment called “venv” located under /home/vagrant/venv/,

  • mysql server 8 (with root password as “root”) and 3 databases created and migrated: “pearl” as the main database, “resnet” a secondary database that holds resnet homes and “reference_characteristic_db” for reference characteristic data.

1.1. Prerequisites:

  • Install VirtualBox and Vagrant

  • You can use either Virtualbox 6.0.8 with Vagrant 2.2.4 (you can ignore the warning about incompatible guest additions) or Virtualbox 5.2.8 with Vagrant 2.0.3. Both combinations were tested on win10.

  • run vagrant plugin install vagrant-disksize (This plugin makes it possible to set the disk size of the Vagrant VM)

  • clone the project from github.

  • get and add the .env files to their respective directories.

1.2. Steps to create the Dev Env:

  • run “vagrant up” in a terminal in the project root. This command will create the dev environment, install all the project dependencies inside a virtual environment and create the project databases. It will also create aliases for the mostly used commands. You will be able type just “runserver” to run the project instead of “python manage.py runserver”. There is also “shell_plus”, “makemigrations”, “showmigrations” and “migrate”.

  • Once the setup is complete, run “vagrant ssh” to ssh into the VM. When you enter the VM, you are in the project root.

  • create a new user using “python manage.py createsuperuser”

  • Now, just type “runserver” to run the project.

  • To access the project, just open the browser on your host machine and go to “localhost:8000” as usual.

  • To finish the setup, check the Code Quality for setting up code quality tools

1.3. Notes about running the project:

  • The project has 4 different sites (in the django-sense): Cert App, API (provides public APIs as well as backend to the react app), PQS and Green Door.

  • runserver will run the Cert App by default with the local settings

  • runserver --settings=[SETTINGS_MODULE] where SETTINGS_MODULE is in [‘config.settings.local’, ‘config.settings.test’, ‘config.settings.production’]

  • In order to run a certain app (Cert, PQS, Green Door or API), make sure to set the environment variable PEARL_PROJECT to either ‘config.cert.settings’, ‘config.pqs.settings’, ‘config.green_door.settings’ or ‘config.api.settings’ using export PEARL_PROJECT=[value]

1.4. Dumping data into database with vagrant:

  • The first step will be to create a json file containing the data you wish to dump. A script named dump_dbdata under pearlcertification/data_management/management/commands is written to do the job. You only have to add the model you want to dump as an argument in the call_command specific to the app it belongs to.

  • If the app containing your model does not already have a file go to the Files class under pearlcertification/data_management/management/commands/files_dbdata and add an attribute with the app’s name containing the path of the file you have to create.

  • The next step will be to run the dump_dbdata script and your json file will be created under pearlcertification/data_management/management/commands/dbdata.

  • Finally we need to load the file you created. For that to the load_dbdata.py under pearlcertification/data_management/management/commands and add the file’s path in a list named metadata_files.

1.5. Notes about the setup:

  • If you want to run the project with “python manage.py runserver”, you must add “0.0.0.0:8000” at the end of the command, otherwise the server won’t be accessible from your browser.

  • The database lives inside the VM, so importing a db dump should be done inside the VM. The easiest way to do that is echo "drop database ${db_name};create database ${db_name};use ${db_name};source ${db_dump_path};" | mysql -u root -p (you’ll be prompted to enter the root password). So, to import the db dump “pearl.sql” into the “pearl” db:

# assuming "pearl.sql" is in the same directory where the below command is run
echo "drop database pearl;create database pearl;use pearl;source pearl.sql;" | mysql -u root -p

  • You can access the db inside the VM from pycharm by following the instructions from this stackoverflow post. In the general tab of the database popup, make sure to set the host as “0.0.0.0” so that it’s possible to access the db data from the host where pycharm is running.

  • It is possible to have mysql server on the host rather than inside the VM. Just make sure to set the db url env variables with the host “10.0.2.2” (which is the default gateway), that enables the project running inside the VM to access services on the host machine like MySQL.

  • If you’d like to more understand Vagrant, they have a great tutorial here.