Getting Started
Brut is developed alongside a separate gem called mkbrut
, which allows you to create a new Brut app. It will set up your dev environment as well.
Get mkbrut
The simplest way to use mkbrut
is to use an existing Docker image. You don't have to install or configure Ruby:
docker run \
-v "$PWD":"$PWD" \
-w "$PWD" \
-it \
thirdtank/mkbrut \
mkbrut my-new-app
If you already have Ruby 3.4 installed, you can install mkbrut
directly:
> gem install mkbrut
> mkbrut my-new-app
Init Your App
A Brut app just needs a name, which will be used to derive a few more useful values. For now:
docker run \
-v "$PWD":"$PWD" \
-w "$PWD" \
-it \
thirdtank/mkbrut \
mkbrut my-new-app
mkbrut my-new-app
This will create your new app, along with some demo routes, components, handlers, and tests. If this is your first time using Brut, we recommend you examine these demo components.
To create your app without the demo components:
docker run \
-v "$PWD":"$PWD" \
-w "$PWD" \
-it \
thirdtank/mkbrut \
mkbrut my-new-app --no-demo
mkbrut my-new-app --no-demo
Start Your Dev Environment
Brut includes a dev environment based on Docker. It uses Docker compose to run a Docker container where your app will run, a Docker container for Postgres, and a Docker container for local observability via OpenTelemetry.
Build the image used to create you app's container:
> dx/build
Start up all the containers:
> dx/start
Now, install your aps gems and set it all up:
> dx/exec bin/setup
Now, you're ready to go. See Dev Environemnt for details on how this all works.
NOTE
Instead of running dx/exec
in front of your commands, you can instead do dx/exec bash
to "log in" to the running container. You'll have a normal prompt and can issue commands directly from there.
Run the App
dx/exec bin/dev
You can now visit your app at localhost:6502
You can make changes and see them when you reload. Open up app/src/front_end/pages/home_page.rb
in your editor running on your computer and change the h1
to look like so:
class HomePage < AppPage
def page_template
div(class: "flex flex-column items-center justify-center h-80vh") do
img(src: "/static/images/icon.png", class: "h-50")
h1(class: "ff-sans ma-0 lh-title f-5") do
"Welcome to My New App!"
end
# ...
When you reload your browser, you'll see your change
Run the Tests
There are a few tests you can run, as well as some checks that you aren't using RubyGems with security vulnerabilities. Run it all now with bin/ci
:
dx/exec bin/ci
Now Build The Rest of Your App 🦉
You can follow the tutorial, check out the conceptual overview, or dive straight into the API docs. You might also want to check out the docs for LSP Support.