restore readme.adoc

Author: adam-cowley

README.adoc

@@ -0,0 +1,192 @@
+= GraphAcademy Course Content
+
+This repository holds the course curriculum for link:https://graphacademy.neo4j.com[GraphAcademy^].
+
+
+== Prerequisites
+
+You will need the following software to run GraphAcademy locally:
+
+* link:https://www.docker.com/[Docker^]
+* link:https://aws.amazon.com/cli/[AWS CLI^]
+* link:https://nodejs.org/en/download[Node.js^]
+* link:https://git-scm.com/downloads[Git]
+
+Recommended:
+
+* link:https://code.visualstudio.com/Download[VS Code^]
+  * Asciidoc extension
+
+== Setup
+
+This repository uses link:https://docs.docker.com/compose/install/[`docker-compose`] to create a local server using the latest production build of the GraphAcademy website (link:https://github.com/neo4j-graphacademy/website/[repo here^]).  The docker image is stored on AWS ECR, so you will need credentials - talk to mailto:adam@neo4j.com[Adam].
+
+1. Clone this repository
+2. Install the link:https://aws.amazon.com/cli/[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 mailto:adam@neo4j.com[Adam] or mailto:martin.ohanlon@neo4j.com[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 link:https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers[Dev Containers^] extension installed and link:https://www.docker.com/[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:
+
+[source,sh]
+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
+
+[source]
+----
+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. +
+  link:https://graphacademy.neo4j.com/courses/workshop-fundamentals[View Workshop]
+* **Importing Data into Neo4j Workshop** (`workshop-importing`) - Learn how to import your data into Neo4j +
+  link:https://graphacademy.neo4j.com/courses/workshop-importing[View Workshop]
+* **Gen-AI - Hands-on Workshop** (`genai-workshop`) - GenAI Beyond Chat with RAG, Knowledge Graphs and Python +
+  link:https://graphacademy.neo4j.com/courses/genai-workshop[View Workshop^]
+* **Mastering Retrieval-Augmented Generation (RAG)** (`genai-workshop-graphrag`) - Learn how to implement GraphRAG with the neo4j-graphrag Python Package +
+  link:https://graphacademy.neo4j.com/courses/genai-workshop-graphrag[View Workshop^]
+// * **GenAI Workshop - TypeScript** (`genai-workshop-typescript`) - Build a Conference Chatbot with LangChain and Neo4j +
+//   link:https://graphacademy.neo4j.com/courses/genai-workshop-typescript[View Workshop^]
+
+
+== QA
+
+A suite of tests have been setup to ensure courses meet the right standard.
+
+To open the test suite run:
+
+[source,sh]
+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
+
+
+=== Creating a PR
+
+When you create a PR, select the correct template:
+
+* link:https://github.com/neo4j-graphacademy/courses/compare/main...other?template=course_draft.md[Course Draft Template^]
+* link:https://github.com/neo4j-graphacademy/courses/compare/main...other?template=course_release.md[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:
+
+[source]
+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:
+
+[source,sh]
+ln -s ../certifications/asciidoc/certifications/neo4j-certification asciidoc/certifications/neo4j-certification
+
+== Documentation
+
+Additional documentation is located in the link:docs/[Docs folder].