GraphAcademy Course Content

This repository holds the course curriculum for GraphAcademy.

Prerequisites

You will need the following software to run GraphAcademy locally:

• Docker

• AWS CLI

• Node.js

• Git

Recommended:

• VS Code

• Asciidoc extension

Setup

This repository uses docker-compose to create a local server using the latest production build of the GraphAcademy website (repo here). The docker image is stored on AWS ECR, so you will need credentials - talk to Adam.

1. Clone this repository

2. Install the AWS CLI

3. Run aws configure to configure the AWS CLI

4. Log in to docker using the credentials above:

   aws ecr get-login-password --region us-east-1 | docker login -u AWS --password-stdin 715633473519.dkr.ecr.us-east-1.amazonaws.com

5. Install the dependencies using NPM

   npm install

6. You will need to create a .env file in the project root with Auth0 configuration. You can get an example file from Adam.

   • NEO4J_HOST

   • NEO4J_USERNAME

   • NEO4J_PASSWORD

   • AUTH0_CLIENT_ID

   • AUTH0_CLIENT_SECRET

   • AUTH0_ISSUER_BASE_URL

7. Run npm run dev to start the server

   • The local server will be available at http://localhost:3000
     

   • A Neo4j instance will be available on http://localhost:7474
     

   • A process will listen for changes in the asciidoc/ folder and sync the content to Neo4j

File Structure

All content lives in the asciidoc/ directory. As you modify the content, a process will sync the course structure to Neo4j.

• categories/ - Category information

• courses/ - All courses are organised into the own folder structure with modules and lessons

• emails/ - The emails sent to users on enrolment, completion and a reminder email when the user has been inactive for 7 days

• languages/ - i18n phrases for courses in languages other than English.

• pages/ - "CMS" content displayed throughout the website, for example the /certifications/ page

• shared/ - Content shared across courses

• statuses/ - Meta data around course statuses

Course Structure

asciidoc
 + courses/
    + {course-slug}/                  - Course Folder
       + badge.svg                    - SVG badge used across the site
       | overview.adoc                - Course meta data and content used on the course overview page
       + modules/                     - Each course is split into modules
         + {module-slug}/
           | overview.adoc
           + lessons/                 - A module is split into lessons
             + {lesson-slug}/
               | lesson.adoc
               + questions/           - A lesson can be optional, otherwise will have questions.
                 | question-1.adoc
                 | question-2.adoc

QA

A suite of tests have been setup to ensure courses meet the right standard.

To open the test suite run:

npm run test

This will open up a UI. Select E2E testing > Chrome and then select the course.

To create a test for your course, you can copy one of the existing files in the cypress/e2e folder to cypress/e2e/{slug}.cy.js and then change line 6 to cy.getCourseDetails('{slug}')/

Contributing

To create a new course or modify an existing course, please create a new branch and make your changes. Once you have finished, create a new PR and add adam-cowley as a reviewer.

git checkout -b new-course
mkdir asciidoc/courses/new-course/
echo "= New Course\n:status: draft" > asciidoc/courses/new-course/course.adoc

git add asciidoc/courses/new-course/
git commit -m "Added new course"
git push --set-upstream origin new-course

Before creating the PR, please rebase your branch on the main branch.

git fetch origin main
git rebase main

Generating a Banner

To generate a banner image for a course, run the following command:

npm run generate:ogimages

The command scans through the asciidoc/ folder, finds all courses that don’t include a banner.png image and attemps to create them.

Deploying Changes

When a new application server is created, the latest tagged version of this repository is downloaded by the server.

You can use the npm version command to create a new tag. First, run a git pull --tags to get the latest commits and tags from the server, then run the npm version command to create a new tag. Once you are done, run git push --tags.

git pull --tags origin main
npm version patch
git push --tags origin main

• npm version patch - To be used when minor fixes are made to an existing course

• npm version minor - To be used when a new course is released

• npm version major - To be used when a major change is made to the repository - for example, multiple course changes, or addition of a new category

Documentation

Additional documentation is located in the Docs folder.