Package: bugout-brood
bugout-dev/broodWhat is Brood?Setting up user registration and login in your application can be challenging and time consuming.
Doing this from scratch takes a lot of planning. Since you're working with sensitive data (emails,
passwords, etc) it's important not to get it wrong.Giving users the ability to set up groups or teams within which they can share resources adds to this
challenge, and adding payments compounds it significantly.Brood is a web service that takes care of user management, team management, and payments in your
application as soon as you set it up.It is a free and open source alternative to systems like AWS Cognito and Auth0.Brood provides a REST API that you can use either directly from your frontend application or through
your own API or serverless application. It uses a Postgres database to store data about users,
teams, and payments.Payments are currently supported through Stripe.Brood has been battle tested in production and has been supporting millions of authentication events
a month since March 2021.Using BroodTo get started with Brood, we'll first need to create a user. This represents a user of your application.
Creating a user is as simple asPOSTing a form:curl-XPOSThttps://auth.bugout.dev/user\-F"username=pepper"\-F"email=pepper@example.com"\-F"password=1dc23a784ed36056887ef0967e8431817a1a2d9e2b3938eef0d0c9d0227d7c14"You can also create a user using one of our client libraries. For example, in Javascript:importBugoutClient,{BugoutTypes}from"@bugout/bugout-js";constbugout=newBugoutClient();bugout.createUser("pepper","pepper@example.com","1dc23a784ed36056887ef0967e8431817a1a2d9e2b3938eef0d0c9d0227d7c14","Pepper","Cat").then(console.log).catch((e)=>{console.error(e);process.exit(1);});Each user is identified to Brood using access tokens in the authorization header of Brood requests.
The authorization header should have the formAuthorization: Bearer <access_token>.If you are integrating Brood into your own API or serverless application, you can just pass this header
through to Brood when you are working with Brood resources and it will handle permissions on your
behalf with no hassles.To generate an access token for a user, you againPOSTa form:curl-XPOSThttps://auth.bugout.dev/token\-F"username=pepper"\-F"password=1dc23a784ed36056887ef0967e8431817a1a2d9e2b3938eef0d0c9d0227d7c14"In Javascript:importBugoutClient,{BugoutTypes}from"@bugout/bugout-js";constbugout=newBugoutClient();bugout.createToken("pepper","1dc23a784ed36056887ef0967e8431817a1a2d9e2b3938eef0d0c9d0227d7c14").then(console.log).catch((e)=>{console.error(e);process.exit(1);});CORS configurationIf you are using Brood directly from your frontend, you will need to configure the Brood server to
respond to CORS requests from your users' browsers. This is actually very simple. When you start
your Brood servers, simply set the following environment variable:BROOD_CORS_ALLOWED_ORIGINS="<domain at which your site is hosted>"For example, if your frontend lives athttps://frontend.example.com, then you would set:BROOD_CORS_ALLOWED_ORIGINS="https://frontend.example.com"You can pass multiple domains as a comma-separated list. If you had sites athttps://frontend.example.comand athttps://other-frontend.example.com, you would set:BROOD_CORS_ALLOWED_ORIGINS="https://frontend.example.com,https://other-frontend.example.com"In your development environment, you can set a localhost domain as follows:BROOD_CORS_ALLOWED_ORIGINS="http://localhost:3000"Client librariesTo make coding against the Brood API easier, you can use one of the client libraries:JavascriptPythonGoAPI documentationYou can find a more detailed documentation on the APIhereRunning BroodInstallation and setupTo set up Brood for development, do the following:Clone the git repositoryInstall postgresql (https://www.postgresql.org/download/linux/ubuntu/)Run server from terminalInstall requirementspipinstall-e.[dev]Copyconfigs/alembic.sample.initoconfigs/alembic.dev.iniEdit variablesqlalchemy.url = <...>intoalembic.dev.iniCopyconfigs/sample.envtoconfigs/dev.envEdit indev.envfile BROOD_DB_URI and other variables.Source environment variablessource configs/dev.envRun alembic migration./alembic.sh -c configs/alembic.dev.ini upgrade headOnce you're ready with the installation, start the server:./dev.shRun server with DockerTo be able to run Brood with your existing local or development services as database, you need to build your own setup.Be aware! The files with environment variablesdocker.dev.envlives inside your docker container!Copyconfigs/sample.envtoconfigs/docker.dev.env, or use your local configs fromconfigs/dev.envtoconfigs/docker.dev.envEdit indocker.dev.envfileBROOD_DB_URIand other variables if requiredClean environment file fromexportprefix and quotation marks to be able to use it with Dockersed--in-place's|^export * ||'configs/docker.dev.env
sed--in-place's|"||g'configs/docker.dev.envBuild container on your machinedockerbuild-tbrood-dev.Runbrood-devcontainer, with following command we specified--network="host"setting which allows to Docker container use localhost interface of your machine (https://docs.docker.com/network/host/)dockerrun--namebrood-dev\--network="host"\--env-file="configs/docker.dev.env"\-p7474:7474/tcp\-ti-dbrood-devAttach to container to see logsdockercontainerattachbrood-devRun server with Docker ComposeIf you want to deploy Brood in isolation against live services, then docker compose is your choice!Run scriptconfigs/docker_generate_env.bashwhich prepare for you:configs/docker.brood.envwith environment variablesconfigs/alembic.brood.iniwith postgresql uri./configs/docker_generate_env.bashRun local setupdocker-composeup--buildAfter setupFresh server is not fully functional, in order to add additional functionality you need to create subscriptions, resources and etc.GroupsTo be able to create new groups, free subscription plan should be generated with record in kv_brood table:python-mbrood.cliplanscreate\--name"Free plan"\--description"free plan description"\--default_units5\--plan_type"seats"\--publicTrue\--kv_keyBUGOUT_GROUP_FREE_SUBSCRIPTION_PLANCLIGroupsCreate new group with specified--nameand--usernameas an ownerpython-mbrood.cligroupscreate--name"bugout-group"--username"neeraj"Add user to group with specified--nameasgroup_name,--usernameand--typeasmember/ownerpython-mbrood.cligroupsrole--name"bugout-group"--username"tim"--type"member"|jq.