Beginners Tutorials

Here, we provide an aggregated but still incomplete list of our recommended starting tutorials as well as the first steps necessary for new developers for the MatD3 database.

• The official Django tutorial - this would be the best starting point. We suggest doing the first six parts of the tutorial. The Django homepage has many more useful tutorials on various topics which are all well written. You’ll probably come back to those as needed.

• The Django tests are written using the Selenium framework.

• reStructuredText (RST) - this format is commonly used for writing technical documentation. When making changes, run make html in the doc directory and then open doc/_build/html/index.html on your personal computer. If happy with the changes, commit and push. The documentation website (e.g. hybrid3-database.readthedocs.io/en/latest/) then automatically pulls the changes from Github and should be up to date within seconds.

  Before pushing, make sure all tests pass:

  source venv/bin/activate
  
  python manage.py test --keepdb # --keepdb is not necessary but will usually save time
  

  If a test fails but you’ve already committed, you can amend the commit by running

  git commit --amend
  

• When updating the code, other than documentation, the changes also need to be pulled from the server side. After pushing changes to Github, ssh to e.g. materials.hybrid3.duke.edu (i.e. the server you have access to) and issue

  cd /var/www/hybrid3-database # Project location on the server
  
  source venv/bin/activate # Activate the Python environment for this project
  
  export DJANGO_SETTINGS_MODULE=mainproject.settings
  
  git pull
  
  ./manage.py collectstatic --noinput # Update static files if necessary
  
  ./manage.py migrate # Update Django models if necessary
  
  sudo systemctl restart hybrid3.socket # Restart the server
  

  Some of those commands will not have an effect when, for example, there were no changes to the models or no static files were updated. But we suggest running them all of them anyway just to be safe. (Why not create a single alias for all those commands in your .bashrc?)

• The data is stored in two different places - the SQL (MariaDB) database and in the directory /var/www/hybrid3-database/mainproject/media. Thus, two actions need to be taken for backing up all data. For making a copy (a dump) of the SQL data, run

  mysqldump -u <user> -p'<password>' materials > dump.sql
  

  which creates a file called dump.sql in the current directory. Replace <user> and <password> by the values of DB_USER and DB_PASSWORD found in /var/www/hybrid3-database/.env. The media folder can be backed up simply with cp -r although we suggest compressing it first. For instance, one might issue

  cd /var/www/hybrid3-database/mainproject/media
  
  mysqldump -u <user> -p'<password>' materials > dump_58c90cc.sql && mv dump_58c90cc.sql ~
  
  tar cjf media_58c90cc.tar.bz2 media && mv media_58c90cc.tar.bz2 ~
  

  where 58c90cc is the short hash of the latest Git commit in this example.

• Basic tutorials on HTML, CSS, and Javascript - this would be a good starting point for learning the basics of these three languages. For a more complete reference for Javascript, see https://javascript.info/.