brut 0.14.0 → 0.16.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6954b7b2b7dd919d891eb6ee7a734e3c4279f7781eeb899c88ac80982662ba6
-  data.tar.gz: b02e176ae104ab3214d52877f13a81e17fa32c4de53d57c5bbe193cd9209f9ad
+  metadata.gz: 98447eff97921a8aeb30a9ffa801452a97c8f46a6169e300f6792582c6af191c
+  data.tar.gz: 3040a27ce2283e967f0f0bac694cb0a4fcaa7c7c0bd1bb2c52246dea9dcc2ba5
 SHA512:
-  metadata.gz: a7f6684baab276fcaab1db9eee5427c9e79d5e50a09032bcaf4e417dbee109fa0c4b77322884304a13310ae6b013fbd23d880b1928c83f1a5db627bb09f403b9
-  data.tar.gz: db5de2626cdeabe12ce571fd046c0472a5295d8831684c9a95b4e2b251f59217c7ec7e5de9ae5c473a2ead812d675d76de1d8e38730dbe4cca7e960bf8cf3839
+  metadata.gz: 834e282f6c08942742733de34e04b9b4ada8cf03bbff02b6604fe54a49af28d1fdebe9da173b852e49f29ab87562335495fc9b6846a0b3a6184aa833677908d1
+  data.tar.gz: 9d41d53d28c12e4d5a99ab81490f10c5e0ccb4f6158c1c1dee51ba5321e3d1e92c04e5e1d566815319dea20bc0071662da174c4d930e84d7a30510da1a382cca

data/.gitignore

@@ -31,6 +31,8 @@
 /brut-js/node_modules
 /brut-js/docs/node_modules
 /brut-css/node_modules
+# Configured location for npm install -g
+/.npm-global
 
 # This is where the bundle is built during testing for BuildJS
 /brut-js/specs/public/js

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Brut CHANGELOG
 
+## v0.16.0.pre - Sep 29, 2025
+
+* Sidekiq support - this may have some churn in various config files that only reveal themselves on deploy so this
+  is a pre-release. Do not use this version.
+
+## v0.15.0 - Sep 16, 2025
+
+* Added `<brut-toast>` to help with toast notifications.  They rely on CSS for showing, hiding, and animations, all your
+  client-side JS needs to do is set the `key` attribute to show the Toast with an i18n-provided message
+
 ## v0.14.0 - Sep 9, 2025
 
 * **BREAKING CHANGE** Layouts now have access to the page object they are 

data/Dockerfile.dx

@@ -37,6 +37,9 @@ ENV EDITOR=vim
 RUN apt-get install -y vim && \
     echo "set -o vi" >> /root/.bashrc
 
+# Install NodeJS
+COPY --from=node:22-slim /usr/local /usr/local
+
 
 # Setup a non-root user
 
@@ -70,12 +73,6 @@ COPY --chown=appuser:${user_gid} dx/bash_customizations.local /home/appuser/.bas
 # ONLY in that group and not in all the groups in which they are a part.
 USER appuser
 
-# Install NodeJS, per https://nodejs.org/en/download
-RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash && \
-    \. "$HOME/.nvm/nvm.sh" && \
-    nvm install 22 && \
-    node -v && nvm current && npm -v
-
 # Node's colors are hand-crafted to always look bad and render at least some text unreadable 
 # no matter what your setup. Cool.
 ENV NODE_DISABLE_COLORS=1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brut (0.14.0)
+    brut (0.16.0.pre)
       concurrent-ruby
       i18n
       irb

