Trellis Tools · Walkthroughs

Walkthroughs › Getting started

Getting started

An account, a lab, and the dashboard behind it

Make an account with your lab's registration code, find your way round your own dashboard, then — if you run a lab or the suite — the controls behind it: labs and their codes, who may do what, how the suite stands, and the backups. Start here before the other walkthroughs.

Versions Recorded on 13 November 2026 with Trellis 2.49.3. Yours are under About in the tool's own header. If yours are newer, a screen here may have moved on; if they are older, something on this page may not be there yet.

Before you start

  1. Have Trellis running: on a lab server, or on your own computer for practice (install).
  2. Load the demo. It adds two teaching labs, their accounts and example work in every module, and leaves your lab's own records alone. On the server, in the Trellis folder:
    demo/demo.sh load
  3. Sign in as demo, password trellis-demo (or the one set with DEMO_PASSWORD).

To start the walkthrough again from a clean slate, run demo/demo.sh reset. The recordings are silent; each step is named in the green caption at the bottom.

1

Make an account

One account for every tool in the suite, made by you, not by an administrator.

  1. Open the suite's address. You land on the sign-in page.One account works in all of the tools: MoClo, the Sequence Editor, the notebook, seeds, stocks, booking and the genome browser.
  2. Click Create an account.
  3. Choose your lab from the list, and paste the registration code your lab lead or lab admin gave you.Every lab has its own code, and it works for every tool. It looks like garnet-quartz-delta-38 — three words and a number, easy to read out.
  4. Pick a username — 3 to 32 letters, digits, dots, dashes or underscores — and a password of at least 8 characters. Then Create account.
  5. You are signed in, on the suite's front page.Every tool is there, each saying what it is for and whether it is running. That one page is the way into all of them.

No code? Ask your lab lead or lab admin: it is on their dashboard, under Labs. An administrator can also make the account for you instead, under Accounts.

A code can be retired. An administrator can issue a new one at any time; the old one stops working at once, and accounts already made are not affected. A closed lab takes nobody new.

Already in one lab and joining another? You keep one account and gain a role in the second lab — see chapter 4.

Recording · Make an account
RecordingAn account made with a lab's registration code, landing on the suite's front page.
Sign in
One account, all of the tools.
Create an account
Your lab, and its registration code.
Filled in
Three to 32 characters, and 8 for the password.
Signed in
Every tool, on one page.
2

Your dashboard

What is yours, gathered from across the tools in one place.

  1. Click Dashboard, top right in any tool.It opens on My account: your username, the lab you are in and your role there.
  2. My parts — what you have contributed to the shared MoClo library, with its type, source and when you uploaded it.
  3. Saved constructs — the assemblies and reactions you kept from MoClo or the CRISPR designer. A saved reaction opens the calculator already filled in.
  4. MoClo sharing — whether your chair group's library is open to another chair group.
  5. My bookings — every room and instrument you have booked, soonest first, including the ones someone else tagged you into. Open the calendar ↗ goes to Booking.

A member sees only these tabs. There is no Administration section: a member can use everything, and sees only their own things here.

Your role is per lab. Member uses the tools; lab lead can act for their lab's members and plasmids and see the lab's code; lab admin can do that and add or remove people.

Recording · Your dashboard
RecordingA member's dashboard: account, parts, saved constructs and bookings.
My account
Role Member — and no Administration section.
My bookings
Including the ones you were tagged into.
Saved constructs
What you kept from MoClo.
My parts
What you contributed to the library.
3

Running a lab

A lab lead or lab admin gets an Administration section, for their own lab.

  1. Sign in as someone with a role in the lab.The header says which: demo · Lab admin. The YOU tabs are the same as a member's; below them an ADMINISTRATION section appears.
  2. Open Labs.Your lab: its name, how many members, its registration code and its chair group. Copy puts the code on the clipboard to send to a new member. Only an administrator of the suite can change it.
  3. Below it, members: who is in the lab, their role here and when they joined.As lab admin you add people and take them out, and as its lead you can open and change your members' plasmids and read their notebooks. Taking someone out of the lab keeps their account and their own work.
  4. Add someone to Demo Lab: a new account, with a username and starting password, or an existing one.Someone already in another lab keeps that lab too. Anyone with the code can also register themselves.
  5. Open Rooms & equipment for what your lab shares in Booking, and its rules.That is the same panel the Booking walkthrough covers.

Lead or admin? A lab lead can act for their lab's members and plasmids and see the lab's code, but cannot change codes or roles. A lab admin can do all that, and add people to the lab and take them out.

Only an administrator deletes accounts or changes roles.

