log4brains
Advanced tools
Log4brains is a docs-as-code knowledge base for your development and infrastructure projects. It enables you to log Architecture Decision Records (ADR) right from your IDE and to publish them automatically as a static website.
By logging your decisions chronologically, you will be able to:
adr-0001.md, adr-0002.md...): avoids git merge issuesComing soon:
@adr annotation to include code references in ADRs
⚡ Demo: Log4brains' own architecture knowledge base
We recommend to store your Architecture Decision Records (ADR) next to the source code of your project, in the same git repository, to keep them in sync.
To get started, run these commands inside your project root folder:
npm install -g log4brains
log4brains init
It will ask you several questions to get Log4brains properly configured. It will also create the required template files and your first ADR as well. Then, you can start the web UI to preview your knowledge base locally:
log4brains preview
In this mode, the Hot Reload feature is enabled: any change you make to a markdown file from your IDE is applied live.
To create a new ADR from your template, run this command:
log4brains adr new
Get all the available commands and options by running log4brains --help.
Finally, do not forget to set up your CI/CD pipeline to automatically publish your knowledge base on a static website service like GitHub/GitLab Pages or S3.
The term ADR became popular in 2011 with Michael Nygard's article: documenting architecture decisions. He aimed to reconcile Agile methods with software documentation by creating a very concise template to record functional or non-functional "architecturally significant" decisions in a lightweight format like markdown. The original template had only a few parts:
There are other ADR templates like Y-Statements or MADR, which is the default one that is shipped with Log4brains.
As you can guess from the template above, an ADR is immutable. Only its status can change. Thanks to this, your documentation is never out-of-date! Yes, an ADR can be deprecated or superseded by another one, but it was at least true one day! And even if it's not the case anymore, it is still a precious piece of information.
This leads us to the main goals of this methodology:
To learn more on this topic, I recommend you to read these great resources:
Log4brains lets you publish automatically your knowledge base on the static hosting service of your choice, thanks to the log4brains-web build command.
Here are some configuration examples for the most common hosting services / CI runners.
First, create .github/workflows/publish-log4brains.yml and adapt it to your case:
name: Publish Log4brains
on:
push:
branches:
- master
jobs:
build-and-publish:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2.3.4
with:
persist-credentials: false # required by JamesIves/github-pages-deploy-action
fetch-depth: 0 # required by Log4brains to work correctly (needs the whole Git history)
- name: Install Node
uses: actions/setup-node@v1
with:
node-version: "14"
- name: Install and Build Log4brains
run: |
npm install -g log4brains
log4brains build --basePath /${GITHUB_REPOSITORY#*/}/log4brains
- name: Deploy
uses: JamesIves/github-pages-deploy-action@3.7.1
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
BRANCH: gh-pages
FOLDER: .log4brains/out
TARGET_FOLDER: log4brains
After the first run, this workflow will create a gh-pages branch in your repository containing the generated static files to serve.
Then, we have to tell GitHub that we don't want to use Jekyll, otherwise, you will get a 404 error:
git checkout gh-pages
touch .nojekyll
git add .nojekyll
git commit -m "Add .nojekyll for Log4brains"
git push
Finally, you can enable your GitHub page:
Settings > GitHub Pagesgh-pages branch as the "Source"/ (root) folderYou should now be able to see your knowledge base at https://<username>.github.io/<repository>/log4brains/.
It will be re-built and published every time you push on master.
Create your .gitlab-ci.yml and adapt it to your case:
image: node:14-alpine3.12
pages:
stage: deploy
variables:
GIT_DEPTH: 0 # required by Log4brains to work correctly (needs the whole Git history)
script:
- mkdir -p public
- npm install -g log4brains
- log4brains build --basePath /$CI_PROJECT_NAME/log4brains --out public/log4brains
artifacts:
paths:
- public
rules:
- if: "$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH"
You should now be able to see your knowledge base at https://<username>.gitlab.io/<repository>/log4brains/.
It will be re-built and published every time you push on master.
First, create a bucket with the "Static website hosting" feature enabled:
# This is an example: replace with the bucket name of your choice
export BUCKET_NAME=yourcompany-yourproject-log4brains
aws s3api create-bucket --acl public-read --bucket ${BUCKET_NAME}
read -r -d '' BUCKET_POLICY << EOP
{
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::${BUCKET_NAME}/*"
}
]
}
EOP
aws s3api put-bucket-policy --bucket ${BUCKET_NAME} --policy "$BUCKET_POLICY"
aws s3 website s3://${BUCKET_NAME} --index-document index.html
Then, configure your CI to run these commands:
npm install -g log4brainslog4brains buildaws s3 sync .log4brains/out s3://<YOUR BUCKET> --deleteYour knowledge base will be available on http://<YOUR BUCKET>.s3-website-<YOUR REGION>.amazonaws.com/.
You can get some inspiration on implementing this workflow for GitHub Actions or GitLab CI by looking at the previous examples.
Finally, you can add the ADR badge to your README.md!
| [](http://URL-of-your-knowledge-base/) |
Of course not! Log4brains is developed with TypeScript and use NPM as a package manager. You need Node and NPM to be installed globally to run Log4brains, but it is designed to work for all kind of projects.
Log4brains supports both mono and multi packages projects. The log4brains init command will prompt you regarding this.
In the case of a multi-package project, you have two options:
docs/adr and "package-specific ADRs", for example in packages/<package name>/docs/adr.Here is an example of a typical file structure for each case:
project-root
├── docs
| └── adr
| ├── 20200101-your-first-adr.md
| ├── 20200115-your-second-adr.md
| ├── [...]
| ├── index.md
| └── template.md
[...]
project-root
├── docs
| └── adr
| ├── 20200101-your-first-global-adr.md
| ├── 20200115-your-second-global-adr.md
| ├── [...]
| ├── index.md
| └── template.md
├── packages
| ├── package1
| | ├── docs
| | | └── adr
| | | ├── 20200102-your-first-package-specific-adr.md
| | | ├── 20200116-your-second-package-specific-adr.md
| | | [...]
| | [...]
| ├── package2
| | ├── docs
| | | └── adr
| | | ├── [...]
| | | [...]
| | [...]
| [...]
[...]
For the moment in one central repository (specific for the docs, or not):
project-docs
├── adr
| ├── global
| | ├── 20200101-your-first-global-adr.md
| | ├── 20200115-your-second-global-adr.md
| | ├── [...]
| | ├── index.md
| | └── template.md
| ├── package1
| | ├── 20200102-your-first-package-specific-adr.md
| | ├── 20200116-your-second-package-specific-adr.md
| | [...]
| ├── package2
| | ├── [...]
| | [...]
| [...]
[...]
In the future:
project-docs
├── adr
| ├── 20200101-your-first-global-adr.md
| ├── 20200115-your-second-global-adr.md
| ├── [...]
| ├── index.md
| └── template.md
[...]
repo1
├── docs
| └── adr
| ├── 20200102-your-first-package-specific-adr.md
| ├── 20200116-your-second-package-specific-adr.md
| [...]
[...]
repo2
├── docs
| └── adr
| ├── [...]
| [...]
[...]
.log4brains.yml?This file is automatically created when you run log4brains init (cf getting started), but you may need to configure it manually.
Here is an example with just the required fields:
project:
name: Foo Bar # The name that should be displayed in the UI
tz: Europe/Paris # The timezone that you use for the dates in your ADR files
adrFolder: ./docs/adr # The location of your ADR files
If you have multiple packages in your project, you may want to support package-specific ADRs by setting the optional project.packages field:
project:
# [...]
packages:
- name: backend # The name (unique identifier) of the package
path: ./packages/backend # The location of its codebase
adrFolder: ./packages/backend/docs/adr # The location of its ADR files
# - ...
Another optional field is project.repository, which is normally automatically guessed by Log4brains to create links to GitHub, GitLab, etc. But in some cases, like for GitHub or GitLab enterprise, you have to configure it manually:
project:
# [...]
repository:
url: https://github.com/foo/bar # Absolute URL of your repository
provider: github # Supported providers: github, gitlab, bitbucket. Use `generic` if yours is not supported
viewFileUriPattern: /blob/%branch/%path # Only required for `generic` providers
At this stage, Log4brains is just a few months old and was designed only based on my needs and my past experiences with ADRs. But I am convinced that this project can benefit a lot of teams. This is why it would be precious for me to get your feedback on this beta version in order to improve it.
To do so, you are very welcome to create a new feedback in the Discussions or to reach out to me at thomvaill@bluebricks.dev. Thanks a lot 🙏
Disclaimer: during the beta, some releases can introduce breaking changes without any warning.
Compatibility issues: the project is heavily tested on Ubuntu / Google Chrome environments; It should also work on Windows, macOS and other browsers, but since this is a beta version, some bugs can occur. Please raise an issue if you encounter some!
Pull Requests are more than welcome! Please read CONTRIBUTING.md for more details. You can also create a new issue or give your feedback.
#NEXTJS-HACK in the code to see the custom adaptations we had to make)This project is licensed under the Apache 2.0 license, Copyright (c) 2020 Thomas Vaillant. See the LICENSE file for more information.
1.0.0-beta.8 (2021-01-20)
FAQs
Log and publish your architecture decisions (ADR) with Log4brains
The npm package log4brains receives a total of 3,547 weekly downloads. As such, log4brains popularity was classified as popular.
We found that log4brains demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.