Skip to contents

Controlled pilot deployment

Source: vignettes/pilot-deployment.Rmd
pilot-deployment.Rmd

Scope

This guide describes a controlled pilot deployment rehearsal for learnrTrackR. It uses the simulated course pilot, PostgreSQL, environment variables, teacher exports, Moodle-ready CSV output, dashboard data, and an HTML teacher report.

The workflow is intended for development, local rehearsal, and small controlled pilots. It is not an institutional authentication layer and it is not a production LMS.

For the SQLite version of the same pilot, the course-pilot example includes run-student.R, run-teacher.R, student.env.example, teacher.env.example, and pilot-checklist.md.

Example directories 

library(learnrTrackR)

postgres_dir <- system.file("examples/postgres-docker", package = "learnrTrackR")
course_pilot_dir <- system.file("examples/course-pilot", package = "learnrTrackR")

postgres_dir
#> [1] "/tmp/Rtmpktuqs0/temp_libpath19a65a519f54/learnrTrackR/examples/postgres-docker"
course_pilot_dir
#> [1] "/tmp/Rtmpktuqs0/temp_libpath19a65a519f54/learnrTrackR/examples/course-pilot"

Environment variables

The PostgreSQL Docker example includes an env.example file. Copy it to .env before launching the service:

cp env.example .env

The important pilot variables are:

LEARNRTRACKR_POSTGRES_DB=learnrtrackr
LEARNRTRACKR_POSTGRES_USER=learnrtrackr
LEARNRTRACKR_POSTGRES_PASSWORD=replace-with-a-long-random-password
LEARNRTRACKR_POSTGRES_HOST=127.0.0.1
LEARNRTRACKR_POSTGRES_PORT=5432
LEARNRTRACKR_POSTGRES_SCHEMA=learnrtrackr_pilot
LEARNRTRACKR_PILOT_TUTORIAL_ID=stat_descriptive_pilot
LEARNRTRACKR_PILOT_GROUP_ID=A
LEARNRTRACKR_PILOT_OUTPUT_DIR=pilot-outputs
LEARNRTRACKR_PILOT_RESET=true
LEARNRTRACKR_DASHBOARD_HOST=127.0.0.1
LEARNRTRACKR_DASHBOARD_TOKEN=replace-with-a-long-random-dashboard-token

Do not commit .env files, database dumps, or exported student results.

Start PostgreSQL

From inst/examples/postgres-docker/:

docker compose --env-file .env up -d

The Compose file starts one local PostgreSQL service. The pilot smoke test uses the schema named by LEARNRTRACKR_POSTGRES_SCHEMA. When LEARNRTRACKR_PILOT_RESET=true, that schema is dropped and recreated before the simulated pilot is inserted.

Run the pilot smoke test 

Rscript course-pilot-smoke-test.R

The smoke test:

  1. connects to PostgreSQL;
  2. prepares the pilot schema;
  3. loads the course, tutorial, student, and question CSV configuration;
  4. records the simulated cohort attempts;
  5. prepares dashboard data with dashboard_data(con, ...);
  6. writes attempts, scores, gradebook, Moodle-ready grades, Canvas Gradebook grades, and a rich export bundle;
  7. renders an HTML teacher report when rmarkdown is installed.

Inspect the teacher outputs

By default, outputs are written to:

inst/examples/postgres-docker/pilot-outputs/

Expected files include:

course-pilot-attempts.csv
course-pilot-scores.csv
course-pilot-gradebook.csv
course-pilot-moodle.csv
course-pilot-canvas.csv
course-pilot-teacher-report.html
course-pilot-bundle/

The Moodle CSV is filtered by LEARNRTRACKR_PILOT_GROUP_ID. For example, LEARNRTRACKR_PILOT_GROUP_ID=A exports only the configured group A learners. The Canvas CSV uses the same group filter.

Dashboard

The pilot verifies dashboard tables with:

dashboard_data(
  con,
  tutorial_id = "stat_descriptive_pilot",
  group_id = "A",
  rule = "last"
)

The interactive dashboard can then be launched from the same PostgreSQL environment:

Rscript run-dashboard.R

The script calls run_dashboard_postgres() with the configured PostgreSQL schema, tutorial id, group filter, dashboard host, and dashboard token:

run_dashboard_postgres(
  postgres_schema = Sys.getenv("LEARNRTRACKR_POSTGRES_SCHEMA"),
  tutorial_id = Sys.getenv("LEARNRTRACKR_PILOT_TUTORIAL_ID"),
  group_id = Sys.getenv("LEARNRTRACKR_PILOT_GROUP_ID"),
  host = Sys.getenv("LEARNRTRACKR_DASHBOARD_HOST", unset = "127.0.0.1"),
  access_token = Sys.getenv("LEARNRTRACKR_DASHBOARD_TOKEN")
)

Teacher launch checklist

Before a real controlled pilot:

  1. read pilot-checklist.md and pilot-protocol.md in the course-pilot example;
  2. choose the student identifier used for Moodle matching;
  3. prepare students.csv with only necessary student metadata;
  4. set a PostgreSQL password that is not committed to Git;
  5. use a dedicated PostgreSQL database or schema;
  6. run course-pilot-smoke-test.R;
  7. inspect course-pilot-moodle.csv before importing;
  8. inspect the teacher report before using results for teaching decisions;
  9. launch run-dashboard.R only from an explicitly managed local or protected environment;
  10. document who can access exports and how long files are retained.

Stop PostgreSQL 

docker compose --env-file .env down

To delete the local data volume:

docker compose --env-file .env down -v

References