Gutenberg is an open source research and teaching platform developed by the Oxford Research Software Engineering Group (OxRSE) at the University of Oxford as part of the UNIVERSE-HPC project.
It provides an environment for hosting training materials in a structured, pathway-based style, offering a visual interface for browsing the various sections of training content and viewing them.
A course management interface allows trainers to create a course syllabus based on materials set up within the system and then to make this available to students. Details of modules completed and results of exercises and challenges within the training material are collated and made available to course leaders to enable them to keep track of student progress.
You can deploy your own instance of the Gutenberg platform locally. Training material is stored in separate GitHub repositories that can be linked to a Gutenberg deployment. A set of open research computing training material that has been collated and updated to fit into the Gutenberg structure is configured within the system by default but you can develop and add your own material to the system.
A hosted deployment of Gutenberg is available at https://train.oxrse.uk/.
This is a Next.js project bootstrapped with create-next-app
.
To see our full documentation, please visit our documentation site.
To get a development environment running, follow the instructions below:
Setting up a local development requires the following software:
git
version 2.43.0 or later - install according to instructions for your systemnpm
version9.2.0
or later - install according to instructions for your systemnode
version v18.19.1 or later - packaged withnpm
corepack
version0.28.0
or later - install withnpm install -g corepack
yarn
version3.3.0
or later - installed viacorepack
withyarn --version
- For developing the full web application functionality rather than just previewing materials, you'll also need a
postgres
instance
Clone the repository with git clone https://github.com/OxfordRSE/gutenberg.git
.
Enter the directory with cd gutenberg
.
Install corepack
if necessary with npm install -g corepack
.
Enable corepack
with corepack enable
.
Run yarn --version
to check the version of your yarn package manager.
corepack
will prompt you to install it if you don't have it already.
With yarn
installed you can run yarn install
to install dependencies listed in package.json
.
The specific versions of packages we use are frozen in yarn.lock
,
so you'll be guaranteed to have working versions of each dependency.
Gutenberg separates its source material from its rendering engine by design. This means you need to copy some source material before you have anything to display!
The HPC materials are already listed as a source via the NEXT_PUBLIC_MATERIAL_URL
variable in the .env
file.
To download those materials, so we have something to work with, run yarn pullmat
and they will be cloned into
a local .materials
directory.
If you just want to develop materials and preview their rendering, skip this step.
If you want to change the rendering system itself, you'll need a database. The database is required for the interactive parts of the site - tracking users' behaviour etc.
The connection string for the database is listed in .env
.
It wants a postgres service listening on localhost:5432
(the default port),
that will accept connections from postgres:password
.
One way to do this fairly simply is using docker
.
docker run -d -e POSTGRES_PASSWORD=password -p 5432:5432 postgres
If you're already in a docker container, you can install postgres directly with
apt install postgresql
and then run it with service postgresql start
.
You'll also need to do a couple more steps to enable serving over localhost:5432
and connecting with postgres:password
as the username:password.
Those steps can be found on the Ubuntu support pages.
If that's all too hard, you can install docker
within a container using apt install docker
and it should all be fine, at least for local development.
The instructions for doing so are on the Docker support pages.
With the database available, we then need to create the various tables etc. that Gutenberg uses with
yarn prisma migrate dev
.
The local development server can be started with yarn dev
.
When the next
server is ready, it will print out its URL.
This will probably be http://localhost:3000
.
Visit that URL in your browser to see your local instance deployed. The development server watches your files, and refreshes when it sees changes. This means that your edits will be reflected instantly.
Now everything should be set up for local development of the core systems.
Gutenberg also has a deployable dev environment using docker-compose. If you wish to use this alternative then see getting started using docker compose.
You can develop material by editing the .material
folder.
Changes will be instantly reflected in the browser if you are running the development server.
All of the content is standard markdown, with the addition of special callouts you can use to present exercises, etc. in a consistent manner.
When you're happy with your changes, you can issue a pull request for your changes to the repository you originally cloned in Getting Started.
The renderer code is written in TypeScript, and consists of a React frontend and NextJS backend, both located within this repository.
The backend's interaction with the database is performed using prisma
.
Prisma Studio is a GUI for viewing and editing the database. It can be started with:
npx prisma studio
The prisma
command only reads from .env
and not .env.local
, so you will need to either copy the values from .env.local
to .env
, or use a command like dotenv
to populate the environment variables. For example:
npm install dotenv-cli -g
dotenv -e .env.local npx prisma studio
Gutenberg is automatically deployed to fly.io by a GitHub action whenever a new commit is pushed to the main
branch.
To see how to deploy the application, see our deployment guide.