Bonham Lab Wiki

Lab services onboarding

Properties2
tagscomputing, protocol, admin
typeprotocol

9 min read

This document covers onboarding a new user to the Bonham Lab Self-hosted lab services. For general lab onboarding instructions, see New Member Onboarding.

Complete the steps in order — Vaultwarden first, since it stores credentials and 2FA codes for everything else.

Before You Begin (Admin Steps)

When you join the lab, Kevin will do the following:

  1. Create a Vaultwarden account — go to https://pw.bonhamlab.bio, log into the admin panel at /admin, and invite the user’s email address. They will receive an invitation link to register.
  2. Create a Forgejo account — go to Site Administration → Identity & Access → User Accounts → Create User. Set a strong temporary password. Note: the user will be required to set up 2FA before they can use their account (enforced instance-wide).
  3. Create a Paperless account — go to https://documents.bonhamlab.bio/admin/auth/user/add/. Set a username, temporary password, and assign appropriate permissions (staff status if they need admin access).
  4. Share temporary credentials securely — use Vaultwarden’s Send feature (https://pw.bonhamlab.bio/#/send) to share a time-limited encrypted note containing the Forgejo and Paperless temporary passwords. Do not send passwords via email or chat.

Step 1 — Vaultwarden (Password Manager)

Vaultwarden is your password manager and stores credentials and 2FA codes for everything else. Set this up first.

Register your account

  1. Open the invitation email and click the registration link
  2. Go to https://pw.bonhamlab.bio if the link has expired — click Create Account and use the email address the admin invited
  3. Set a strong master password — this is the one password you must memorize and never store digitally. Use a passphrase of 4+ random words if needed
  4. Log in and verify you can access the vault

Set up 2FA for Vaultwarden itself

  1. In the Vaultwarden web vault, go to Account Settings → Security → Two-step Login
  2. Choose Authenticator App
  3. Open your authenticator app (Aegis, authy, google authenticator, or any TOTP-compatible app)
  4. Scan the QR code and enter the verification code
  5. Save your recovery code somewhere physically safe (printed paper, not digital)

Install the Bitwarden-compatible client

Vaultwarden is compatible with all official Bitwarden clients:

  • Browser extension: install the Bitwarden extension for your browser, then change the server URL in Settings to https://pw.bonhamlab.bio
  • Mobile: install the Bitwarden app (iOS or Android), go to Settings → Server URL → set to https://pw.bonhamlab.bio
  • Desktop: same server URL change as above

Step 2 — Forgejo (Git Hosting)

Forgejo is the lab’s self-hosted git forge at https://code.bonhamlab.bio. It hosts code, manages issues, and runs CI workflows.

First login and password change

  1. Go to https://code.bonhamlab.bio
  2. Log in with the temporary username and password provided by the admin via Vaultwarden Send
  3. You will be prompted to change your password immediately — set a strong unique password
  4. Save this password in Vaultwarden in your Bonham Lab folder before proceeding

Set up 2FA (required — your account is locked until this is done)

Forgejo enforces 2FA for all users. Until you complete this step your account is in limited mode and cannot access repositories or the API.

  1. Go to Settings → Security → Two-Factor Authentication
  2. Click Enroll
  3. Scan the QR code with your authenticator app — Vaultwarden’s mobile app or browser extension supports TOTP and is the recommended place to store this, keeping everything in one place
    • In the Bitwarden/Vaultwarden app: open the Forgejo login entry → Edit → scroll to Authenticator Key (TOTP) → scan or paste the secret key shown below the QR code
  4. Enter the 6-digit code to verify and complete enrollment
  5. Save your recovery codes — Forgejo shows these once. Store them as a secure note in Vaultwarden attached to the Forgejo login entry

Set up SSH key for git operations

See also Authenticating through secure shell (SSH) protocol

To configure your local machine:

  1. Generate an SSH key pair if you don’t have one:

    ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/forgejo-key

  2. Add the public key to Forgejo: Settings → SSH / GPG Keys → Add Key → paste the contents of ~/.ssh/forgejo-key.pub

  3. Add to your ~/.ssh/config:

    Host code.bonhamlab.bio
    User git
    Port 443
    IdentityFile ~/.ssh/forgejo-key

  4. Test the connection:

    ssh -T git@code.bonhamlab.bio

    You should see: Hi username! You've successfully authenticated...

  5. Clone repos using the SSH URL shown in Forgejo, e.g.:

    git clone git@code.bonhamlab.bio:OrgName/repo-name.git

Sign in with GitHub or GitLab (optional)

If you prefer to use your existing GitHub or GitLab identity instead of a local password, go to Settings → Security → Linked Accounts and connect your GitHub or GitLab account. You can then log in with either method.

Step 3 — Paperless (Document Management)

Paperless-ngx is the lab’s document management system at https://documents.bonhamlab.bio.

First login and password change

  1. Go to https://documents.bonhamlab.bio
  2. Click Login with username and password (ignore the Authelia button if it appears — it is no longer active)
  3. Log in with the temporary credentials provided by the admin via Vaultwarden Send
  4. Save these credentials in Vaultwarden immediately
  5. Change your password: click your username top-right → My Profile → Change Password
  6. Update the saved entry in Vaultwarden with the new password

Set up 2FA

Paperless supports TOTP 2FA but does not enforce it at the application level — it is required as part of this onboarding procedure.

  1. Go to My Profile → Authentication (or similar — the exact location varies by Paperless version)
  2. Set up an authenticator app the same way as Forgejo — store the TOTP secret in Vaultwarden alongside the Paperless login entry
  3. Save recovery codes in Vaultwarden as a secure note

Using Paperless

  • Upload documents: drag and drop into the web UI, or drop files into the consume folder if you have direct access to the server
  • Mobile: the official Paperless mobile app (iOS/Android) connects to https://documents.bonhamlab.bio using your username and password (plus 2FA token on login)

Step 4 - HedgeDoc (Collaborative Notes) — pad.bonhamlab.bio

HedgeDoc is the lab’s collaborative markdown editor — like a self-hosted HackMD. It is for quick, shared, ephemeral notes: meeting scratchpads, drafts, paste-and-share snippets. It is deliberately open and low-ceremony.

You usually do NOT need an account

Anyone — including people with no account — can create and edit notes just by visiting https://pad.bonhamlab.bio and starting a new note. New notes default to Freely editable: anyone with the link can read and write. Share the link, collaborate in real time, done. For the large majority of uses, that is all you need, and there is nothing to set up.

Notes are treated as disposable. There is no guarantee any note persists. Unowned notes (see below) may be deleted without warning if the instance needs cleaning up or is being abused. Do not use HedgeDoc as durable storage. If a note matters, move its content somewhere permanent — a repo on Forgejo, a document in Paperless, or the wiki.

When you DO want an account: to own a note

The one reason to log in is ownership. A note created while logged in is owned by your account, which lets you:

  • Protect it from cleanup — owned notes are not subject to the “unowned notes may be removed” policy.
  • Restrict its permission — only the owner can change a note’s permission away from the default. You can lock down who can read/write (see the table below).

If you want that, ask an admin to create you an account. There is no self-registration — accounts are provisioned by an admin (same pattern as the other lab services). Once you have credentials, log in at https://pad.bonhamlab.bio, and store them in your Bonham Lab folder in Vaultwarden like any other service credential.

Permission tiers

Every note has a permission, changeable only by its owner (via the button at the top-right of the note). The ones you’ll use:

PermissionGuest readGuest writeSigned-in writeOwner
Freely (default)✔✔✔✔
Editable✔✖✔✔
Limited✖✖✔✔
Locked✔✖✖✔

So: leave a note Freely for open collaboration; drop it to Editable to let people read but only signed-in users edit; Limited to hide it from guests entirely; Locked for a read-only public note only you can edit.

HedgeDoc’s access model is link-as-secret, not real access control. A guest-readable note is protected only by the randomness of its URL — there is no per-user access list, and no “list all notes” page. Treat a note’s URL like a password. Do not put anything sensitive in HedgeDoc; for secrets use Vaultwarden, for sensitive documents use Paperless. Locked/Limited are conveniences, not security boundaries — the same “guardrails, not a security boundary” philosophy the rest of the lab infrastructure uses.

Retention policy (documented, not yet automated)

Unowned notes idle for a long time may be deleted without warning, and notes may be removed if the instance is abused. This is currently a stated policy, not an automated job — an admin may do a manual cleanup if needed. The practical rule for users: if a note matters, it needs an owner (log in and create it under your account) or it needs to be moved somewhere permanent.

Summary: What Goes in Vaultwarden

By the end of onboarding, your Bonham Lab folder in Vaultwarden should contain:

EntryUsernamePasswordTOTPNotes
Vaultwardenyour emailmaster password (memorized, not stored)✅ stored in authenticator apprecovery code stored separately on paper
Forgejoyour username✅✅ stored in VaultwardenSSH key stored locally; recovery codes as secure note
Paperlessyour username✅✅ stored in Vaultwardenrecovery codes as secure note
HedgeDocyour email✅ (if you have an account)— (no 2FA)Only needed if you want to own/protect notes; most use is anonymous

Troubleshooting

Locked out of Forgejo (2FA device lost): contact the admin. The admin can generate a new recovery code or reset 2FA via the Forgejo admin panel or CLI (forgejo admin user generate-2fa-secret).

Locked out of Paperless: contact the admin. Password can be reset via docker exec -it selfhosted-paperless-1 python3 manage.py changepassword <username> on the server.

Locked out of Vaultwarden: if you have your recovery code, use it at login. If not, contact the admin — the Vaultwarden admin panel can manage accounts, but the admin cannot recover your vault contents since they are end-to-end encrypted with your master password. This is by design.

Vaultwarden server URL not accepted in Bitwarden client: make sure you’re entering https://pw.bonhamlab.bio (with https://, no trailing slash) in the custom server field, not just the domain name.

Graph View

Backlinks