@webundsoehne/brownie
A CLI that automatically merges the desired skeleton and generates the docker-compose to run on development versions.
Last updated a month ago by ws-admin .
MIT · Repository · Original npm · Tarball · package.json
$ cnpm install @webundsoehne/brownie 
SYNC missed versions from official npm registry.

Web und Söhne - Logo

Web & Söhne is Austrian's leading expert in programming and implementing complex and large web projects.

@webundsoehne/brownie

Version Downloads/week

Description

A CLI that automatically merges the desired skeleton to the current repository and generates the docker-compose to run.js on development versions. It will prompt the user to tailor out a custom configuration.

Navigation

Initial Run as a Client

The default command, brownie, will apply pre-configured changes for a given project by applying the .brownie.lock file that is in the root of the repository. With this command user can only select what optional services to opt in/out off, the rest will be configured according to the project configuration details.

The default command will run:

After Initial Run

Just run brownie to change optional services.

For Pulling Last Skeleton Configuration

You can refresh your configuration using brownie git pull to pull the skeleton repository.

For Reseting Environment Variables Used by Docker-Compose file

You can also use brownie reset env. This will just reset the .env file that is used by the docker-compose configuration, giving a fast way to go back to the defaults.

For Changing Docker Configuration From the Project Configuration

If you desire to change your current docker-compose file with any other configuration, you can run brownie reset docker to rollback to base or optional configuration depending on the .brownie.yml.

This command will undo any changes made by brownie utilizing the lock file. Depending on the last configuration you selected and the configuration file itself you can go back to a base configuration that will remove any additional services and optional services or last known additional service configuration which will remove the optional services.

Adding to a Project

To add brownie to a skeleton you can easily run brownie add project. This will perform all the necessary steps to add it to a project.

The .brownie.yml was supposed to come from the skeleton to be used. But you can also adapt it or recreate it with brownie init:docker if required.

After initial run all the configuration will be saved to .brownie.lock file therefore can be shared through the git for sharing the configuration with all the users.

This is a jumper command that will run:

Adding to a Skeleton

To add brownie to a skeleton you can easily run brownie add skeleton. This will perform all the necessary steps to add it to a skeleton.

Then edit the generated .brownie.yml file compliying to section Brownie Templates.

This is a jumper command that will run:

Brownie Templates

For it to generate docker-compose.yml files automatically, .brownie.yml must exist in the root folder of the project.

This file can be automatically generated through brownie init:docker. This will give freedom to switch docker-compose.yml and tailor the configuration in between multiple options.

Current configuration method includes 3 key points. Base, additional/variable and optional services. Additional to this there is also 2 default keys that are important in the configuration file itself which is header and footer.

The basic architecture is follows. The autogenerated file will have enough comments to guide the way through. This architecture is nested too much at the moment and does not allow complex configurations an alternative but more complex version can be implemented if needed, see here.

.
├── header
├── footer
├── base
│   └── the service itself
│       ├── docker-compose properties
│       └── init-cli properties
└── variable
    ├── base
    │   ├── docker-compose properties
    │   └── init-cli properties
    └── optional
        ├── docker-compose properties
        └── init-cli properties

Default Keys

Header

In header you can add configuration like docker-compose file version, which usually goes at the top of the configuration file.

Footer

In footer you can add configuration like networks, shared volumes, which usually goes at the bottom of the configuration file.

Template Keys

Base

  • Base configuration shall be named with the key base.
  • The services defined inside this key will be automatically added to any configuration without any prompts.
  • Since this will not be prompted to the user, the configuration of the base services shall go directly below the key itself.

Variable/Additional

  • Variable configuration shall be named with the key variable.
  • User can only select one of many additional services.
  • It shall be given a human-readable-name that will appear in the prompt under that it shall be named base for the base of the additional selection and under that it's properties.
  • The user is prompted to select one of these configured services and depending on the variable service optional service can be selected.

Optional

  • Optional configuration will go nested under the adjecent variable key.
  • User can select one or many of optional services.
  • It should be nested directly under the variable service it is adjecent to. It shall also be given a human-readable-name that will appear in the prompt and under that it's properties, but the key base is reserverd for the variable service itself.

Brownie Properties

Under any service, there are special brownie keys nested under init_cli key adjecent to the docker-compose service keys.

init_cli:
├── node:
│   ├── prod:
│   │   └── dependency: version // production dependencies to be installed
│   ├── dev:
│   │   └── dependency: version // development dependencies to be installed
│   └── scripts:
│       └── scriptname: command // scripts to be added to the package.json
├── environment:
│   └── string[] // this will add .env variables to the generated .env file.
├── config:
│   └── Object // merges the entries with the config/default.yml
└── gitlab:
    └── Object // merges the entires with the .gitlab-ci.yml

Manually Editing Files