data/brut-css/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "brut-css",
-  "version": "0.14.0",
+  "version": "0.16.0.pre",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "brut-css",
-      "version": "0.14.0",
+      "version": "0.16.0.pre",
       "license": "Hippocratic-2.1",
       "devDependencies": {
         "comment-parser": "^1.4.1",

data/brut-css/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brut-css",
-  "version": "0.14.0",
+  "version": "0.16.0.pre",
   "description": "Utility CSS Library for Full Stack Developers",
   "keywords": [
     "css"

data/brut-js/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "brut-js",
-  "version": "0.14.0",
+  "version": "0.16.0.pre",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "brut-js",
-      "version": "0.14.0",
+      "version": "0.16.0.pre",
       "license": "Hippocratic-2.1",
       "devDependencies": {
         "esbuild": "^0.24.2",

data/brut-js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brut-js",
-  "version": "0.14.0",
+  "version": "0.16.0.pre",
   "type": "module",
   "keywords": [
     "WebComponents",

data/brut-js/specs/Toast.spec.js

@@ -0,0 +1,34 @@
+import { withHTML } from "./SpecHelper.js"
+
+describe("<brut-toast>", () => {
+  withHTML(`
+    <div>
+     <brut-i18n-translation key="toast.saved" value="Save successful"></brut-i18n-translation>
+     <brut-toast show-warnings>
+       <div>
+         <output><span>Message here</span></output>
+         <button>Close</button>
+       </div>
+       <button>Close</button>
+     </brut-toast>
+   </div>
+  `).test("setting the key shows the message, then it's removed when closed", ({window,document,assert}) => {
+
+    const toast = document.querySelector("brut-toast")
+    assert(toast, "brut-toast element should be present")
+
+    toast.setAttribute("key", "toast.saved")
+    const output = toast.querySelector("output")
+    assert.equal(output.textContent.trim(), "Save successful")
+    const message = output.querySelector("brut-message")
+    assert(message, "brut-message should be present")
+    console.log(message.outerHTML)
+    assert.equal(message.getAttribute("role"), "status")
+    assert.equal(message.getAttribute("aria-live"), "polite")
+    assert.equal(message.getAttribute("aria-atomic"), "true")
+
+    const button = toast.querySelector("button")
+    button.click()
+    assert.equal(toast.getAttribute("key"), null)
+  })
+})

data/brut-js/src/I18nTranslation.js

@@ -49,6 +49,9 @@ class I18nTranslation extends BaseCustomElement {
    * }
    */
   translation(interpolatedValues) {
+    if (!this.#value) {
+      this.logger.warn("No value attribute for key '%s', so translation will be blank", this.#key)
+    }
     return this.#value.replaceAll(/%\{([^}%]+)\}/g, (match,key) => {
       if (interpolatedValues[key]) {
         return interpolatedValues[key]

data/brut-js/src/Message.js

@@ -23,10 +23,16 @@ class Message extends BaseCustomElement {
     "key",
   ]
 
+  /*
+   * Creates a new `<brut-message>` element with the given attributes.
+   */
   static createElement(document,attributes) {
     const element = document.createElement(Message.tagName)
-    element.setAttribute("key",attributes.key)
-    element.setAttribute("show-warnings",attributes["show-warnings"])
+    Object.entries(attributes).forEach(([name,value]) => {
+      if (value !== null && value !== undefined) {
+        element.setAttribute(name,value)
+      }
+    })
     return element
   }
 
@@ -49,7 +55,7 @@ class Message extends BaseCustomElement {
       return
     }
 
-    this.textContent = RichString.fromString(translation.translation()).capitalize().toString()
+    this.textContent = RichString.fromString(translation.translation(), {allowBlank: true }).capitalize().toString()
   }
 }
 

data/brut-js/src/RichString.js

@@ -13,10 +13,13 @@ class RichString {
    *
    * @param {null|undefined|String|RichString} possiblyDefinedStringOrRichString - if `null`, `undefined`, or otherwise falsey, this method returns `null`. If a String, returns a new `RichString` wrapping it. If a `RichString`, returns the `RichString` unchanged.
    */
-  static fromString(possiblyDefinedStringOrRichString) {
+  static fromString(possiblyDefinedStringOrRichString, {allowBlank=false} = {}) {
     if (possiblyDefinedStringOrRichString instanceof RichString) {
       return possiblyDefinedStringOrRichString
     }
+    if (allowBlank && possiblyDefinedStringOrRichString === "") {
+      return new RichString("")
+    }
     if (!possiblyDefinedStringOrRichString) {
       return null
     }

data/brut-js/src/Toast.js

@@ -0,0 +1,102 @@
+import { BaseCustomElement, RichString, Message } from "brut-js"
+
+/**
+ * Support for a toast component, which is a momentary message shown to the user, for example
+ * if an aynchronous update has occured.
+ *
+ * To use this element, you should set up your CSS so that the element is hidden if there is no `key`
+ * attribute set.  When the `key` attribute *is* set, the element should be shown.  You can use CSS animations
+ * for this as needed, but the main thing to remember is that, without a `key` attribute, this element
+ * should not be visible.
+ *
+ * The `key` attribute is expected to be an i18n key that references a `<brut-i18n-message>` on
+ * the page, which contains the actual message to show the visitor.  When the `key` attribute is
+ * set, this component will find an `<output>` inside itself, and replace the entire contents
+ * with a `<brut-message>` component, using the same `key`.  This will cause the `<brut-message>`
+ * to look up the key and put that text into the element.
+ *
+ * In addition to this lookup, this element will set appropriate ARIA attributes on the
+ * created `<brut-message>` element.
+ *
+ * Further, if there is a `<button>` inside this element, it will be used to close the toast by removing the
+ * `key` attribute (which, assuming your CSS is correct, will hide the element).
+ *
+ * @property {string} key - an I18n key of the message to show in the toast.  When you generate
+ *                          the toast's HTML on the server, do not set key.  Then, when you need
+ *                          to display the toast, use JavaScript to set the key. This will
+ *                          trigger its behavior as described above.
+ *
+ * @example
+ * <style>
+ *   brut-toast {
+ *     display: none;
+ *   }
+ *   brut-toast[key] {
+ *     display: block;
+ *   }
+ * </style>
+ * <brut-i18n-translation key="toast.saved">Save successful</brut-i18n-translation>
+ * <brut-toast>
+ *   <div>
+ *   <output></output>
+ *   <button>Close</button>
+ *   </div>
+ * </brut-toast>
+ * <!-- now, if you set the key to "toast.saved", the HTML will be changed as follows: -->
+ * <brut-toast key="toast.saved">
+ *   <div>
+ *   <output>
+ *     <brut-message key="toast.saved" role="status" aria-live="polite" aria-atomic="true">
+ *       Save successful
+ *     </brut-message>
+ *   </output>
+ *   <button>Close</button>
+ *   </div>
+ * </brut-toast>
+ */
+class Toast extends BaseCustomElement {
+  static tagName = "brut-toast"
+
+  static observedAttributes = [
+    "show-warnings",
+    "key",
+  ]
+
+  #key = null
+  #closeListener = (event) => {
+    event.preventDefault()
+    this.removeAttribute("key")
+  }
+
+  keyChangedCallback({newValue}) {
+    this.#key = RichString.fromString(newValue)
+  }
+
+  update() {
+    const closeButton = this.querySelector("button")
+
+    if (closeButton) {
+      closeButton.addEventListener("click", this.#closeListener)
+    }
+
+    if (!this.#key) {
+      return
+    }
+    const output = this.querySelector("output")
+    if (!output) {
+      this.logger.warn("No <output> element found, so toast will not be displayed")
+      return
+    }
+    const messageNode = Message.createElement(document,{
+      "key": this.#key,
+      "role": "status",
+      "aria-live": "polite",
+      "aria-atomic": "true"
+    })
+    output.replaceChildren(messageNode)
+    this.style.animation = "none"
+    this.offsetWidth // Trigger reflow to restart the animation
+    this.style.animation = ""
+  }
+}
+export default Toast

data/brut-js/src/index.js

@@ -12,6 +12,7 @@ import LocaleDetection             from "./LocaleDetection"
 import Message                     from "./Message"
 import RichString                  from "./RichString"
 import Tabs                        from "./Tabs"
+import Toast                       from "./Toast"
 import Tracing                     from "./Tracing"
 
 /**
@@ -105,6 +106,7 @@ BrutCustomElements.addElementClasses(
   AjaxSubmit,
   ConstraintViolationMessage,
   Tabs,
+  Toast,
   LocaleDetection,
   Autosubmit,
   Tracing,
@@ -125,6 +127,7 @@ export {
   Message,
   RichString,
   Tabs,
+  Toast,
   Tracing
 }
 

data/brutrb.com/.vitepress/config.mjs

@@ -129,12 +129,13 @@ export default defineConfig({
         text: "Recipes",
         collapsed: true,
         items: [
-          { text: "Migration Basics", link: "/recipes/migrations" },
-          { text: "Styling Form Errors", link: "/recipes/form-errors" },
-          { text: "Authentication", link: "/recipes/authentication" },
           { text: "Alternate Layouts", link: "/recipes/alternate-layouts" },
+          { text: "Authentication", link: "/recipes/authentication" },
           { text: "Custom Flash Class", link: "/recipes/custom-flash" },
           { text: "Indexed Form Elements", link: "/recipes/indexed-forms" },
+          { text: "Managing Secrets in the Dev Environment", link: "/recipes/dev-env-secrets" },
+          { text: "Migration Basics", link: "/recipes/migrations" },
+          { text: "Styling Form Errors", link: "/recipes/form-errors" },
           { text: "Text Field Component", link: "/recipes/text-field-component" },
         ],
       },

data/brutrb.com/brut-js.md

@@ -52,6 +52,7 @@ of what each one does.
 | `<brut-locale-detection>`    | Sends an Ajax request to the server with the browser's reported locale and timezone.  See [space-time continuum](/space-time-continuum#getting-timezone-from-the-browser) for more details.        |
 | `<brut-message>`             | Shows a message using an [i18n](/i18n) key to dynamically pull a localized message for client-side constraint violations. |
 | `<brut-tabs>`                | Uses ARIA roles related to a tab control and implements it client-side. |
+| `<brut-toast>`               | Support for managing i18-capable [toast notifications](https://en.wikipedia.org/wiki/Pop-up_notification) |
 | `<brut-tracing>`             | Sends observability data back to the server to unify a server-side request with client-side tracing.|
 
 > [!NOTE]

data/brutrb.com/deployment.md

@@ -22,30 +22,45 @@ When creating your Brut app with `mkbrut`, the Heroku segment can be used to cre
 
 How to deploy:
 
-1. Auth to Heroku from inside your dev container:
+1. Get an auth token from Heroku, which you can do from inside the container, and save it to
+   `bash_customizations.local`:
 
    ```
    your-computer> dx/exec bash
    devcontainer> heroku auth:login
    # You will need to copy/paste the URL to log in
-   devcontainer> heroku container:login
+   devcontainer> heroku authorizations:create -d "container pushes" --expires-in 31536000
+   # Copy the token output by this command
+   devcontainer> echo "HEROKU_API_KEY=«TOKEN YOU COPIED»" >> dx/bash_customizations.local
    ```
+2. Exit the devcontainer and  stop `dx/start` (e.g. hit `Ctrl-C` wherever you ran it)
+3. Rebuild and restart the devcontainer (this will set `HEROKU_API_KEY` for you)
 
-2. Create your app using the container stack:
+   ```
+   your-computer> dx/build
+   your-computer> dx/start
+   # In another terminal window
+   your-computer> dx/exec bash
+   devcontainer> echo $HEROKU_API_KEY
+   # You should see the token
+   ```
+
+   Setting this environment variable avoids having to constantly re-authenticate to Heroku.
+
+4. 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`
+5. Ensure your app's source code is all checked in, there are no uncommitted or unadded files, and you have pushed to the `main` branch of your remote Git repository.
+6. `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:
+* 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 do based on what you already 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
@@ -106,7 +121,6 @@ some options for debugging issues:
   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:

data/brutrb.com/jobs.md

@@ -1,14 +1,114 @@
 # Background Jobs
 
-Brut provides little direct support for background jobs. Currently, Brut recommends Sidekiq, since it is
-battle-tested, well-supported, and open source.
+Brut ships without any background job system, however it should work with any system you'd like to use.  Brut
+can install/configure Sidekiq for you, however you are expected to understand Sidekiq in order to use it.
 
-When you set up your Brut app, it should ask if you want Sidekiq support and add the necessary configuraiton.
+## Setting up Sidekiq
 
-It will expect jobs in `app/src/back_end/jobs`.
+Brut's code-generation system used for installing capabilities are called *segments*, and Brut provides a
+Sidekiq segment you can use to get an initial working setup of Sidekiq in your Brut app.
 
-> [!WARNING]
-> The way Sidekiq is configured with Brut is effective and reliable, but it is complex.  It currently
-> involves several moving parts to make it work properly.  This will be an area for improvement.
+### Adding the Segment
 
+1. Ensure your project files are all committed. This is so you can easily see (and, if needed, undo) the
+   changes `mkbrut` will make.
+2. Use `mkbrut` to add the segment:
 
+   ```
+   docker run \
+          --pull always \
+          -v "$PWD":"$PWD" \
+          -w "$PWD" \
+          -u $(id -u):$(id -g) \
+          -it \
+          thirdtank/mkbrut \
+          mkbrut add-segment -r /path/to/your/project sidekiq
+   ```
+3. This will modify and create various files in your project. Check them out if you like:
+
+   ```
+   > git status
+   ```
+4. Exit your dev environment (i.e. hit `Ctrl-C` wherever you ran `dx/start`).
+5. Rebuild and restart your dev environment. This may take a moment, since Valkey will be downloaded.
+
+   ```
+   your-computer> dx/build
+   your-computer> dx/start
+   ```
+6. In another Terminal, connect to your dev container and run `bin/setup`
+
+   ```
+   your-computer> dx/exec bash
+   devcontainer> bin/setup
+   ```
+7. The segment provides an integration test that will use the actual Sidekiq server and client, running
+   against the actual Valkey database that was installed:
+
+   ```
+   devcontainer> bin/test e2e specs/integration/sidekiq_works.spec.rb
+   ```
+
+If this test passes, you are ready to go.
+
+### Using Sidekiq in Brut
+
+Jobs live in `app/src/back_end/jobs`, however this is just a convention and is not enforced - you can place a
+job anywhere that Zeitwerk will find the class.  Brut also provides basic configuration and a base job.
+
+| File | Purpose|
+|------|--------|
+| `app/config/sidekiq.yml` | Standard configuration for Sidekiq |
+| `app/src/back-end/jobs/app_job.r` | Base class for your jobs that includes `Sidekiq::Job` |
+| `app/src/back-end/segments/sidekiq_segment.rb` | Initial client and server configuration for Sidekiq (that you can't do with `sidekiq.yml`. This sets up basic observability for your jobs |
+
+### Accessing the Web UI
+
+The Sidekiq segment mounts the Sidekiq Web UI to your app inside `config.ru`:
+
+```ruby
+# ...
+map "/sidekiq" do
+  use Rack::Auth::Basic, "Sidekiq" do |username, password|
+    [username, password] == [ENV.fetch("SIDEKIQ_BASIC_AUTH_USER"), ENV.fetch("SIDEKIQ_BASIC_AUTH_PASSWORD")]
+  end
+  run Sidekiq::Web.new
+end
+# ...
+```
+
+Values for `SIDEKIQ_BASIC_AUTH_USER` and `SIDEKIQ_BASIC_AUTH_PASSWORD` for dev and test are placed into
+`.env.development` and `.env.test`, respectively. You must provide these values for production, based on
+however you are managing environment variables.
+
+Once you start the app, navigat to `http://localhost:6502/sidekiq` and enter the username/password from
+`.env.development`. You should see the web UI.
+
+### Deploying with The Heroku Segment
+
+If you have set up [Heroku Container-based Deployment](/deployment.md#heroku-container-based-deployment), you
+may need to modify `deploy/heroku_config.rb`.  The Sidekiq segement should have edited this, however if you
+installed the Heroku segment after setting up Sidekiq, you'll need to add to the file:
+
+```ruby [2-6]
+class HerokuConfig
+  def self.additional_images
+    {
+      "sidekiq" => {
+        cmd: "bin/run-sidekiq",
+      }
+    }
+  end
+end
+```
+
+## Setting Up Other Job Systems
+
+To use another job system, you'll likely want to start with `app/src/app.rb`.  You can place all your
+initialize code in `#boot!` to get things working, then factor it out from there.  `App`, the class in that
+file, is a normal class, so you can extract your setup to other normal classes and bring them in as you would
+in any other Ruby app.
+
+Just note that `App`'s `initialize` method should avoid making network connections, so while you are safe to
+create objects and configuration here, do not connect to databases or anything like that.  You *can* do that
+inside `boot!`.

data/brutrb.com/recipes/dev-env-secrets.md

@@ -0,0 +1,87 @@
+# Managing Secrets in the Dev Environment
+
+Often, you need API keys like GitHub or Heroku tokens in order to perform development tasks. These should not be checked into version
+control, however you can still manage them.
+
+## Feature - API Keys
+
+* Developers need do use the Heroku command-line app inside the dev container.
+* Develoeprs do not want to have to perform a daily, browser-based authentication via `heroku auth:login`
+
+### Recipe
+
+The file `dx/bash_customizations.local` is set up for exactly this.  It is not checked into version control (see your `.gitignore`), and it
+is included when the development environment is built.
+
+```bash
+# dx/bash_customizations.local
+HEROKU_API_KEY=xxxxxx
+```
+
+When you change this file, you must rebuild your dev environment:
+
+1. `Ctrl-C` wherever you ran `dx/start`
+2. `dx/build`
+3. `dx/start`
+4. `dx/exec bash`, then `bin/setup`, then continue where you left off
+
+#### How This Works
+
+Here is a snippet of how this works.  In the first `RUN` directlive, the non-root user is created. When that is completed, `~/.profile` and
+`~/.bashrc` are modified to source both `bash_customizations` (per-project customizations that should **not** contain secrets) and
+`bash_customizations.local`, which is the file we are discussing.
+
+After that, the files are copied into the image via the `COPY` directives.
+
+```dockerfile
+# Snippet from Dockerfile.dx
+RUN useradd --uid ${user_uid} --gid ${user_gid} --groups ${sadly_user_must_be_added_to_root}${docker_gid} --create-home --home-dir /home/appuser appuser && \
+    echo ". ~/.bash_customizations" >> /home/appuser/.profile && \
+    echo ". ~/.bash_customizations.local" >> /home/appuser/.profile && \
+    echo ". ~/.bash_customizations" >> /home/appuser/.bashrc && \
+    echo ". ~/.bash_customizations.local" >> /home/appuser/.bashrc
+
+COPY --chown=appuser:${user_gid} dx/show-help-in-app-container-then-wait.sh /home/appuser
+COPY --chown=appuser:${user_gid} dx/bash_customizations /home/appuser/.bash_customizations
+COPY --chown=appuser:${user_gid} dx/bash_customizations.local /home/appuser/.bash_customizations.local
+```
+
+> [!WARNING]
+> The resulting image **will** contain the secrets from `bash_customizations.local`, so it's
+> **very important** you never push that image to a regsitry.
+
+## Feature - SSH Keys
+
+* You need an SSH key in order to push to GitHub from the dev container
+* You do not want to creata new key every time
+
+### Recipe
+
+Ultimately, you want the SSH key to be copied into the container and set up as if you'd created the key there.  The recipe below is an
+example of how you could do this, and should demonstrate the various seams in Brut's dev environment to allow you to craft it how you like.
+
+1. Choose a directory in the project where each developer will store their keys. **This directory should be excluded from version control**
+
+   ```
+   mkdir dx/credentials
+   echo "/dx/credetials" >> .gitignore
+   ```
+
+2. Assuming you create an SSH key already, place `id_ed25519` (private key) and `id_ed25519.pub` (public key) into `dx/credentials`.
+3. Create `dx/credentials/known_hosts` using `id_ed25519.pub`:
+
+   ```
+   github.com ssh-ed25519 «key from id_ed25519.pub here»
+   ```
+4. Your dev container will have access to `dx/credentials` already, so you can use `bin/setup` to copy them to the right place. How
+   you do this depends on how complicated you want to get.  You can examine Brut's `bin/setup` to see how it manages it.  You will
+   see that ti uses `ssh-agent` to avoid requiring the passcode every time, and that it uses `chmod` to make sure the SSH
+   directories are the right permissions.
+
+> [!WARNING]
+> The resulting image **will** contain your SSH key, so it's
+> **very important** you never push that image to a regsitry.
+
+
+This recipe is scant on details, since each credential is highly specific. The key points to know are that you can store information in the
+project, but not checked in, then rely on that information being available to `bin/setup` inside the container.