Web Interface
The web interface, akin to the API, is rendered on GitGub pages according to the organization of the files. Let's look at the structure of the repository and review what everything is: The site is rendered via jekyll, which magically can render our markdown files into json, html, and whatever else we can dream up.
Jekyll sites store their configuration in this _config.yml file. Specifically, you should open the file and edit details like your Twitter handle, and the storage name.
├── _config.yml
The entire point of the registry is to serve container collections! To explain how this works, let's take a look at one. This is the collection "vanessa/greeting" stored at the registry namespace https://singularityhub.github.io/container-storage":
└── vanessa
└── greeting
├── manifests
│ └── latest
│ ├── README.md
│ └── Singularity
├── README.md
└── tags
└── README.md
You'll notice it's fairly simple - each collection has:
- a README.md in its top level folder,
vanessa/greeting/README.md. This file is found, and uses the collection.html template to render a collection table. You are free to write free text in this file and it will be rendered on the page under the collection details. - tags: is a folder that is there to render the tags endpoint. It isn't collection specific, but needs to be there to render the API endpoint.
- manifests: is a folder with subfolders corresponding to container tags, with each subfolder containing a README.md detailing layers, and locations in storage. The README.md in each tag folder renders to the image manifest. You'll also notice a Singularity (build recipe) in each manifest/ folder - this is the file that drives the build.
How are the files generated?
That's it! I'll explain how this content is automatically generated in another post - it's done via pull request and merge from another branch.
Am I limited to one repository?
If you are astute, you'll notice that the registry namespace corresponds to the Github Pages address. This technically means that you have flexibility to serve your containers from one repository (such as the example here) or from an organization repository (for example, a namespace like https://<organization>.github.io or if you have many users and permissions, you can use several repositories under the same organization that all are still under the https://<organization>.github.io namespace. There is a way for GitHub pages to parse all the repositories for an organization, so it would be very easy to create a "master" page that includes links to all the GitHub repositories (each a static storage namespace) for a registry. Please reach out if you would like help to do this (I haven't done an example yet!)
The following include files and templates that you might want to edit if you are a developer, or are interested in extending the storage.
The README.md at the root of the repository must have the layout at the top as home, otherwise it won't render your home page! However, you are free to write whatever content that you please (it won't change the site rendering). It's recommended to add links to continuous integration, etc.
├── README.md
Layouts are html files that determine how a page renders. For example, all templates under the "manifests" folder render into content type (json) manifests to be served by the API. The collection.html layout renders into a table of containers for a particular collection, and the home.html layout is the page you see at the root of the repository. The default.html is the underlying page that the other front end interfaces bootstrap. You are free to change these up to tweak the style of your static registry! I'm not a web designer, but I do my best.
├── _layouts
│ ├── collection.html
│ ├── default.html
│ ├── home.html
│ ├── manifests
│ │ └── singularity.html
│ └── tags.html
The following folders and files you don't need to touch, change, or poke. These are relevant to how the site looks, meaning templates and styling.
In here you will find css stylesheets, javascript, and images. You would only need to dig in here if you are a developer and want to add or remove dependencies for how the site looks.
├── assets
Have a question? Ask away!