Remove readme and startup focus on configuration
Problem: A big chunk of both the readme and the startup output is dedicated to configuration, which feels to me to be focused on developers and advanced users rather than beginners who just want to try using Oasis. Solution: Move readme configuration info to its own file and hide all config output (except one line) behind `--debug`. While doing this I noticed that we're `require()`ing a few modules that we don't need before setting `process.env.DEBUG`, which I've reorganized so that we don't accidentally disable debug mode for those modules.
This commit is contained in:
Christian Bundy
parent
3758bbf636
commit
2e7cb4ad66
61
README.md
61
README.md
@ -18,58 +18,16 @@ No browser JavaScript! Oasis has strict security rules that prevent any
|
||||
JavaScript from running in your browser, which helps us make Oasis accessible
|
||||
and easy to improve.
|
||||
|
||||
## Example
|
||||
|
||||
```sh
|
||||
oasis
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
Start Oasis from a command-line interface with the `oasis` command.
|
||||
|
||||
```console
|
||||
$ oasis --help
|
||||
Usage: oasis [options]
|
||||
|
||||
Options:
|
||||
--version Show version number [boolean]
|
||||
-h, --help Show help [boolean]
|
||||
--open Automatically open app in web browser. Use --no-open to disable.
|
||||
[boolean] [default: true]
|
||||
--offline Don't try to connect to scuttlebutt peers or pubs. This can be
|
||||
changed on the 'settings' page while Oasis is running.
|
||||
[boolean] [default: false]
|
||||
--host Hostname for web app to listen on [string] [default: "localhost"]
|
||||
--port Port for web app to listen on [number] [default: 3000]
|
||||
--debug Use verbose output for debugging [boolean] [default: false]
|
||||
-c --config Show current default configuration [boolean] [default: false]
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
The above options can be permanently set with a configuration file found in a
|
||||
standard folder for configuration, depending on your operating system:
|
||||
|
||||
- Linux: `$XDG_CONFIG_HOME/oasis/default.json`.
|
||||
Usually this is `/home/<your username>/.config/oasis/default.json`
|
||||
<!-- cspell:disable-next-line -->
|
||||
- Windows `%APPDATA%\oasis\default.json`.
|
||||
- Mac OS, `/Users/<your username>/Library/Preferences/oasis/default.json`
|
||||
|
||||
The configuration file can override any or all of the command-line _defaults_.
|
||||
Here is an example customizing the port number and the "open" settings:
|
||||
|
||||
```json
|
||||
{
|
||||
"open": false,
|
||||
"port": 19192
|
||||
}
|
||||
```
|
||||
|
||||
### Configuration Semantics
|
||||
|
||||
Which value is given is decided like this:
|
||||
|
||||
1. If an argument is given on the command-line, use that value.
|
||||
2. Otherwise, use the value from the configuration file if present.
|
||||
3. If neither command-line nor configuration file are given, use the built-in default value.
|
||||
Use `oasis --help` to get configuration options. You can change the default
|
||||
values with a custom [configuration](./docs/configuring.md).
|
||||
|
||||
## Installation
|
||||
|
||||
@ -86,7 +44,8 @@ For faster updates and less stability, install from GitHub and upgrade often.
|
||||
npm -g install fraction/oasis
|
||||
```
|
||||
|
||||
Want more? Check out [`install.md`](https://github.com/fraction/oasis/blob/master/docs/install.md).
|
||||
Check out [`install.md`](https://github.com/fraction/oasis/blob/master/docs/install.md)
|
||||
for more information.
|
||||
|
||||
## Resources
|
||||
|
||||
|
||||
28
docs/configuring.md
Normal file
28
docs/configuring.md
Normal file
@ -0,0 +1,28 @@
|
||||
# Configuring
|
||||
|
||||
The default options can be permanently set with a configuration file found in a
|
||||
standard folder for configuration, depending on your operating system:
|
||||
|
||||
- Linux: `$XDG_CONFIG_HOME/oasis/default.json`.
|
||||
Usually this is `/home/<your username>/.config/oasis/default.json`
|
||||
<!-- cspell:disable-next-line -->
|
||||
- Windows `%APPDATA%\oasis\default.json`.
|
||||
- Mac OS, `/Users/<your username>/Library/Preferences/oasis/default.json`
|
||||
|
||||
The configuration file can override any or all of the command-line _defaults_.
|
||||
Here is an example customizing the port number and the "open" settings:
|
||||
|
||||
```json
|
||||
{
|
||||
"open": false,
|
||||
"port": 19192
|
||||
}
|
||||
```
|
||||
|
||||
## Semantics
|
||||
|
||||
Which value is given is decided like this:
|
||||
|
||||
1. If an argument is given on the command-line, use that value.
|
||||
2. Otherwise, use the value from the configuration file if present.
|
||||
3. If neither command-line nor configuration file are given, use the built-in default value.
|
||||
58
src/index.js
58
src/index.js
@ -2,28 +2,18 @@
|
||||
|
||||
"use strict";
|
||||
|
||||
// Koa application to provide HTTP interface.
|
||||
|
||||
const fs = require("fs");
|
||||
const envPaths = require("env-paths");
|
||||
// Minimum required to get config
|
||||
const path = require("path");
|
||||
const nodeHttp = require("http");
|
||||
const debug = require("debug")("oasis");
|
||||
const envPaths = require("env-paths");
|
||||
const cli = require("./cli");
|
||||
const fs = require("fs");
|
||||
|
||||
const defaultConfig = {};
|
||||
const defaultConfigFile = path.join(
|
||||
envPaths("oasis", { suffix: "" }).config,
|
||||
"/default.json"
|
||||
);
|
||||
|
||||
const log = (...args) => {
|
||||
const isDebugEnabled = debug.enabled;
|
||||
debug.enabled = true;
|
||||
debug(...args);
|
||||
debug.enabled = isDebugEnabled;
|
||||
};
|
||||
|
||||
const defaultConfig = {};
|
||||
var haveConfig;
|
||||
let haveConfig;
|
||||
|
||||
try {
|
||||
const defaultConfigOverride = fs.readFileSync(defaultConfigFile, "utf8");
|
||||
@ -40,8 +30,21 @@ try {
|
||||
}
|
||||
}
|
||||
|
||||
const cli = require("./cli");
|
||||
const config = cli(defaultConfig, defaultConfigFile);
|
||||
if (config.debug) {
|
||||
process.env.DEBUG = "oasis,oasis:*";
|
||||
}
|
||||
|
||||
const nodeHttp = require("http");
|
||||
const debug = require("debug")("oasis");
|
||||
|
||||
const log = (...args) => {
|
||||
const isDebugEnabled = debug.enabled;
|
||||
debug.enabled = true;
|
||||
debug(...args);
|
||||
debug.enabled = isDebugEnabled;
|
||||
};
|
||||
|
||||
delete config._;
|
||||
delete config.$0;
|
||||
|
||||
@ -49,26 +52,17 @@ const { host } = config;
|
||||
const { port } = config;
|
||||
const url = `http://${host}:${port}`;
|
||||
|
||||
console.log();
|
||||
if (haveConfig) {
|
||||
console.log(`Configuration read defaults from ${defaultConfigFile}`);
|
||||
log(`Configuration read defaults from ${defaultConfigFile}`);
|
||||
} else {
|
||||
console.log(
|
||||
`No configuration file found at ${defaultConfigFile}. ` +
|
||||
"Using built-in default values."
|
||||
log(
|
||||
`No configuration file found at ${defaultConfigFile}, using built-in default values.`
|
||||
);
|
||||
}
|
||||
console.log("Current configuration:");
|
||||
console.log();
|
||||
console.log(JSON.stringify(config, null, 2));
|
||||
console.log();
|
||||
console.log(`Note: You can save the above to ${defaultConfigFile} to make \
|
||||
these settings the default. See the readme for details.`);
|
||||
console.log();
|
||||
|
||||
if (config.debug) {
|
||||
process.env.DEBUG = "oasis,oasis:*";
|
||||
}
|
||||
debug("Current configuration: %O", config);
|
||||
debug(`You can save the above to ${defaultConfigFile} to make \
|
||||
these settings the default. See the readme for details.`);
|
||||
|
||||
const oasisCheckPath = "/.well-known/oasis";
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user