If you manually edit files, even though brownie will prompt you before overwriting them, please be mindful of data losses, since there is no compare and select functionality implemented while merging the files.

Customizing Configuration

Even though brownie can run without any personalized configuration, you can run brownie config commands to follow through the prompts and create local configurations instead of using the predefined ones in the module.

The repositories used as a skeleton is completely user-configurable using the CLI. It will create a local configuration file instead of using the default one. See brownie config:skeleton.

Missing Features

Currently, some missing features must be implemented for some, not to common and trivial cases. If it can be a problem for the user it will throw a warning to give a heads-up. You can check what is missing at todo section.

Usage

$ yarn global add @webundsoehne/brownie
$ brownie COMMAND
running command...
$ brownie (-v|--version|version)
@webundsoehne/brownie linux-x64 node-v13.7.0
$ brownie help [COMMAND]
USAGE
  $ brownie COMMAND
...

Commands

brownie add

Add brownie to your project or skeleton.

USAGE
  $ brownie add

brownie add:project

Adds brownie to your project.

USAGE
  $ brownie add:project

OPTIONS
  -c, --config=config          [default: .brownie.yml] Config file to use.
  -d, --dump=dump              [default: .gitignore] Output file to write.
  -e, --envfile=envfile        [default: .env] Environment variable file to write
  -f, --force                  Do not prompt for overwrites.
  -n, --no-comment             Disable the comments while writing the yaml file.
  -o, --output=output          [default: docker-compose.yml] Output file to write.
  -r, --remove                 Remove from the file instead of adding.
  -v, --variables=variables    [default: config/default.yml] Skeleton config file to output to.
  --gitlab-ci=gitlab-ci        [default: .gitlab-ci.yml] Gitlab CI/CD file to read and write to.
  --package-json=package-json  [default: package.json] Package json file to work with.

brownie add:skeleton

Adds brownie to a skeleton.

USAGE
  $ brownie add:skeleton

OPTIONS
  -d, --brownie=brownie      [default: .brownie.yml] Output file to write.
  -d, --dump=dump            [default: .gitignore] Output file to write.
  -f, --force                Do not prompt for overwrites.
  -g, --gitignore=gitignore  [default: .gitignore] gitignore file to write.
  -n, --no-comment           Disable the comments while writing the yaml file.
  -r, --remove               Remove from the file instead of adding.

brownie config

Various ways to edit default configuration.

USAGE
  $ brownie config

brownie config:skeleton

Edit available skeletons through a user interface.

USAGE
  $ brownie config:skeleton

brownie docker

Generate the docker-compose configuration from projects .brownie.yml.

USAGE
  $ brownie docker

OPTIONS
  -c, --config=config          [default: .brownie.yml] Config file to use.
  -e, --envfile=envfile        [default: .env] Environment variable file to write
  -f, --force                  Do not prompt for overwrites.
  -o, --output=output          [default: docker-compose.yml] Output file to write.
  -v, --variables=variables    [default: config/default.yml] Skeleton config file to output to.
  --gitlab-ci=gitlab-ci        [default: .gitlab-ci.yml] Gitlab CI/CD file to read and write to.
  --package-json=package-json  [default: package.json] Package json file to work with.

brownie git

Merge skeletons, pull the last configuration using GIT.

USAGE
  $ brownie git

brownie git:merge

Merge existing skeleton with the current repository.

USAGE
  $ brownie git:merge

OPTIONS
  -d, --dump=dump              [default: .gitignore] Output file to write.
  -n, --no-comment             Disable the comments while writing the yaml file.
  -r, --remove                 Remove from the file instead of adding.
  --package-json=package-json  [default: package.json] Package json file to work with.

brownie git:pull

Pull and merge the latest skeleton configuration.

USAGE
  $ brownie git:pull

OPTIONS
  --package-json=package-json  [default: package.json] Package json file to work with.

brownie help [COMMAND]

display help for brownie

USAGE
  $ brownie help [COMMAND]

ARGUMENTS
  COMMAND  command to show help for

OPTIONS
  --all  see all commands in CLI

See code: @oclif/plugin-help

brownie init

Generate default configuration files for this CLI for new repositories.

USAGE
  $ brownie init

brownie init:docker

This command will generate an empty and commented out ".brownie.yml".

USAGE
  $ brownie init:docker

OPTIONS
  -d, --dump=dump   [default: .brownie.yml] Output file to write.
  -f, --force       Do not prompt for overwrites.
  -n, --no-comment  Disable the comments while writing the yaml file.

brownie init:gitignore

Generate gitignore files.

USAGE
  $ brownie init:gitignore

brownie init:gitignore:base

This command will append the files required for CLI to ".gitignore".

USAGE
  $ brownie init:gitignore:base

OPTIONS
  -d, --dump=dump   [default: .gitignore] Output file to write.
  -n, --no-comment  Disable the comments while writing the yaml file.
  -r, --remove      Remove from the file instead of adding.

