Bonham Lab Wiki

Lab services onboarding

Properties2
tagscomputing, protocol, admin
typeprotocol

6 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)

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

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