Developer Setup

Requirements and Preparation

  • Select your development platform. This will likely have to do with the machines that are available for your use. Plant-Tracer/webapp is being deployed on a Linux host, so that’s going to be the best place for runtime debugging. MacOS works well. Windows is not favored, but may work. This file was developed on MacOS Sonoma but should be fine for Ubuntu and other Linuxes. See other doc files such as :doc: DevSetupUbuntu and :doc: WindowsDevSetup for more detail on setting up on those platforms.

  • Install the following things on your development machine, in roughly the order presented, if they aren’t already there. How to do that is beyond the scope of this document.

  • Chrome web browser. While you can use most web browsers with Plant-Tracer/webapp, only Google Chrome and Chromium are used for application testing. So when dealing with development issues, make sure that work on Chrome before getting concerned about other browsers.

  • Package installer. Have a package installer.

    • Homebrew. If installing on a MacOS machine, HomeBrew must be installed prior to performing the steps below.

    • Chocolatey. If installing on a Windows machine, the Chocolatey package manager is recommended.

    • For Linux, use whatever is the favored package manager for that distro. For Ubuntu, it will be apt.

  • Python3.11. Verify that typing ‘python’ gives you python3.11. If it doesn’t, make sure that your PATH is up-to-date.

    • On ubuntu, sudo apt install python3.11-venv (if venv not available by default)

  • make

  • git and gh

  • MySQL 8.0. See MySQL Setup for Plant Tracer

Setup Steps

  1. Clone the Plant Tracer webapp into a directory that will be the local repository, for example:

    git clone https://github.com/Plant-Tracer/webapp.git webapp

  2. Change to the local repository directory:

    cd webapp

  3. Make a Python Virtual Environment (venv):

    make venv

  4. Activate the venv:

    . venv/bin/activate

  5. Install the prerequisites with make install-<your-os>, e.g.:

    make install-macos

  6. Create a new local database

    • The database will be named actions_test by default

    • You may override the default with the PLANTTRACER_LOCALDB_NAME environment variable

    export MYSQL_ROOT_PASSWORD="your-mysql-root-password"
export PLANTTRACER_CREDENTIALS=deploy/etc/credentials-localhost.ini
make create_localdb

  7. Run the self-tests:

    make pytest-quiet

  8. Create your first course! If you want, give it a demo account too:

    • “My Course Name” is the name of the course you are creating. A course in PlantTracer is for a specific delivery of a course, or perhaps a section of a course. PlantTracer assets published in a course are available to all course members.

    • –admin-email is the email address for the first course administrator. It is useful to have a unique email address for the administrator role. For example, if your email address is joecool@company.com, then an admin email address might be joecool+admin@company.com

    • –admin-name “Your Name” should be unique for each admin registration. This is not absolutely necessary but it is helpful to tell under which account you have logged in when using PlantTracer.

    • –demo_email is the email address for a demo user. A demo user is logged in by default when the PlantTracer server is started in demo mode. Omit this parameter if there is no need to use this course in demo mode.

    python dbutil.py --create_course "My Course Name" --admin_email your_admin_email@company.com --admin_name "Your Name" [--demo_email your_demo_email@company.com]
>>> course_key: leact-skio-proih #save this course_key, you will need it later!

  9. You now have a course key! If the demo account is made, you have that too.

  10. In order run a non-demo instance, a mailer must be configured in the credentials ini file, for example:

    [smtp]
SMTP_USERNAME=plantadmin@mycompany.com
SMTP_PASSWORD=MyPassword
SMTP_PORT=587
SMTP_HOST=smtp.mycompany.com

[imap]
IMAP_USERNAME=plantadmin@mycompany.com
IMAP_PASSWORD=MyPassword
IMAP_HOST=imap.mycompany.com
IMAP_PORT=993

  11. If you have created a demo account, that action has also added demo movies to the database. To finish setting up demo mode, run the server in non-demo mode, track all the demo movies manually, and publish them.

Running Locally Quick Start

  1. Run Plant-Tracer/webapp locally using the database created above and the credentials file already specified in the PLANTTRACER_CREDENTIALS environment variable

    make run-local # Ctrl-C to quit

  2. To run a Plant-Tracer/webapp server process locally, examine the debug-* targets in Makefile. The general form is:

    python standalone.py [arguments]

  3. A specific case: running with movies stored in MySQL rather than S3:

    python standalone.py --storelocal

  4. Another case: running in demo mode, with movies stored in MySQL rather than S3:

    • Note: there must be no user logged in for demo mode to take effect. May have to clear browser cookies.

    DEMO_MODE=1 python standalone.py --storelocal

  5. Sometimes, it is necessary to manually clear the cookies that Plant-Tracer/webapp creates in a browser. These cookies are of the form “api_key-“+my_database_name. Here is an example:

_images/PlantTracerCookieExample.png