Recording · Running a lab
RecordingA lab admin's dashboard: the lab's code, its members, and its rooms.
Lab admin
Role Lab admin, with an Administration section.
Your lab
The code to give new members, and who is in.
Rooms & equipment
What the lab shares in Booking.
4

Administering the suite

An administrator sees every lab and every account, and how the suite itself stands.

  1. Sign in as an administrator.The header reads admin · Administrator, and the Administration section grows: Labs, Accounts, Hosting, MoClo library, eLab owners' labs, Rooms & equipment and Backups.
  2. Labs — every lab, its members, its registration code and its chair group.Copy the code, New code to retire the old one at once, Close a lab so it takes nobody new, and Add lab at the foot. Existing accounts are never affected by a new code.
  3. Below that, Chair groups — labs that work together.The labs of a chair group see each other's stocks in Lab Stocks, and each other's library in MoClo, changing only their own. A lab is in at most one.
  4. Accounts — one row per person, with the labs they are in and their role in each.Change a role in place, add someone to another lab with + lab, tick Administrator, or Set password, Report, Archive and Remove. Add an account makes one for someone who cannot register themselves.
  5. Hosting — what matters once the suite has an address of its own, checked as you look.Whether a public address is set, which certificate is in use and until when, whether browsers are told to use https only, that sign-ins travel over https, that registration needs a code, that password guessing is limited, that administrators have passwords of their own — and whether a backup has ever run.
  6. HPC Terminal (Trellis 2.55 and later) — the networks the HPC Terminal may reach.List the lab's HPC networks, as narrowly as you can — a subnet as 192.168.2.0/24, one machine as 192.168.2.19 — each with a note, and Save: it counts at once. Until a list is saved, TERMINAL_ALLOWED_NETWORKS in the server's .env counts, else private networks only. TERMINAL_NETWORK_LIMIT there, if set, is a bound this list cannot go beyond, so a stolen administrator sign-in cannot point the terminal anywhere else.

Archive, don't delete. Archiving someone keeps their work and opens it to their lab's leads; removing an account is for one that should never have existed.

Chair groups are how two labs share. An administrator chooses which labs are in which; everything else follows from that.

Recording · Administering the suite
RecordingEvery lab and its code, the accounts and their roles, and how the suite stands.
Labs and registration codes
Every lab's code, and the chair groups.
Accounts
Who is in which lab, and what they may do.
Hosting
How the suite stands, checked now.
5

Backups

The one administration job worth doing on day one.

  1. Open the Backups tab.On a new install it says the destination is not marked yet, the last backup is none yet, and Hosting warns that no backup has run.
  2. Choose where they are kept: a network drive (a Windows file server or NAS), or a folder on the server.A folder is only useful if the server has a drive mounted there itself, under /mnt or /backup; otherwise the backups stay on the same machine as the suite, which is no protection at all.
  3. Click Use this folder.It creates the folder if needed and marks it as the backup drive: Destination is ready. Backups will be written there, and Ready turns to yes.
  4. Click Back up now rather than waiting for tonight.The log shows each database as it goes: MoClo main and parts, the Sequence Editor, labs and codes, the notebook, seeds, stocks, booking, the genome browser — then the stack's configuration. The archive appears with its size and a verified checksum.
  5. Set Schedule and retention: the hour and minute it runs each day, and how many daily, weekly and monthly archives to keep. Save schedule, with Run automatically ticked.Under Archives, each one can be Downloaded, Verify'd without changing anything, or Restored.

Genome files are not in the archive. They are far too large; the log says so. Back those up with the rest of the server's bulk data — see docs/BACKUP.md.

Moving to a new machine? Download an archive here, install the suite there, and use Upload an archive to put it back.

Verify is free. It checks an archive without touching anything. Worth doing once after you set the destination, and now and then after.

Recording · Backups
RecordingA destination marked, a backup run, and the schedule set.
Not set up yet
What a new install looks like.
Destination ready
Ready: yes — backups will be written.
Backed up
Each database, with its size and tables.
Schedule and archives
When it runs, what is kept, and Restore.
6

Where your data lives, and who can see it