brownie init:gitignore:skeleton

This command will append the files required for CLI to ".gitignore".

USAGE
  $ brownie init:gitignore:skeleton

OPTIONS
  -d, --dump=dump   [default: .gitignore] Output file to write.
  -n, --no-comment  Disable the comments while writing the yaml file.
  -r, --remove      Remove from the file instead of adding.

brownie reset

Resets the configuration complying with the lock file.

USAGE
  $ brownie reset

brownie reset:docker

Re-select services from ".brownie.yml" from the last configuration.

USAGE
  $ brownie reset:docker

OPTIONS
  -c, --config=config          [default: .brownie.yml] Config file to use.
  -e, --envfile=envfile        [default: .env] Environment variable file to write
  -f, --force                  Do not prompt for overwrites.
  -o, --output=output          [default: docker-compose.yml] Output file to write.
  -v, --variables=variables    [default: config/default.yml] Skeleton config file to output to.
  --gitlab-ci=gitlab-ci        [default: .gitlab-ci.yml] Gitlab CI/CD file to read and write to.
  --package-json=package-json  [default: package.json] Package json file to work with.

brownie reset:env

Re-generate only the .env file from ".brownie.yml" for the last configuration.

USAGE
  $ brownie reset:env

OPTIONS
  -e, --env-file=env-file  [default: .env] Environment variable file to write
  -f, --force              Do not prompt for overwrites.

TODO

Code

General

  • There is a problem with the library calling the index.ts if there is any other command in the folder. This seems to be a bug of the oclif framework itself since it is not very critical at the moment it will be maintained in further revisions.

Performance Considerations

  • There may be an optimization needed on that regard, cold start is a bit slow but that might be do the framework and the nature of node itself.
  • Currently uses around 70-110MB ram in a given task, which is much, but considering an empty cli project in node uses around ~60MB, not sure if can be improved on that number.

Structural Changes

Current configuration does not allow to make complex configurations easy and the .brownie.yml file is nested too much.

A complex configuration example, without any base services and with 2 different additional services. If you want to only add selectable services with no service configured as default, you can do the one below. But the problem is you have to write down the optional service twice, which is undesired.

.
├── header
├── footer
└── variable
    ├── an additional service
    │   └── an optional service
    └── a different additional service
        └── the same optional service

This can be changed in the structure change as follows if desired, but it will introduce more complex parsing of configuration files and breaking changes, and also does not seem applicable at the moment.

.
├── header
├── footer
├── an additional service
│   └── init_cli:
│       ├── type: additional/variable
│       └── optionals: - the optional service
├── another additional service
│   └── init_cli
│       ├── type: additional/variable
│       └── optionals: - the optional service
└── optional service

This kind of structure will also flat out the configuration file as well, which is the desired out way and look more similar to ci/cd configurations which will be relatable.

While speaking of complex configurations another thing that can be added is a dependent injection dependent of the additional and optional service selection.

.
├── header
├── footer
├── base
│   └── init_cli:
│       ├── type: base
│       └── depends_on:
│           └── optional service
│               └── depends_on: optional service
├── an additional service
│   └── init_cli:
│       ├── type: additional/variable
│       └── optionals: - the optional service
└── optional service

The disadvantage of this will be a way more complex and circular way of parsing configuration files, which will introduce breaking changes.

Package Size

Dependencies Size
21 13.47M

Current Tags

  • 0.2.5                                ...           latest (a month ago)

24 Versions

  • 0.2.5                                ...           a month ago
  • 0.2.2                                ...           2 months ago
  • 0.2.1                                ...           3 months ago
  • 0.2.0                                ...           3 months ago
  • 0.1.5                                ...           3 months ago
  • 0.1.4                                ...           3 months ago
  • 0.1.3                                ...           3 months ago
  • 0.1.2                                ...           3 months ago
  • 0.1.1                                ...           3 months ago
  • 0.1.0                                ...           3 months ago
  • 0.0.16                                ...           3 months ago
  • 0.0.15                                ...           3 months ago
  • 0.0.14                                ...           3 months ago
  • 0.0.12                                ...           3 months ago
  • 0.0.11                                ...           3 months ago
  • 0.0.10                                ...           3 months ago
  • 0.0.9                                ...           3 months ago
  • 0.0.8                                ...           3 months ago
  • 0.0.7                                ...           3 months ago
  • 0.0.5                                ...           3 months ago
  • 0.0.4                                ...           3 months ago
  • 0.0.3                                ...           3 months ago
  • 0.0.2                                ...           3 months ago
  • 0.0.1                                ...           3 months ago
Maintainers (2)
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (21)
Dev Dependencies (14)
Dependents (0)
None

Copyright 2014 - 2017 © taobao.org |