brut 0.0.27 → 0.0.29

data/docs/assets/deployment.md.Dbka4OTr.js

@@ -1 +0,0 @@
-import{_ as t,c as o,o as a,ag as i}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"Deployment","description":"","frontmatter":{},"headers":[],"relativePath":"deployment.md","filePath":"deployment.md"}'),n={name:"deployment.md"};function s(r,e,l,d,c,p){return a(),o("div",null,e[0]||(e[0]=[i('<h1 id="deployment" tabindex="-1">Deployment <a class="header-anchor" href="#deployment" aria-label="Permalink to &quot;Deployment&quot;">​</a></h1><p>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.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>Everyone deploys apps in different ways. Brut can&#39;t provide a simple solution for all deployment setups, so this document will outline considerations when setting up deployment.</p><p>The most direct way to understand what needs to happen is to look at <code>deploy/Dockerfile</code>, which is the foundation of a <code>Dockerfile</code> you can use. In particular, it shows you the commands needed to setup and run the app in production:</p><p>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:</p><ol><li>Install Ruby Gems with <code>bundle install</code></li><li>Install Node modules with <code>npm clean-install</code></li><li>Build all assets with <code>bin/build-assets</code> (this will bundle all CSS and Javascript, plus copy over any other <a href="/assets.html">assets</a> to the locations from where the Brut app will serve them)</li><li>Run the app with <code>bin/run</code></li></ol><p>Your Brut app also includes <code>bin/release</code> 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.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>If you are using Docker, you can create the <code>Dockerfile</code>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.</p><p>If you are not using Docker, you will need to apply various techniques that are beyond the scope of this documentation.</p><h2 id="recommended-practices" tabindex="-1">Recommended Practices <a class="header-anchor" href="#recommended-practices" aria-label="Permalink to &quot;Recommended Practices&quot;">​</a></h2><p>Brut goes to great lengths to avoid environment-specific code. Much of Brut&#39;s behavior works the same in dev as it does in production. For example, assets are hashed in all environments.</p><p>Assuming your code does the same thing, there should be a minium of surprises. That all being said, here are some recommendations:</p><ul><li>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.</li><li>Configure observability so you know what your app is doing at all times.</li><li>Configure a URL that, when accessed, produces an error. This allows you to check your error reporting system.</li><li>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.</li></ul>',15)]))}const m=t(n,[["render",s]]);export{u as __pageData,m as default};

data/docs/assets/deployment.md.Dbka4OTr.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as o,o as a,ag as i}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"Deployment","description":"","frontmatter":{},"headers":[],"relativePath":"deployment.md","filePath":"deployment.md"}'),n={name:"deployment.md"};function s(r,e,l,d,c,p){return a(),o("div",null,e[0]||(e[0]=[i("",15)]))}const m=t(n,[["render",s]]);export{u as __pageData,m as default};

data/docs/assets/doc-conventions.md.DCfRXXi-.js

