Getting Started

If you have trouble with one of the steps below, make sure to checkout the Troubleshooting section.

Project Setup

Make sure Docker, Node (>= version 18), and pnpm are installed.
- Docker
- Node (>= version 18)
- pnpm
- Erlang
- Elixir
It's recommended to use a version manager (like asdf or mise) to install erlang, elixir, node and pnpm.
Configure the npm registry
- Create a Personal Access Token and give it the "repo" and "read:packages" scopes (No expiration).
- Copy this into ~/.npmrc
```
//npm.pkg.github.com/:_authToken="<<token goes here>>"
@kualibuild:registry=https://npm.pkg.github.com/
```
- Copy this into ~/.zshrc or ~/.bashrc or ~/.bash_profile. Make sure it comes BEFORE any nvm references (why?):
```
export KUALIBUILD_NPM_TOKEN="<<token goes here>>"
```
Configure the private hex repo (needed for Oban Pro)
You'll need to get the command with the secret from 1Password or another engineer.
Install the build cli: pnpm add -g @kualibuild/build-cli
Create a folder for your kuali code: mkdir -p ~/code/kuali
Setup the builder-ui project: cd ~/code/kuali && git clone git@github.com:kualibuild/builder-ui.git && cd builder-ui && pnpm install
Setup the platform project: cd ~/code/kuali && git clone git@github.com:kualibuild/platform.git && cd platform && mix do deps.get, deps.compile
Run: mkdir ~/code/kuali/__ && touch ~/code/kuali/__/build.services.json5 and then copy this into that new file:

{
  undocked: ['../builder-ui', '../platform']
}

Start the platform services: cd ~/code/kuali/__ && build up
Run migrations for the platform project: cd ~/code/kuali/platform && mix do ecto.create, ecto.migrate
Once that's finished, start the ui project: cd ~/code/kuali/builder-ui && pnpm dev
In another terminal tab/window, start the platform project: cd ~/code/kuali/platform && mix phx.server
Run pnpx @kualibuild/bootstrap@latest. This will create all needed databases in core and build, grant full permissions to the kualiadmin user, and add Build to the grid menu.
Login at https://local.kualibuild.com with user: kualiadmin, password: admin

Next Steps

Head on over and read the Frequently Asked Questions.

Troubleshooting

There is a security warning for using the certificate

You can trust the certificate authority that caddy generated. The file is located at ~/.config/@kualibuild/build-cli/ingress/data/caddy/pki/authorities/local/root.crt.

On macOS, open up at file and it should open up Keychain Access. Adjust the trust settings to always trust.

Or you can run this command:

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/.config/@kualibuild/build-cli/ingress/data/caddy/pki/authorities/local/root.crt

Chrome won't let me bypass the security warning locally :(

Click anywhere on the warning page and then type "thisisunsafe". Yes, this seriously works.

I'm getting permission errors when trying to install the build cli

Check your error logs and see where npm/yarn/pnpm is trying to fetch the cli from. If you see https://npm.pkg.github.com/@kualibuild%2fbuild-cli then chances are that you actually don't have permissions to get the cli. Contact someone on the platform team and they can get you added.

If npm/yarn/pnpm is trying to fetch https://registry.npmjs.org/@kualibuild%2fbuild-cli then you've got a different issue. That's the wrong registry and indeed, our cli doesn't exist there. This happens when (for some unknown reason) yarn doesn't honor the settings in .npmrc. The fix here is to create a file called ~/.yarnrc and copy the following snippet into it:

registry "https://npm.pkg.github.com/"
"@kualibuild:registry" "https://npm.pkg.github.com"

Then run npm login --registry=https://npm.pkg.github.com --scope=@kualibuild. Once you've done this you should be able to resume the instructions above by installing the build cli.

I'm getting a weird error about the AWS REGION not being valid when running build up

Try creating another entry in ~/.aws/config and ~/.aws/credentials with all the same data but name the profile default. In particular, it is known that a default profile is required to exist in ~/.aws/config.

I see this error when running build up: SyntaxError: Unexpected token .

This probably means you're running an unsupported version of node. Make sure you've installed and are using node >= 16. The build cli use the ?. operator which was added in that version.

build up shows errors when pulling some or all of the images

First check and see which images are failing. If you're failing to pull mongo, redis, maildev, or postgres then there's a good chance you don't have docker installed/running properly. Those images come straight from the public docker registry. Go troubleshoot docker on The Google until you're able to successfully run docker -D run hello-world. Then come back and try again.

If you're unable to pull identity or ingress it means you're not correctly authenticated with Github. Sync up with someone on the platform team and they can make sure you're added to the right Github team.

If you can't pull the rest (proxy, builder-api, forms-api, etc.) it probably means your aws credentials don't have access to our ECR buckets. Shoot an email over to ops@kuali.co and they'll help you get everything sorted out.

https://github.com/docker/cli/issues/1263

brew install watchman