search

go-fed / apcore

Golang ActivityPub Server Framework
GNU Affero General Public License v3.0
104 stars 10 forks source link

Improve CLI + Example installation experience #56

Open aschrijver opened 3 years ago

aschrijver commented 3 years ago

Based on my apcore installation experience I created a list of possible CLI improvements, on which feedback / discussion is needed.

  1. Separate into a normal and an advanced installation flow
  2. Discern between script output and application logging ('verbose' mode)
  3. Put all default values between brackets (similar to [y/N])
  4. More automation of installation process
  5. Bootstrap vs. example?
  6. Separating for 'Debug' vs. 'Prod' mode?
  7. CLI extensibility

1. Normal vs. advanced installation

Many questions will be way over the head of the apcore dev, like 'burst limit'. There should be a default install (normal flow) and an option to go all-in (advanced flow). The former will set sensible defaults, the latter may offer more explanation text with each question (or just starts with a pointer to the docs).

2. Script output

Most of the INFO logging (application output) is too much to be part of the script output. I'd consider adding some additional script logging e.g. "Loading templates..." and then have a verbose -v flag to show INFO e.g. "Templates found..".

(Additionally - different issue - there's the question to separate INFO + DEBUG output, e.g. for the latter "Calling sql.Open...")

3. Presenting defaults

Instead of showing the default values after the colon, suggesting to have them before that between brackets. After the colon there's no text and an override value can be immediately typed.

Enter the postgres database port [5432]: █

4. Install automation

(For this I need to know more about what the outcome of the install process is, in terms of folder/file structure, etc.)

There are a number of steps that can be further automated:

5. Bootstrapping

(If worth pursuing further this needs to be addressed separately altogether)

The purpose of example is to showcase how to integrate apcore in your project. The example has an elaborate process to get it running. A step further in that would be that it bootstraps a minimum project layout that has apcore built-in (which can still serve as just-the-example). In fact the CLI is already part of a bootstrap process.

There can be multiple (community-contributed) bootstrap projects. Also the current example may be extended with much more code to demonstrate concepts/features. Should it even be part of apcore repo at all, or separate?

(Additional considerations e.g.: config.ini is sensitive, needs to be part of .gitignore)

6. Dev / Prod mode

Related to 5. Bootstrapping. For the example the CLI configuration needs a certificate for localhost. But if I use develop a GoFed based app, I want to have both Dev and Prod modes at my disposal (test/debug locally, deploy to CI pipeline for prod). In that case config.ini needs a range of different settings, or I need to have separate config.ini files (might be better).

7. CLI extensibility

The CLI is targeted at surfacing the features contained in apcore. But in any scenario a dev will typically create an installable application on top of apcore, with lotsa additional extensions. If the CLI only exists for a one-time bootstrap process or to launch an example server, then it is good as-is. But it should not be part of apcore itself, then.

Another option were if the CLI can also be used in my own application, and I'd be able to extend it. I might add an assets folder besides static. I might have additional DB installation steps. Etcetera. I can't reuse the current actions, which have a pre-cooked sequence and need to copy/paste reuse to add a step.

An addition to cmdline.go may allow me to compose actions from steps in any sequence that make most sense. Part of this change might also involve moving CLI related files to their own folder (framework/cli maybe?)

cjslep commented 3 years ago

Thanks for this! If I can take a quick second to organize the discussion:

  1. Normal vs. advanced installation => #65
  2. Script output => #54
  3. Presenting defaults => #53
  4. Install automation => #66
  5. Bootstrapping => #67
  6. Dev/Prod Mode => #68
  7. CLI Extensibility => This issue! :)

What sort of interface would be an ideal one for the CLI extensibility? That is, what would you want to accomplish with extending the onboarding UI? I am guessing prompting certain choices and getting back a value, most likely for a custom config? Could the API be streamlined to an API call like cli.SetYesNo("My prompt text", my_callback_fn, /*default=*/true) which would do the logic of prompting plus calling my_callback_fn(user_choice), or would it need to be different?

aschrijver commented 3 years ago

There's a bunch of design choices that will lead to different experiences.

But imagine I built a big app on top of apcore. I need to do some config that apcore requires. But I may need to customize, e.g. add an additional DB initialisation step. I might have my own config script that overrides the current one (I start with a copy of that, and extend), or I might have some form of DSL or API that allows me to tweak to heart's content.