@@ -1 +0,0 @@
-import{_ as t,c as o,o as s,ag as a}from"./chunks/framework.1L-BeKqY.js";const m=JSON.parse('{"title":"Documentation Conventions","description":"","frontmatter":{},"headers":[],"relativePath":"doc-conventions.md","filePath":"doc-conventions.md"}'),r={name:"doc-conventions.md"};function i(n,e,u,d,c,l){return s(),o("div",null,e[0]||(e[0]=[a('<h1 id="documentation-conventions" tabindex="-1">Documentation Conventions <a class="header-anchor" href="#documentation-conventions" aria-label="Permalink to &quot;Documentation Conventions&quot;">​</a></h1><h2 id="terminology" tabindex="-1">Terminology <a class="header-anchor" href="#terminology" aria-label="Permalink to &quot;Terminology&quot;">​</a></h2><p>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 &quot;CSS variables&quot;, rather the term is &quot;custom properties&quot;. HTML entities are <em>elements</em> or <em>tags</em> that have <em>attributes</em>. As another example, HTML doesn&#39;t have <em>validations</em>, rather it as <em>constraints</em>, which can be <em>violated</em>.</p><p>When speaking about Ruby, we prefer the term <em>initializer</em> over constructor, <em>parameters</em> over arguments, and <em>methods</em> over messages. We also prefer <em>tests</em> over specs, however test files <em>are</em> located in <code>specs/</code> and named <code>*.spec.rb</code> to be consistent with RSpec&#39;s nomenclature. We prefer <em>end-to-end</em> or <em>e2e</em> tests instead of browser tests or request specs.</p><p>Further, Brut doesn&#39;t render HTML, it <em>generates</em> it. The browser renders the HTML for the website&#39;s visitor.</p><p>Lastly, the documentation tries to talk about the person accessing a website as a &quot;vistor&quot; not a &quot;user&quot;. Though the &quot;user&quot; nomenclature is near-ossified in software development, we feel &quot;visitor&quot; is more apt.</p><h2 id="structure-of-these-documents" tabindex="-1">Structure of These Documents <a class="header-anchor" href="#structure-of-these-documents" aria-label="Permalink to &quot;Structure of These Documents&quot;">​</a></h2><p>Each page here documents on aspect of Brut, called a <em>module</em>, and these pages are organized along four sections:</p><ul><li><strong>Overview</strong> - 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.</li><li><strong>Testing</strong> - information about how to write tests for the code in this module. For example, in <a href="/pages.html">Pages</a>, we detail how you are intended to test page classes.</li><li><strong>Recommended Practices</strong> - 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&#39;s often useful to understand the intention of the authors.</li><li><strong>Technical Notes</strong> - 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.</li></ul><h2 id="names-of-the-library-and-associated-modules" tabindex="-1">Names of the Library and Associated Modules <a class="header-anchor" href="#names-of-the-library-and-associated-modules" aria-label="Permalink to &quot;Names of the Library and Associated Modules&quot;">​</a></h2><p>This framework is called &quot;Brut&quot; though may be called &quot;BrutRB&quot;. It lives at <code>brutrb.com</code>.</p><p>The JavaScript library is called &quot;BrutJS&quot;, but is <code>brut-js</code> in code or the filesystem. &quot;Brut-JS&quot; is wrong, as is <code>brut_js</code>.</p><p>The CSS library is called &quot;BrutCSS&quot;, but is <code>brut-css</code> in code or the filesystem. &quot;Brut-CSS&quot; is wrong, as is &quot;brut-css&quot;.</p><h2 id="on-using-vitepress" tabindex="-1">On Using VitePress <a class="header-anchor" href="#on-using-vitepress" aria-label="Permalink to &quot;On Using VitePress&quot;">​</a></h2><p>This site is built using <a href="https://vitepress.dev" target="_blank" rel="noreferrer">VitePress</a>, which is a client-side heavy framework. It kinda goes against the ethos of Brut, but it is allowing me to write documentation that looks decent and is mostly navigable. I would like to use a more accessible, customized system for documenting Brut, but for now, it&#39;s more important to get the documentation out. A better documentation experience is planned.</p>',15)]))}const p=t(r,[["render",i]]);export{m as __pageData,p as default};

data/docs/assets/getting-started.md.Bz2s1Vjb.js

@@ -1,2 +0,0 @@
-import{_ as t,c as a,o as i,ag as s}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"Getting Started","description":"","frontmatter":{},"headers":[],"relativePath":"getting-started.md","filePath":"getting-started.md"}'),n={name:"getting-started.md"};function o(p,e,l,r,d,c){return i(),a("div",null,e[0]||(e[0]=[s(`<h1 id="getting-started" tabindex="-1">Getting Started <a class="header-anchor" href="#getting-started" aria-label="Permalink to &quot;Getting Started&quot;">​</a></h1><p>To make a new app with Brut, you&#39;ll need to clone a template app, initialize it, then set up your dev environment.</p><h2 id="clone-the-app-template" tabindex="-1">Clone the App Template <a class="header-anchor" href="#clone-the-app-template" aria-label="Permalink to &quot;Clone the App Template&quot;">​</a></h2><p>To get started, clone the Brut app template:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>&gt; git clone https://github.com/thirdtank/brut-app-template your-app-name</span></span></code></pre></div><h2 id="init-your-app" tabindex="-1">Init Your App <a class="header-anchor" href="#init-your-app" aria-label="Permalink to &quot;Init Your App&quot;">​</a></h2><p>The template includes <code>init</code>, which will ask you a few questions to get everything set up.</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>&gt; cd your-app-name</span></span>
-<span class="line"><span>&gt; ./init</span></span></code></pre></div><p>You&#39;ll need to provide four pieces of info:</p><ul><li>Your app&#39;s name, suitable has a hostname or identifier</li><li>A prefix for your app&#39;s externalizable ids</li><li>A prefix for your app&#39;s custom elements</li><li>An organization name, needed for deployment</li></ul><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>Choose your app&#39;s name wisely, however everything else can be easily changed later, so don&#39;t stress!</p></div><h2 id="set-up-your-dev-environment" tabindex="-1">Set Up Your Dev Environment <a class="header-anchor" href="#set-up-your-dev-environment" aria-label="Permalink to &quot;Set Up Your Dev Environment&quot;">​</a></h2><p>Brut includes a dev environment based on Docker.</p><ol><li><p><a href="https://docs.docker.com/get-started/get-docker/" target="_blank" rel="noreferrer">Install Docker</a></p></li><li><p>Build Your images</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>&gt; dx/build</span></span></code></pre></div></li><li><p>Start up the environment</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>&gt; dx/start</span></span></code></pre></div></li><li><p>Install gems and modules for your app. In another terminal:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>&gt; dx/exec bin/setup</span></span></code></pre></div></li></ol><p>Now, you&#39;re ready to go</p><h2 id="run-the-app" tabindex="-1">Run the App <a class="header-anchor" href="#run-the-app" aria-label="Permalink to &quot;Run the App&quot;">​</a></h2><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>&gt; dx/exec bin/dev</span></span></code></pre></div><p>You can now visit your app at <code>localhost:6502</code></p><h2 id="now-build-the-rest-of-your-app-🦉" tabindex="-1">Now Build The Rest of Your App 🦉 <a class="header-anchor" href="#now-build-the-rest-of-your-app-🦉" aria-label="Permalink to &quot;Now Build The Rest of Your App 🦉&quot;">​</a></h2><p>You can <a href="/tutorial.html">follow the tutorial</a>, check out the <a href="/overview.html">conceptual overview</a>, or dive straight into the API docs.</p>`,20)]))}const g=t(n,[["render",o]]);export{u as __pageData,g as default};

