README.md

Scinguistics Archive

The Scinguistics Archive is a WebApp developed to serve the Scinguistics community as a repository for audio recordings of voice lessons and related voice training material.

This WebApp is built using the Django web framework, and uses PostgreSQL as a database and Backblaze B2 as a storage solution for audio recordings. It utilizes django-allauth for user authentication via the Patreon API.

The WebApp is available at https://archive.cramdvoicelessons.blog/, and it was developed by Lílian and Emilia for the Scinguistics team with support from CRAMDVoiceLessons.

specifications

This WebApp is hosted with Heroku provisioned with the Heroku Postgres Add-on and jonathanong's FFmpeg buildpack.

configuration variables

Invoked in scinguistics_archive/settings.py, these should be exported as environment variables and values of IDs and Keys should be kept secret.

• DJANGO_ALLOWED_HOSTS (string of host names separated by comma, e.g. "example.herokuapp.com,127.0.0.1")
• DJANGO_DEBUG (set "True" on test server, "False" on production)
• DJANGO_SECRET_KEY (a large random string, you can use python's secrets.token_urlsafe to produce one)
• DATABASE_URL (parsed by dj-database-url, see schema)
• BACKBLAZE_KEY_ID (from your B2 Application Key [non-master], see Backblaze B2 docs)
• BACKBLAZE_KEY (from your B2 Application Key [non-master], see Backblaze B2 docs)
• BACKBLAZE_BUCKET (your B2 Bucket Name, see Backblaze B2 docs)
• PATREON_CLIENT_ID (from your Patreon API Client)
• PATREON_CLIENT_SECRET (from your Patreon API Client)
• SECURE_SSL_REDIRECT (set "False" on test server, "True" on production)

how to run locally

• clone the repo git clone https://github.com/lily-mosquitoes/scinguistics_archive.git
• start a new virtual env python3 -m pip venv venv then source it source venv/bin/activate
• move into the repo cd scinguistics_archive
• install requirements python3 -m pip install -r requirements.txt
• set all of the config vars
  • remember to start a database service (code uses postgresql, change that in scinguistics_archive/settings.py if using something else)
• in catalog/models.py comment out the Lesson recording variable:
  • # recording = models.FileField(blank=True, null=True, upload_to='uploads', storage=BackblazeB2Storage, help_text='Recording link from the CDN (autofilled from CRAIG/GIARC link)')
• run python3 manage.py createcachetable
  • this will fail if the previously mentioned line is not commented out
• run python3 manage.py makemigrations
• run python3 manage.py migrate
• in catalog/models.py uncomment the Lesson recording variable:
  • recording = models.FileField(blank=True, null=True, upload_to='uploads', storage=BackblazeB2Storage, help_text='Recording link from the CDN (autofilled from CRAIG/GIARC link)')
• run python3 manage.py makemigrations
• run python3 manage.py migrate
• run python3 manage.py collectstatic
• run python3 manage.py createsuperuser
• run python3 manage.py runserver

Now your test server should be accessible from http://127.0.0.1:8000/.

how to deploy with Heroku

• clone the repo git clone https://github.com/lily-mosquitoes/scinguistics_archive.git
• start a new virtual env python3 -m pip venv venv then source it source venv/bin/activate
• move into the repo cd scinguistics_archive
• install requirements python3 -m pip install -r requirements.txt
• install the Heroku CLI
• run heroku login
• run heroku apps:create NAME where NAME is any name you wish to give the app
• check if postgresql is provisioned by running heroku addons
• if not, run heroku addons:create heroku-postgresql:hobby-dev (hoby-dev is the free tier, see tiers here and substitute with the desired tier codename)
• heroku buildpacks:add --index 1 https://github.com/jonathanong/heroku-buildpack-ffmpeg-latest.git
• set the config vars with heroku congif:set VAR_NAME="value"
  • obs: Heroku automatically sets the DATABASE_URL variable
• in catalog/models.py comment out the Lesson recording variable:
  • # recording = models.FileField(blank=True, null=True, upload_to='uploads', storage=BackblazeB2Storage, help_text='Recording link from the CDN (autofilled from CRAIG/GIARC link)')
• run python3 manage.py makemigrations
• run git push heroku main
• run heroku run python manage.py createcachetable
  • this will fail if the previously mentioned line is not commented out
• run heroku run python manage.py migrate
• in catalog/models.py uncomment the Lesson recording variable:
  • recording = models.FileField(blank=True, null=True, upload_to='uploads', storage=BackblazeB2Storage, help_text='Recording link from the CDN (autofilled from CRAIG/GIARC link)')
• run python3 manage.py makemigrations
• run git push heroku main
• run heroku run python manage.py migrate
• run heroku run python manage.py createsuperuser

Now the deployed WebApp should be available at Heroku's provided url, as a shortcut you can run heroku open.

Remember to add and commit changes using git (git add ., git commit -m "commit message"), and re-deploy to Heroku with git push heroku main. It is recommended to schedule backups for the database.

copyright

The following copyright applies to this work:

• The script file process_recording.sh is a modified version of Yahweasel's craig powersfx.sh script, and it is licensed under the GNU Lesser General Public License v2.1 or any later version of the License.
• The image file catalog/static/images/lovekiss.gif was retrieved from the image sharing service Tenor (original image), and it is shared through the deployed WebApp under their terms of service.
• The image file catalog/static/images/scinguistics_icon.webp is an asset of Scinguistics and all rights are reserved to the owner, permission for use must be explicitly granted from the owner (see contact page).
• The remainder of the code and assets in this repository are licensed under the GNU Affero General Public Licence v3.0 or any later version of the License (see LICENSE.md).