search

breadboard-ai / breadboard

A library for prototyping generative AI applications.
Apache License 2.0
160 stars 22 forks source link

[docs] Breadboard from scratch #2675

Open timswanson-google opened 1 month ago

timswanson-google commented 1 month ago

Breadboard from scratch

Document the process for creating and deploying the full suite of Breadboard components from scratch.

Assumes no previous setup. Target audience is a developer who wants to create their own independently running Breadboard instance, all available features, with no reliance on anything already deployed.

Run through the process on a fresh account. Document steps and pitfalls. Add a page in the docs describing the process.

timswanson-google commented 1 month ago

Step 0: Required software

The docs won't go into how to set up the user's system. It's assumed that they either already have these things, or know how to get them.

timswanson-google commented 1 month ago

First problem encountered with deploying the visual editor. It looks like the firebase.json file has properties that are specific to the Breadboard team's publicly deployed editor at https://breadboard-ai.web.app/

https://github.com/breadboard-ai/breadboard/blob/main/packages/visual-editor/firebase.json

Maybe we should delete this file from the repo, and encourage users to run firebase init, which creates it.

timswanson-google commented 1 month ago

Actually, it looks like we can just delete "site": "breadboard-ai" from the JSON file and it works fine. It uploads to the default site of the current project.

dglazkov commented 1 month ago

Actually, it looks like we can just delete "site": "breadboard-ai" from the JSON file and it works fine. It uploads to the default site of the current project.

Ah, turns out this breaks Firebase hosting. We can still deploy to app engine, but if we try to deploy to Firebase hosting (which is where breadboard-ai.web.app is hosted, it breaks.

timswanson-google commented 1 month ago

Ah, turns out this breaks Firebase hosting. We can still deploy to app engine, but if we try to deploy to Firebase hosting (which is where breadboard-ai.web.app is hosted, it breaks.

What is the error when you try to run it?

I'm looking at that Firebase project, and it has two sites. So I'm thinking maybe the "deploy to default site" logic doesn't work when there's more than one.

dglazkov commented 1 month ago

What is the error when you try to run it?

It's a confluence of two things:

  1. I need to set up the default project with firebase --add
  2. The way firebase hosting works is that you can't do anything with the default site (can't remove it, change the default, etc.), and the default site isn't the one we're deploying to.
timswanson-google commented 1 month ago

Ok. I don't think we should revert the PR, because the old config only works for our site. Maybe update the mechanism so that it can take a param? (Can you do that with npm scripts?)

dglazkov commented 1 month ago

Can you do that with npm scripts?

yup!

Another thing we can do is document the appengine setup (not using firebase hosting) as the prefered approach.

timswanson-google commented 1 month ago

Another thing we can do is document the appengine setup (not using firebase hosting) as the prefered approach.

I've been working through this doc using Firebase hosting. Should I switch to appengine? Are there any docs currently?

dglazkov commented 1 month ago

I've been working through this doc using Firebase hosting

oh, sorry, I didn't realize that. LGTM. We do need to figure out how to deploy to breadboard-ai. Currently our workaround is to revert the commit locally.

Also, yes -- you can deploy to app engine as well. There's an app.yaml in packages/visual-editor that is configured to deploy if you run gcloud app deploy in that dir.

timswanson-google commented 1 month ago

Doc started for Visual Editor on a new branch. Will submit a PR to main when we think it's ready to go on the public site.

https://github.com/breadboard-ai/breadboard/blob/scratch/packages/website/src/docs/guides/breadboard-from-scratch.md

dglazkov commented 1 month ago

Please feel free to land, gives you higher iteration loop, less time off the trunk.

timswanson-google commented 1 month ago

Ok, I'll do that. It would be good to see how the doc looks on github.io as well, and as far as I can tell there's no way to render a branch on the docs site. (Please let me know if there is, that would be useful.)

dglazkov commented 1 month ago

You can render it locally using npm run dev in packages/website or npm run d at the repo root.

timswanson-google commented 1 month ago

The page now has working end-to-end instructions that are verified in a fresh Google account with a new Cloud project.

https://breadboard-ai.github.io/breadboard/docs/guides/breadboard-from-scratch/

The next step is to do a revision and polish pass. Adding screenshots where appropriate, and updating instructions where a better way exists.

Parallel to this, also want to start brainstorming process improvements and to file issues for those.

Will close this issue once those two things are done.