data/docs/assets/getting-started.md.Bz2s1Vjb.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as a,o as i,ag as s}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"Getting Started","description":"","frontmatter":{},"headers":[],"relativePath":"getting-started.md","filePath":"getting-started.md"}'),n={name:"getting-started.md"};function o(p,e,l,r,d,c){return i(),a("div",null,e[0]||(e[0]=[s("",20)]))}const g=t(n,[["render",o]]);export{u as __pageData,g as default};

data/docs/assets/index.md.B28EwVpq.js

@@ -1 +0,0 @@
-import{_ as e,c as t,o as a}from"./chunks/framework.1L-BeKqY.js";const m=JSON.parse(`{"title":"","description":"","frontmatter":{"layout":"home","hero":{"name":"Brut RB","text":"Raw Ruby Web Apps","tagline":"Standards-based, No-nonsense, HTML-first, Low Ceremony","image":{"src":"/images/logo.png","alt":"A Ruby gemstone embedded into a concrete, brutalist building"},"actions":[{"theme":"brand","text":"Brut is Not Yet Released","link":"/not-released"},{"theme":"brand","text":"Getting Started","link":"/getting-started"},{"theme":"alt","text":"Conceptual Overview","link":"/overview"}]},"features":[{"title":"Standards-Based","icon":"📄","details":"Brut leverages HTML, HTTP, SQL, and the Ruby standard library to let you write apps using standards you already know…or could quickly learn"},{"title":"Convention-Oriented","icon":"🎚️","details":"In a Brut app, there's usually just one way to do something. Learn things once, and you won't forget how your app works."},{"title":"Objects and Methods","icon":"💻","details":"Author classes to create objects on which to call methods. Nothing fancy."},{"title":"Builds on Community Libraries","icon":"🏘️","details":"Sequel, Phlex, I18n, RSpec. They do it best"}]},"headers":[],"relativePath":"index.md","filePath":"index.md"}`),n={name:"index.md"};function o(s,i,r,d,l,c){return a(),t("div")}const h=e(n,[["render",o]]);export{m as __pageData,h as default};

data/docs/assets/index.md.B28EwVpq.lean.js

@@ -1 +0,0 @@
-import{_ as e,c as t,o as a}from"./chunks/framework.1L-BeKqY.js";const m=JSON.parse(`{"title":"","description":"","frontmatter":{"layout":"home","hero":{"name":"Brut RB","text":"Raw Ruby Web Apps","tagline":"Standards-based, No-nonsense, HTML-first, Low Ceremony","image":{"src":"/images/logo.png","alt":"A Ruby gemstone embedded into a concrete, brutalist building"},"actions":[{"theme":"brand","text":"Brut is Not Yet Released","link":"/not-released"},{"theme":"brand","text":"Getting Started","link":"/getting-started"},{"theme":"alt","text":"Conceptual Overview","link":"/overview"}]},"features":[{"title":"Standards-Based","icon":"📄","details":"Brut leverages HTML, HTTP, SQL, and the Ruby standard library to let you write apps using standards you already know…or could quickly learn"},{"title":"Convention-Oriented","icon":"🎚️","details":"In a Brut app, there's usually just one way to do something. Learn things once, and you won't forget how your app works."},{"title":"Objects and Methods","icon":"💻","details":"Author classes to create objects on which to call methods. Nothing fancy."},{"title":"Builds on Community Libraries","icon":"🏘️","details":"Sequel, Phlex, I18n, RSpec. They do it best"}]},"headers":[],"relativePath":"index.md","filePath":"index.md"}`),n={name:"index.md"};function o(s,i,r,d,l,c){return a(),t("div")}const h=e(n,[["render",o]]);export{m as __pageData,h as default};

data/docs/assets/overview.md.CDalkuxV.lean.js

@@ -1 +0,0 @@
-import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.1L-BeKqY.js";const n="/assets/overview.Da81cB9R.png",g=JSON.parse('{"title":"Conceptual Overview","description":"","frontmatter":{},"headers":[],"relativePath":"overview.md","filePath":"overview.md"}'),l={name:"overview.md"};function h(p,s,r,d,o,k){return e(),a("div",null,s[0]||(s[0]=[t("",79)]))}const E=i(l,[["render",h]]);export{g as __pageData,E as default};