Skip to content

Onboarding — Your First Week

Welcome. This guide gets you from "I have access" to "I can ship a change" in five days.

Day 1 — Accounts and access

You need three accounts before you can do anything. Ask João or Cristina to create them — there is no self-signup anywhere.

  1. Vaultwarden account at https://vault.joaoluisbrazao.cloud
  2. This is where all credentials live
  3. From inside Vaultwarden, you will find your Forgejo, Vikunja, and SSH key passphrases
  4. Forgejo account at the JB git server (URL inside Vaultwarden)
  5. All source code lives here, not GitHub
  6. Vikunja account at the JB task manager
  7. The single source of truth for what needs to be done
  8. Look at the Onboarding list — that is your starting backlog

Test: by end of day 1 you should be able to clone one Forgejo repo to your laptop and see your assigned tasks in Vikunja.

Day 2 — Read the map

Read in this order, take notes:

  1. vps-overview.md — what machine you are working against
  2. docker-layout.md — what is running, grouped by purpose
  3. networking.md — how the world reaches the apps
  4. security.md — the boundaries you must not cross
  5. adr/ — read all of them. They are short.

Test: answer these without looking — Why is GitHub not used? What is the only nginx replacement we accept? Where do health-data records live and why?

Day 3 — The big idea

JB infrastructure is built around three principles. Internalise them:

  1. Sovereignty. No SaaS for code, secrets, or knowledge. Everything self-hosted on this one VPS or on the Intel Mac home server.
  2. One machine, well known. No Kubernetes, no fleet. One box, well documented, well backed up.
  3. AI as an operator, not a co-author. Paperclip skills (43 of them, in jb-skills-gateway) run on cron and on-demand to keep the system healthy. You will end up writing skills, not just apps.

Day 4 — Ship something tiny

Pick the smallest Vikunja task assigned to you. Do not pick infrastructure work in your first week.

  1. Branch from develop (never from main)
  2. Open the relevant project's docs/ folder — read its onboarding.md and architecture.md
  3. Make the change
  4. Open a merge request in Forgejo
  5. Tag the maintainer listed in the project's index.md

No commit goes directly to main or staging. Production promotion requires explicit approval from João.

Day 5 — Operations basics

  • Where logs are: docker logs <container> for live logs, structured logs to stdout per app
  • How to know if something is broken: Uptime Kuma + Telegram @DownRabbitbot
  • Where the runbooks are: each project has docs/runbooks/; infra runbooks are in runbooks/
  • Who to ask for what:
Question type Ask
"How does X work?" Project's docs/ first, then the maintainer in index.md
"What should I work on?" Vikunja
"Why was this decision made?" The relevant adr/
"Something is on fire" @DownRabbitbot channel, then escalate to João

What you should never do without asking

  • Push to main of any repo
  • Run docker system prune -a (kills shared images)
  • Modify nginx config or UFW rules
  • Touch Vaultwarden master password
  • Delete anything in /opt/backups/
  • Reboot the VPS
  • Use git push --force to any shared branch

What you should do proactively

  • Update the project's docs/ whenever you change behaviour that contradicts what is documented
  • Write an ADR when you make a non-obvious decision
  • Add a runbook when you solve a problem you might face again
  • Add a row to errors/REGISTRY.md if you debug an error that took more than 30 minutes