Publishing Content¶

For members of elab-data-managers

This guide is for the people who put data and material where others in the eLab can use it — a data custodian making a curated dataset available to a research project, say, or a course lead handing out notebooks to a class. If you need to do this and don't hold the role, ask your platform operator to add you; it takes effect the next time you sign in. The role is deliberately separate from administering the eLab: holding one does not give you the other.

Your desktop has two folders nobody else's has:

Folder	What it is
`/publish`	The writable side of the read-only `/shared` every user sees. What you put here, everyone here reads.
`/publish-sites/<site>`	The same area at each other site of a multi-site eLab, so you can see all of them at once

In a teaching eLab you also have /analyst-homes — see Working in other people's homes.

Getting data or material to users, start to finish¶

The whole journey, in order. Each step links to the detail below it or to the guide for the role that performs it.

Decide how people should get it. Something they only need to read — a curated dataset, reference data, documentation, a handout — goes in /shared. Something each of them must edit — a template analysis, a notebook to complete, an assessment file — is delivered, so everyone gets their own copy. The difference matters for storage: 200 MB delivered to 120 users is 24 GB of home space; the same file in /shared is 200 MB. Data people only analyse almost always belongs in /shared.
Bring the files onto your desktop. The airlock is the route that is reviewed and recorded, and in a secure-data eLab it is the only one. Raise an import request (this needs the airlock-analysts role as well — see Importing & Exporting Data); once a reviewer approves it, the files appear read-only in your /imports/<request>/. Nobody but you can see them there, which is why publishing is a separate step.
Publish or deliver them. Copy from /imports/<request>/ into /publish/... to share read-only content, or into /publish/_deliver/<name>/ to deliver editable copies.
On a multi-site eLab, send it to every site — each site has its own copy of /shared. See Keeping sites in step.
Check it arrived. Shared content is visible at once under /shared. Your own desktop receives deliveries like anyone else's, so start or restart it and run elab-materials --list. Then tell the people you published it for — deliveries reach a desktop when it starts, and anyone already working can fetch them straight away with Get materials.

Put the files anywhere under /publish. Every desktop at this site sees them straight away, read-only, at the same path beneath /shared — there is nothing to trigger. Other sites of a multi-site eLab need a push.

Use this for anything people only need to read or analyse. It is one copy on disk however many people use it, and nobody can change it by accident.

Delivering editable copies¶

Files people must edit cannot live in read-only /shared. Put them in a delivery folder instead, and each user's own desktop copies them into their own home:

/publish/_deliver/week-03-notebooks/delivery.yml     settings for this delivery (optional)
/publish/_deliver/week-03-notebooks/...              the files to deliver

Every desktop picks it up at its next start, including one created next week, and anyone can fetch it mid-session with the Get materials icon on their desktop. Add an optional delivery.yml beside the files to say what should happen:

Key	Values	Meaning
`mode`	`copy-if-absent` (default), `update`, `remove`	land once, refresh a revision, or withdraw it
`target`	a path under the home	where it lands (default `Delivered/<name>`)
`on_modified`	`keep` (default), `backup`	for `update`: leave a user's changed file, or save theirs aside
`message`	text	shown to the user when it runs

For example:

mode: update
target: Handouts/week-03
on_modified: backup
message: Week 3 notebooks revised. If you had edited one, your version is saved beside the new one.

Things to know when writing it:

Each delivery has its own delivery.yml, inside its folder. A delivery.yml placed directly in /publish/_deliver/ belongs to no delivery and is ignored. The folder must be named exactly _deliver; anything else is published as ordinary read-only content in /shared.
Write each setting as a plain key: value line. It is not read as full YAML, so lists and nested settings aren't understood, and if a key appears twice the first one wins. Quotes around a value are optional.
target must be a relative path inside the user's home, such as Handouts/week-03. A path starting with / or containing .. is refused, and that delivery is skipped with a message.
The folder name is the delivery's identity. It is the default destination (Delivered/<name>), the name users see when they list what has been published, and how a later update or remove finds the copies it delivered. Keep the folder when you revise it — renaming it makes a new delivery, and leaves the old copies where they are.
delivery.yml itself is not copied into anyone's home.

What recipients see is described for them in Using Your Desktop.

Revising or withdrawing delivered copies¶

Change the delivery's mode in its delivery.yml. Editing the files alone is not enough: copy-if-absent delivers once per user, so a revision never reaches anyone who already has a copy until the mode is update.

update refreshes a revised version. Files a user has not touched are replaced; files they have changed are left alone — or, with on_modified: backup, their version is saved beside the new one as …yours-<date>.
remove withdraws it. Untouched copies are taken back; anything a user has edited stays.

A file someone has changed is never overwritten or deleted by either — update and remove only touch files still identical to what was delivered, and anything edited is left alone and reported. Withdrawing takes back the untouched copies and leaves people's work.

Keeping sites in step¶

With more than one site, each has its own copy of /shared, and an upload lands only at the site you were working at. Your desktop carries elab-publish for this:

elab-publish status              # what differs between this site and the others
elab-publish push --to all      # send this site's content everywhere
elab-publish pull --from <site>  # take another site's content as the truth here

Everything is a dry run until you add --yes, so the first run of any command shows exactly which files it would send. A push is also refused outright when the far side holds anything newer than this one — someone may have published there — so "who has the current copy?" is never guessed.

Deliveries are per site too. A delivery folder is part of /shared, so users placed on another site only receive it, or a revision of it, once you have pushed it there. Push it rather than recreating it by hand: a user who moves between sites keeps their record of what they have received, and a delivery is recognised by its folder name, so a different name at the other site would be delivered to them again.

Working in other people's homes — teaching eLabs only¶

In a teaching eLab, your desktop also mounts every user's home, writable, at /analyst-homes/<site>/<username>/ — for marking, fixing a notebook that will not run, or putting a file where someone will find it. Every site of the eLab appears there, named, so a multi-site cohort is never half-visible.

Treat it as what it is: you can change and delete anyone's work, and nothing warns you. The user guide tells students plainly that their course team can see and change their home, because finding that out afterwards would be worse than the access itself. In a secure-data eLab the mount does not exist at all and cannot be switched on — researchers' homes are theirs alone.