Nothing here asks you to trust a promise: the suite checks itself, and you can read every line of it.

  1. It is your server. Trellis runs on hardware your lab or your university controls, in Docker containers. Sequences, notebooks, seeds, stocks and bookings are written to disk there and go nowhere else by themselves. There is no account with us, no shared cloud, and no telemetry.
  2. Each tool runs in its own container, and only one has a door. The suite starts thirteen containers — one per tool, plus the sign-in service, the backup pair, a file converter, the genome worker and the proxy — and exactly one of them publishes a port to the outside: the proxy. Every tool listens on an address that exists only on the suite's private Docker network, so nothing on your institute's network can reach the notebook or the stocks database directly — only the proxy, over https, after a sign-in.
  3. The HPC Terminal reaches only the lab's machines, on the networks an administrator allows, each checked against its host key. It keeps no passwords, codes or private keys, and administrators and lab leads see who is connected, never what is on anyone's screen (more).
  4. Two things leave, and only when you ask. BLAST at NCBI in the Genome Browser sends the sequence you selected to NCBI — the button says so before you press it. If an administrator connects eLabJournal, the stocks and seed lots you choose are copied there. Nothing else goes out.
  5. Who can see what follows your lab, not the tool. A plasmid, stock or seed lot belongs to the lab of whoever made it, and is read-only to the other labs of its chair group; labs outside it see nothing. Notebooks are tighter: a member reads only their own, a lab lead their lab's except a lab admin's, and only the owner ever writes in theirs. Sharing a page is a deliberate act.
  6. Check it yourself on the Hosting tab.It tests the running suite as you look at it and says what is true now: that sign-ins travel over https and last 14 days, that registering needs a lab's code, that password guessing is limited, that administrators have passwords of their own, and when the last backup ran. Warnings are things for you to fix, not decoration.
  7. On day one, do these three. Replace the lab's own certificate with a real one if the suite has a public address; set the backups up (chapter 5) so Last backup turns green; and once everyone has registered, close registration so no code can be used again.

You can read the code. Trellis Tools is open source under the GPL-3: every rule described here is in the repository, and so is the history of how it got there. Nothing about who-sees-what is hidden in a service you cannot inspect.

The certificate warning is normal at first. A new install makes its own certificate authority, so browsers warn until each computer trusts it once. That is a trust problem, not an encryption one — the connection is already encrypted. For an address outside the lab, use a public authority such as Let's Encrypt.

If something looks wrong, every record keeps its own history: who changed what, and when. Stocks, seeds, notebook pages and sequences all have it.

Recording · How the suite stands
RecordingThe Hosting tab checking the running suite, line by line.
How the suite stands
The suite checking itself, as you look.
Settings
And the settings behind each warning.
What actually protects it

Passwords are never stored. Each is hashed with bcrypt, which is deliberately slow to compute, so a stolen database cannot be turned back into passwords at any useful speed. Changing a password rewrites the hash; nothing anywhere keeps the original.

Guessing is rate-limited in two places: after 10 wrong passwords for one account, that address waits 15 minutes, and the proxy in front of the suite independently slows anyone trying too often. Both are on by default.

Sessions are cookies marked https-only, so a browser will not send them over an unencrypted connection, and they expire after 14 days.

Getting in at all needs a lab's registration code, which an administrator can retire at any moment — the old code stops working at once and existing accounts are untouched. Registration can be closed entirely once everyone has an account.

Backups are checked, not just written: each archive is verified by checksum as it is made, Verify re-checks one later without changing anything, and retention prunes old archives on the schedule you set. A backup kept on the same machine as the suite protects you from mistakes, not from losing the machine — point it at a network drive.

The containers themselves. Each tool is a separate container with its own filesystem, running as an ordinary user and not as root — appuser, portal, genome and so on. A flaw in one tool therefore starts with no privileges and no view of another tool’s files; it would have to get out of its own box first.

$ docker ps --format '{{.Names}}	{{.Ports}}'
lab-proxy            80/tcp, 0.0.0.0:443->443/tcp   <- the only door
lab-portal           5003/tcp                       <- internal only
plasmid-editor       5001/tcp
lab-notebook         5004/tcp
lab-stocks           5006/tcp
lab-genome           5008/tcp
...

A port with no address in front of it is not published: it exists only inside the Docker network. That listing is worth running on your own server — it is the whole attack surface, on one screen.

Pinned, and reproducible. Every tool is pinned to an exact version in docker-compose.yml, never to latest, so the suite you are running is the suite that was tested together, and scripts/check.sh prints the versions back to you. An update replaces a container; a rollback pins the old tag again. Code and data are kept apart — the databases live in named volumes — so replacing a tool never touches what it stored.

Where containers do not help. They share the host’s kernel, so this is defence in depth, not a sandbox: keep the host patched, and treat anyone with root on it, or access to the Docker socket, as having everything. The suite cannot protect you from the machine it runs on.

None of this is unusual, and none of it is clever. It is the ordinary set, turned on by default, and shown to you on one page so you can see that it still is.

Where next

  • With an account, start the work itself: the MoClo Library Tool walkthrough designs and assembles the construct the rest of the thread follows.
  • Or go straight to whichever tool you need — every walkthrough is listed on the Walkthroughs page.