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 or Martin.

   • NEO4J_HOST

   • NEO4J_USERNAME

   • NEO4J_PASSWORD

   • AUTH0_CLIENT_ID

   • AUTH0_CLIENT_SECRET

   • AUTH0_ISSUER_BASE_URL

   • CDN_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

Devcontainer

If you are using VS Code, you can use the devcontainer to run the application in a container.

You will need the Dev Containers extension installed and Docker running.

When the devcontainer is started, it will:

• Install all dependencies

• Start the GraphAcademy application and Neo4j database.

You can run the content update and sync by running the following command in a terminal:

npm run dev:watch

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

Workshops

Workshops are instructor-led courses that are designed to be delivered in a classroom setting. They should not be used for self-study. The following workshops are available:

• Introduction to Graph Databases Workshop (workshop-fundamentals) - Learn about Graph theory, Neo4j fundamentals, and how to read and write data using Cypher.
  View Workshop

• Importing Data into Neo4j Workshop (workshop-importing) - Learn how to import your data into Neo4j
  View Workshop

• Gen-AI - Hands-on Workshop (genai-workshop) - GenAI Beyond Chat with RAG, Knowledge Graphs and Python
  View Workshop

• Mastering Retrieval-Augmented Generation (RAG) (genai-workshop-graphrag) - Learn how to implement GraphRAG with the neo4j-graphrag Python Package
  View Workshop

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}')/

You can run QA tests for all courses by running:

npm run test:qa

You can run QA tests for specific courses by setting the COURSES environment variable:

COURSES=fundamentals,aura npm run test:qa

Skipping Tests

You can skip certain time-consuming tests by setting environment variables:

• SKIP_LINK_CHECKS=true - Skip validation of external links (GitHub repositories, lesson links)

• SKIP_CYPHER_CHECKS=true - Skip Cypher query validation (file existence checks still run)

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

Creating a PR

When you create a PR, select the correct template:

• Course Draft Template

• Course Release Template

The checklist must be completed before the PR can be merged.

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 attempts 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

Linking Certifications

To link certifications from the certifications repository, create a symlink:

ln -s ../certifications/asciidoc/certifications/neo4j-certification asciidoc/certifications/neo4j-certification

Documentation

Additional documentation is located in the Docs folder.