brut 0.0.28 → 0.1.0

data/brutrb.com/deployment.md

@@ -1,66 +1,144 @@
 # Deployment
 
 Brut apps are Rack apps, so they can be deployed in conventional
-ways.   Brut apps are 12-factor apps and the scripts used for
-development are inteded to work for production as well.
+ways.
 
 ## Overview
 
-Everyone deploys apps in different ways.  Brut can't provide a
-simple solution for all deployment setups, so this document will
-outline considerations when setting up deployment.
+There are just too many ways to deploy.  Brut attempts to address this by adhering to [12-factor principles](https://12factor.net).  Brut also tries not to create artifacts like `Procfile` or `Dockerfile` that would conflict with the artifacts you'd need to manage deployment.
 
-The most direct way to understand what needs to happen is to look
-at `deploy/Dockerfile`, which is the foundation of a `Dockerfile`
-you can use.  In particular, it shows you the commands needed to
-setup and run the app in production:
+That said, Brut includes first-class support for deploying to Heroku using containers.  More options will be included as necessary, either through direct support in code/tooling, or documentation here.
 
-Beyond installing system software to run any Ruby web app, as well
-as whatever is needed for NodeJS and Postgres, the Brut-specific
-parts look like so:
+### Heroku Container-based Deployment
 
-1. Install Ruby Gems with `bundle install`
-2. Install Node modules with `npm clean-install`
-3. Build all assets with `bin/build-assets` (this will bundle all
-   CSS and Javascript, plus copy over any other [assets](/assets)
-   to the locations from where the Brut app will serve them)
-4. Run the app with `bin/run`
+When creating your Brut app with `mkbrut`, the Heroku segment can be used to create files and scripts for a [Heroku container-based deployment](https://devcenter.heroku.com/articles/container-registry-and-runtime).
 
-Your Brut app also includes `bin/release` which is a script
-intended to run in the production environment after the code has
-been deployed, but before the app starts up.  By default, it
-applies any needed migrations to the database.
+| File | Purpose | Notes |
+|------|---------|-------|
+| `bin/deploy` | Script to use to perform the deployment | This wraps `HerokuContainerBasedDeploy` in `Brut::CLI::Apps` |
+| `deploy/Dockerfile` | Template `Dockerfile` used to create a `Dockerfile` for each process type | Heroku requires each process (web, worker, release, etc.) to have its own `Dockerfile` and own image |
+| `deploy/heroku_config.rb` | Class that exports optional processes | By default, your app has a web and release process. `HerokuConfig` can export others, like Sidekiq |
+| `deploy/docker-entrypoint` | The [`ENTRYPOINT`](https://docs.docker.com/reference/dockerfile/#entrypoint) for production Docker images, which is set up to use jemalloc | You can modify or remove this as needed |
+
+How to deploy:
+
+1. Auth to Heroku from inside your dev container:
+
+   ```
+   your-computer> dx/exec bash
+   devcontainer> heroku auth:login
+   # You will need to copy/paste the URL to log in
+   devcontainer> heroku container:login
+   ```
+
+2. Create your app using the container stack:
+
+   ```
+   > heroku create --stack container -a «your heroku app name»
+   ```
+3. Ensure your app's source code is all checked in, there are no uncommitted or unadded files, and you have pushed to main.
+4. `bin/deploy`
+
+   This will generate a `Dockerfile` for each process (by default, `Dockerfile.web` and `Dockerfile.release`), build images, push those images to Heroku, and ask Heroku to release them.
+
+Debugging Tips:
+
+* Keep in mind it's hard to make general deployment tools. You are expected to understand your deployment and be capable of deploying an arbitrary Rack app manually.  Brut's tooling automates what you need to know.
+* `bin/deploy` runs the `deploy` subcommand, so `bin/deploy help deploy` can provide
+some options for debugging issues:
+
+  ```
+  devcontainer> bin/deploy help deploy
+  Usage: bin/deploy [global options] deploy [command options] 
+
+      Build images, push them to Heroku, and deploy them
+
+      Manages a deploy process based on using Heroku's Container Registry. See
+
+      https://devcenter.heroku.com/articles/container-registry-and-runtime
+
+      for details. You are assumed to understand this.
+      This command will make the process somewhat easier.
+
+      This will use deploy/Dockerfile as a template to create
+      one Dockerfile for each process you want to run in Heroku.
+      deploy/heroku_config.rb is where the processes and their
+      commands are configured.
+
+      The release phase is included automatically, based on bin/release.
+
+  GLOBAL OPTIONS
+
+      -h, --help            Get help
+          --log-level=LEVEL Set log level. Allowed values: debug,
+                            info, warn, error, fatal. Default 'fatal'
+          --verbose         Set log level to 'debug', which will produce
+                            maximum output
+
+  ENVIRONMENT VARIABLES
+
+      BRUT_CLI_RAISE_ON_ERROR - if set, shows backtrace on errors
+      LOG_LEVEL               - log level if --log-level or --verbose is omitted
+
+
+  COMMAND OPTIONS
+
+          --platform=PLATFORM  Override default platform. Can be any Docker
+                               platform.
+          --[no-]dry-run       Print the commands that would be run and
+                               don't actually do anything. Implies --skip-checks
+          --[no-]skip-checks   Skip checks for code having been
+                               committed and pushed
+          --[no-]deploy        After images are pushed, actually deploy them
+          --[no-]push          After images are created, push them
+                               to Heroku's registry. If false,
+                               implies --no-deploy
+  ```
+* Try building images first: `bin/deploy deploy --no-push --skip-checks`
+* It's possible to run the images locally.  If you are on Apple Silicon, you'll
+  need to set --platform:
+
+  * `bin/deploy deploy --no-push --skip-checks --platform linux/arm64`
+  * Create `docker-compose.yml` for your image and any other services e.g. databases
+  * Set required environment variables in `docker-compose.yml`
+  * Start up Docker compose and poke around
+
+  You'll need to have a better understanding of Docker to do this, however if you
+  are deploying with Docker, this is an understanding you hopefully already have.
+
+
+### Other Mechanisms for Deployment
+
+As a Rack app, other deployments should be possible.  To make the app work, you'll need to make sure a few things are dealt with:
+
+* `RACK_ENV` **must** be `"production"`
+* `bin/build-assets` will build all assets by default.  This must either be done on production servers or done ahead of time and the results packaged with the app.
+* `bin/build-assets` outputs files in `app/public` and `app/config`.  Those files are used at runtime.  Brut **will not** initiate the build of any assets.
+* If you are going to build assets on production servers, you *must* included developer tooling. This means NodeJS, all modules in `package.json` and all RubyGems in `Gemfile`.
+
+The `deploy/Dockerfile` created by `mkbrut --segment-heroku` is not very Heroku-specific and could serve as a reference.
 
 ## Testing
 
-If you are using Docker, you can create the `Dockerfile`s and run
-them locally to see how they work.  You will need to have local
-versions of all infrastructure (database, Redis, etc.), but if
-these work locally, there is a high chance they work in
-production.
+Testing deployments is a bit out of scope, but in general:
 
-If you are not using Docker, you will need to apply various
-techniques that are beyond the scope of this documentation.
+* A container-based deployment can theoretically be run on your computer as a test.
+* Non-production, but production-like environments can be used to validate production configurations.
+* You own the means of production…not Brut.
 
 ## Recommended Practices
 
-Brut goes to great lengths to avoid environment-specific code.
-Much of Brut's behavior works the same in dev as it does in
-production. For example, assets are hashed in all environments.
+* Avoid a lot of code that checks `Brut.container.project_env`.  Try to consolidate all prod/test/dev differences in environment variables.
+* Have a way to get a shell into your production environment for debugging.
+* Brut doesn't log much, but if you remove the `OTEL_*` environment variables, Brut will log OTel telemetry to the console, which may be useful. 
+* Setting `OTEL_LOG_LEVEL=debug` is advised if the app isn't starting or you aren't seeing any telemetry or logging
 
-Assuming your code does the same thing, there should be a minium
-of surprises.  That all being said, here are some recommendations:
+## Technical Notes
 
-* Create a way to interact with external services in a testing
-capacity. For example, ensure you have a test user with a known
-email address and trigger an email to them.  Or a company credit
-card you charge and refund.
-* Configure observability so you know what your app is doing at
-all times.
-* Configure a URL that, when accessed, produces an error. This
-allows you to check your error reporting system.
-* Create a page somewhere that shows the git SHA of your
-deployment, or some other unique, unambiguous version number. This
-will clarify what version of the code is actually running.
+> [!IMPORTANT]
+> Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut's
+> internals, the source code is always more correct.
 
+_Last Updated July 3, 2025_
 
+None at this time.

data/brutrb.com/dev-environment.md

@@ -1,6 +1,6 @@
 # Dev Environment
 
-Brut provides sophisticatd tooling to manage your dev environment
+Brut provides sophisticated tooling to manage your dev environment
 
 ## Overview
 
@@ -41,7 +41,7 @@ Your editor and version control system run on your computer.
 These are the commands you will use to manage the *foundational core*, which is the Docker containers and
 their contents.
 
-A few brief terminoloy notes if you aren't familiar with Docker:
+A few brief terminology notes if you aren't familiar with Docker:
 
 * A Docker *container* is akin to a virtual machine. On Linux this isn't strictly true, but conceptually, you can think of this like a virtual computer.
 * A Docker *image* is what you use to start a container.  This is akin to a disk image you might use to
@@ -52,7 +52,7 @@ A few verbs to provide additional help:
 
 * One *builds* a Docker image from a Dockerfile.
 * One *starts* a Docker container from an image.
-* One *stops* a Docker conatiner when it's no longer needed.
+* One *stops* a Docker container when it's no longer needed.
 
 
 | App        | Purpose                                                                |
@@ -68,7 +68,7 @@ The workflow for the foundational core is shown in this diagram.
 
 In words:
 
-1. You build the images based on the latest instrutions via `dx/build`.
+1. You build the images based on the latest instructions via `dx/build`.
 2. You start up the environment with `dx/start`.
 3. You then use `dx/exec` to execute commands from the Workspace (see below).
 4. When you are done working for the day, `dx/stop` shuts everything down.
@@ -90,7 +90,7 @@ you full documentation about what the command and subcommands do.
 |                 | `drop`                | Drop the database if it exists                                                            |
 |                 | `migrate`             | Apply any outstanding migrations to the database                                          |
 |                 | `new_migration`       | Create a new migration file                                                               |
-|                 | `rebuild`             | Drop, re-create, and run migrations, effecitvely rebuilding the entire database           |
+|                 | `rebuild`             | Drop, re-create, and run migrations, effectively rebuilding the entire database           |
 |                 | `seed`                | Load seed data into the database                                                          |
 |                 | `status`              | Check the status of the database and migrations                                           |
 | <code style="white-space: nowrap">bin/dbconsole</code> | None                  | Starts up a `psql` session to your database                                               |
@@ -138,7 +138,7 @@ While you are free to set up mise or rbenv or whatever to run all this on your c
 working is currently not supported nor encouraged.  For now, Brut will focus on the Docker-based approach.
 
 The primary reason is that it's a tightly controlled environment that is almost
-entirely scriptable, but does not require devs to abandon their preffered editor.
+entirely scriptable, but does not require devs to abandon their preferred editor.
 Environment manager-based approaches tend to be more fussy and require documentation
 to ensure they are set up.
 
@@ -174,7 +174,7 @@ exit Brut::CLI.app(
      )
 ```
 
-These files have a lot of duplication, but should be relatively stable.
+These files have some duplication, but should be relatively stable.
 
 This means that Brut-provided CLIs *will*  be updated when you update Brut.  Compare this to the files in
 `dx/` which are entire Bash scripts that will not be updated when Brut is updated.

data/brutrb.com/dir-structure.md

@@ -0,0 +1,120 @@
+# Directory Structure
+
+```
+.
+├── app
+│   ├── config
+│   │   └── i18n
+│   │       └── en
+│   ├── public
+│   │   ├── css
+│   │   ├── js
+│   │   └── static
+│   │       └── images
+│   └── src
+│       ├── back_end
+│       │   ├── data_models
+│       │       ├── db
+│       │       ├── migrations
+│       │       └── seed
+│       ├── cli
+│       └── front_end
+│           ├── components
+│           ├── css
+│           ├── fonts
+│           ├── forms
+│           ├── handlers
+│           ├── images
+│           ├── js
+│           ├── layouts
+│           ├── pages
+│           ├── route_hooks
+│           ├── support
+│           └── svgs
+├── bin
+├── deploy
+├── dx
+└── specs
+    ├── back_end
+    │   ├── data_models
+    │       └── db
+    ├── e2e
+    ├── factories
+    │   └── db
+    └── front_end
+        ├── components
+        ├── handlers
+        ├── js
+        ├── pages
+        └── support
+```
+
+## Top Level
+
+| Directory | Purpose |
+|-----------|---------|
+| `app/`    | Contains all configuration and source code specific to your app |
+| `bin/`    | Contains tasks and other CLIs to do development of your app, such as `bin/test` |
+| `dx/`     | Contains scripts to manage your development environment |
+| `specs/`  | Contains all tests |
+
+## Inside `app`/
+
+| Directory | Purpose |
+|-----------|---------|
+| `bootstrap.rb` | A ruby file that sets up your app and ensures everything is `require`d in the right way. |
+| `config/` | Configuration for your app, such as localizations and translations. Brut tries very hard to make sure there is no YAML in here at all. YAML is not good for you. |
+| `public/` | Root of public assets served by the app. |
+| `src/` | All source code for your app |
+
+Inside `app/src`
+
+| Directory | Purpose |
+|-----------|---------|
+| `app.rb` | The core of your app, mostly configuration, such as routes, hooks, middleware, etc. |
+| `back_end/` | Back end classes for your app including database schema, DB models, seed data, and your domain logic |
+| `cli/` | Any CLIs or tasks for your app |
+| `front_end/` | The front-end for your app, including pages, components, forms, handlers, JavaScript, and assets |
+
+Inside `app/src/back_end`
+
+| Directory | Purpose |
+|-----------|---------|
+| `data_models/app_data_model.rb` | Base class for all DB model classes |
+| `data_models/db` | DB model classes |
+| `data_models/db.rb` | Namespace module for DB model classes |
+| `data_models/migrations` | Database schema migrations |
+| `data_models/seed` | Seed data used for local development |
+
+Inside `app/src/front_end`
+
+|Directory       | Purpose |
+|----------------|---------|
+| `components/`  | Component classes |
+| `css/`         | CSS, managed by esbuild and `bin/build-assets` |
+| `fonts/`       | Custom fonts, managed by esbuild and `bin/build-assets` |
+| `forms/`       | Form classes |
+| `handlers/`    | Handler classes |
+| `images/`      | Images, copied to `app/public` by `bin/build-assets` |
+| `js/`          | JavaScript, managed by esbuild and `bin/build-assets` |
+| `layouts/`     | Layout classes |
+| `middlewares/` | Rack Middleware, if any |
+| `pages/`       | Page classes |
+| `route_hooks/` | Route hooks, if any |
+| `support/`     | General support classes/junk drawer. |
+| `svgs/`        | SVGs you want to render inline |
+
+## Inside `specs/`
+
+`specs/` is intended to mirror `app/src`, but has a few extra directories:
+
+
+|Directory       | Purpose |
+|----------------|---------|
+| `specs/back_end` | tests for all back-end code, organized the same as `app/src/back_end` |
+| `specs/back_end/data_models/db` | tests for all DB classes, if needed |
+| `specs/e2e` | End-to-end tests, organized however you like |
+| `specs/factories` | Root of all factories for FactoryBot. You can create subdirectories here for non-DB classes you may want to be able to create |
+| `specs/factories/db` | Factories to create DB records |
+| `specs/front_end` | tests for all front-end code, organized the same as `app/src/front_end` |
+| `specs/js`| *JavaScript* code to test any autonomous custom elements you have created |

data/brutrb.com/doc-conventions.md

@@ -2,32 +2,35 @@
 
 ## Terminology
 
-Brut attempts to use existing terminology where possible, particularly where that technology applies to the web platform.  For example, there is not a thing called "CSS variables", rather the term is "custom properties". HTML entities are *elements* or *tags* that have *attributes*. As another example, HTML doesn't have *validations*, rather it as *constraints*, which can be *violated*.
+Brut attempts to use existing terminology where possible, particularly where that technology applies to the web platform.  For example, there is not a thing called "CSS variables", rather the term is "custom properties".
 
-When speaking about Ruby, we prefer the term *initializer* over constructor, *parameters* over arguments, and *methods* over messages.  We also prefer *tests* over specs, however test files *are* located in `specs/` and named `*.spec.rb` to be consistent with RSpec's nomenclature.  We prefer *end-to-end* or *e2e* tests instead of browser tests or request specs. 
+Here are some common exampels:
 
-Further, Brut doesn't render HTML, it *generates* it.  The browser renders the HTML for the website's visitor. One exception is Phlex, which uses the term *render* to mean "generate HTML to an internal buffer that will be delivered to the client later".  Thus, you will need to call Phlex's `render` method from time to time, even though it is not rendering HTML but helping to generate it.
 
-Lastly, the documentation tries to talk about the person accessing a website as a "vistor" not a "user". Though the "user" nomenclature is near-ossified in software development, we feel "visitor" is more apt.
+- HTML entities are **elements** or **tags**
+- HTML elements have **attributes**.
+- Forms don't have validations, they have **constraints** which are **violated** by invalid data.
+- Ruby classes don't have constructors, they have **initializers**.
+- Invoking behavior on a Ruby object is **calling a method**, not sending a message.
+- Despite being in `specs/`, the files in there are **tests**, not specifications or
+-specs".
+- Tests that use a browser are **end to end** or **e2e** tests.
+- HTML is not rendered, but **generated**. The browser renders the HTML sent to it by the server, along with the CSS.
+- Your app or site doesn't have users, it has **visitors**.
 
 ## Structure of These Documents
 
 Each page here documents on aspect of Brut, called a *module*, and these pages are organized along four sections:
 
-* **Overview** - provides detailed information on how this part of Brut works, with minimal examples to orient you to
-the terms and design of that module.  Links to reference documentation are provided inline as needed.
-* **Testing** - information about how to write tests for the code in this module.  For example, in [Pages](/pages), we detail how you are intended to test page classes.
-* **Recommended Practices** - this section outlines what we believe is the best way to use the module, along with
-justifications for the recommended approach.  While you are free to ignore this advice, it's often useful to
-understand the intention of the authors.
-* **Technical Notes** - where appropriate, technical details about how or why the module works the way it does
-are provided.  This section should be marked with a date to allow you to understand the recency of the
-information. It may not always be up to date, but this can help further clarify what is happening under the
-covers and why.
+* **Overview** - What the module does, how it works, and a brief example.
+* **Testing** - How to test the code you write in this module.
+* **Recommended Practices** - Opinions from the creators about how best to think about the code in this module.
+* **Technical Notes** - details about the technical implementations that may be
+useful as context.
 
 ## Names of the Library and Associated Modules
 
-This framework is called "Brut" though may be called "BrutRB".  It lives at `brutrb.com`.
+This framework is called "Brut" though may be called "BrutRB" or "brut-rp".  It lives at `brutrb.com`.  Never use "brutRB", "brut_rb", etc.
 
 The JavaScript library is called "BrutJS", but is `brut-js` in code or the filesystem. "Brut-JS" is wrong, as is `brut_js`.
 

data/brutrb.com/dx

@@ -0,0 +1 @@
+../dx

data/brutrb.com/end-to-end-tests.md

@@ -55,7 +55,7 @@ RSpec.describe "logging into the website" do
 end
 ```
 
-`playwright-ruby-client` provides excellent documentation on how it has adapter Playwright's API for use
+`playwright-ruby-client` provides excellent documentation on how it has adapted Playwright's API for use
 in Ruby.
 
 ### Test Setup
@@ -70,9 +70,15 @@ jobs, but rather assert the effects those jobs will have. Redis is flushed betwe
 
 Inside your test, `t` is available to produce translations. You can also access all your page and handler classes, so you can (and should) use `.routing`, e.g. `DashboardPage.routing`, to generate or access routes for your app.
 
-You can set `e2e_timeout` on any test to override the default amount of time Playwright will wait for a
+You can set the `e2e_timeout` metadata on any test to override the default amount of time Playwright will wait for a
 locator to locate an element. The default is 5 seconds.
-`, to generate or access routes for your app.
+
+```ruby
+RSpec.describe "Test for login", e2e_timeout: 10 do
+  # ...
+end
+```
+
 You can also configure behavior with environment variables:
 
 | Variable            | Default | Purpose                                                                                           |
@@ -122,12 +128,9 @@ The main Playwright documentation encourages you to locate elements by "accessib
 indirect ways of finding elements.  In practice, this is error prone and tedious.  Determining the
 accessible name of an element is not always easy.
 
-We recommend you assess your app's accssibility in another way than trying to do it while performing
-end-to-end tests.  Instead, locate elements with CSS selectors—this is what you'd use to debug your app so
-it makes sense as a testing technique.
+We recommend you assess your app's accessibility in another way than trying to do it while performing end-to-end tests.  Instead, locate elements with CSS selectors—this is what you'd use to debug your app so it makes sense as a testing technique.
 
-Insulating your end-to-end tests from markup changes does not produce significant savinsg and can make
-tests more difficult to write.
+Insulating your end-to-end tests from markup changes does not produce significant savings and can make tests more difficult to write.
 
 ### Testing Must Inform your HTML
 
@@ -170,5 +173,4 @@ make sure it's still needed.
 
 _Last Updated June 13, 2025_
 
-The test server is run bin `bin/test-server`, which is why Sidekiq will be running when your app is
-running for an e2e test.
+The test server is run via `bin/test-server`.