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:
gitversion 2.43.0 or later - install according to instructions for your systemnpmversion9.2.0or later - install according to instructions for your systemnodeversion v18.19.1 or later - packaged withnpmcorepackversion0.28.0or later - install withnpm install -g corepackyarnversion3.3.0or later - installed viacorepackwithyarn --version- For developing the full web application functionality rather than just previewing materials, you'll also need a
postgresinstance
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 postgresIf 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 studioThe 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 studioGutenberg 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.