Board: new hire to first commit

The goal is to show a new developer going from a blank laptop to a running project with the same packages as everyone else, using the repo itself as the setup guide.

This page is drawn from https://flox.dev/blog/setting-up-a-new-laptop-made-easy-with-flox/, https://flox.dev/blog/flox-and-teams-onboarding-made-easy-with-github-and-flox/, https://flox.dev/blog/reproducible-development-environment-in-any-repo-part-1/, https://flox.dev/blog/reproducible-development-environment-in-any-repo-part-2/, https://flox.dev/docs/tutorials/sharing-environments, https://flox.dev/docs/concepts/environments and https://flox.dev/docs/man/flox-activate.

Whiteboard outcome

When you are done, the board shows a new laptop, a git repo with a .flox folder committed in it, one arrow labeled flox activate, and a lock file on the left that guarantees the new laptop and a teammate’s laptop get the same versions.

Before you draw: three questions

1. How long does a new hire take today to run the project, and what do they follow: a wiki, a script, a Docker Compose file?
2. What do laptops run: macOS, Linux, both? (System-specific packages need a manifest edit; https://flox.dev/docs/tutorials/sharing-environments.)
3. Do developers need services such as a database, and do they also need their own personal tools on every new machine?

Draw it in 8 steps

1. On the left, draw a git repo with a folder .flox inside it. Say: A Flox environment “stores its metadata, declarative manifest, and manifest lock file in a .flox directory”, and path environments can be committed to version control (https://flox.dev/docs/concepts/environments).
2. Inside the folder, draw two files: manifest.toml and manifest.lock. Say: the manifest is what you asked for. “The lock file serves as a snapshot of the specific package versions and their dependencies that were built and activated at a particular point in time” (https://flox.dev/docs/concepts/environments).
3. Draw a brand new laptop on the right with an arrow labeled git clone. Say: the new developer gets the code and the environment together, because the folder is just files in the repo (https://flox.dev/docs/tutorials/sharing-environments).
4. Draw a second arrow labeled flox activate. Say: it will “automatically download the same versions of those packages to their machine” (https://flox.dev/docs/tutorials/sharing-environments). The Flox CLI itself is installed first; the onboarding blog has a bootstrap script do that (https://flox.dev/blog/flox-and-teams-onboarding-made-easy-with-github-and-flox/).
5. Draw a small clock beside the arrow labeled “first time only”. Say: packages download on the first activation, and the blog’s new-hire story has Flox install Hugo, Node.js, a pinned Go and ImageMagick for a docs repo (https://flox.dev/blog/flox-and-teams-onboarding-made-easy-with-github-and-flox/). How long this takes depends on the package set and network [verify]; no source gives a benchmark.
6. Draw a cylinder labeled “services” attached to the laptop. Say: the story’s front-end repo starts Node.js, nginx and an OpenTelemetry collector as services after flox activate, and the blog stresses “Flox does this without VMs or containers” (https://flox.dev/blog/flox-and-teams-onboarding-made-easy-with-github-and-flox/). Part 1 adds that environments run “on your local system, not in hermetically sealed containers or VMs”, so files, secrets and env vars stay reachable (https://flox.dev/blog/reproducible-development-environment-in-any-repo-part-1/).
7. Draw a dashed arrow from FloxHub to the laptop for personal tools. Say: flox pull --copy <username>/default then flox activate set up a whole userland on a new machine (“Your entire userland is set up on your new MacBook”), while flox activate -r runs a FloxHub environment without cloning anything (https://flox.dev/blog/setting-up-a-new-laptop-made-easy-with-flox/, https://flox.dev/docs/tutorials/sharing-environments).
8. At the bottom, write the rule: If it is in the repo, flox activate is the setup guide. (https://flox.dev/docs/tutorials/sharing-environments)

flowchart LR
  subgraph R[Git repo]
    F[.flox folder<br/>manifest.toml<br/>manifest.lock]
  end
  FH[FloxHub<br/>default env and team envs]
  R -->|git clone| L[New laptop]
  L -->|flox activate| E[Same packages<br/>as teammates]
  FH -.flox pull or activate -r.-> L
  E --> S[Local services<br/>and first commit]

What can go wrong

• A repo with no .flox yet. Part 2 shows an agent turning Node-RED into an environment in minutes, ending with “Just commit the .flox directory to your repo” (https://flox.dev/blog/reproducible-development-environment-in-any-repo-part-2/). The agent route is covered on the agent board.
• Different OS or CPU. Packages that exist only on one platform can fail on another, fixed “with a minor edit to the manifest” (https://flox.dev/docs/tutorials/sharing-environments).
• Private FloxHub environments. Activating a private remote environment with -r requires login (https://flox.dev/docs/man/flox-activate).

What they will ask