make a /boot/GRIST_BOOT_KEY page for diagnosing configuration problems (#850)
This is a start at a page for diagnosing problems while setting up Grist. Starting to add some diagnostics based on feedback in github issues. We should make Grist installation easier! But when there is a problem it should be easier to diagnose than it is now, and this may help. The page is ugly and doesn't have many diagnostics yet, but we can iterate. Visit `/boot` on a Grist server for tips on how to use this feature.pull/884/head
parent
2693e01d08
commit
95b734149e
@ -0,0 +1,259 @@
|
|||||||
|
import { AppModel } from 'app/client/models/AppModel';
|
||||||
|
import { createAppPage } from 'app/client/ui/createAppPage';
|
||||||
|
import { pagePanels } from 'app/client/ui/PagePanels';
|
||||||
|
import { BootProbeInfo, BootProbeResult } from 'app/common/BootProbe';
|
||||||
|
import { removeTrailingSlash } from 'app/common/gutil';
|
||||||
|
import { getGristConfig } from 'app/common/urlUtils';
|
||||||
|
import { Disposable, dom, Observable, styled, UseCBOwner } from 'grainjs';
|
||||||
|
|
||||||
|
const cssBody = styled('div', `
|
||||||
|
padding: 20px;
|
||||||
|
overflow: auto;
|
||||||
|
`);
|
||||||
|
|
||||||
|
const cssHeader = styled('div', `
|
||||||
|
padding: 20px;
|
||||||
|
`);
|
||||||
|
|
||||||
|
const cssResult = styled('div', `
|
||||||
|
max-width: 500px;
|
||||||
|
`);
|
||||||
|
|
||||||
|
/**
|
||||||
|
*
|
||||||
|
* A "boot" page for inspecting the state of the Grist installation.
|
||||||
|
*
|
||||||
|
* TODO: deferring using any localization machinery so as not
|
||||||
|
* to have to worry about its failure modes yet, but it should be
|
||||||
|
* fine as long as assets served locally are used.
|
||||||
|
*
|
||||||
|
*/
|
||||||
|
export class Boot extends Disposable {
|
||||||
|
|
||||||
|
// The back end will offer a set of probes (diagnostics) we
|
||||||
|
// can use. Probes have unique IDs.
|
||||||
|
public probes: Observable<BootProbeInfo[]>;
|
||||||
|
|
||||||
|
// Keep track of probe results we have received, by probe ID.
|
||||||
|
public results: Map<string, Observable<BootProbeResult>>;
|
||||||
|
|
||||||
|
// Keep track of probe requests we are making, by probe ID.
|
||||||
|
public requests: Map<string, BootProbe>;
|
||||||
|
|
||||||
|
constructor(_appModel: AppModel) {
|
||||||
|
super();
|
||||||
|
// Setting title in constructor seems to be how we are doing this,
|
||||||
|
// based on other similar pages.
|
||||||
|
document.title = 'Booting Grist';
|
||||||
|
this.probes = Observable.create(this, []);
|
||||||
|
this.results = new Map();
|
||||||
|
this.requests = new Map();
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Set up the page. Uses the generic Grist layout with an empty
|
||||||
|
* side panel, just for convenience. Could be made a lot prettier.
|
||||||
|
*/
|
||||||
|
public buildDom() {
|
||||||
|
const config = getGristConfig();
|
||||||
|
const errMessage = config.errMessage;
|
||||||
|
if (!errMessage) {
|
||||||
|
// Probe tool URLs are relative to the current URL. Don't trust configuration,
|
||||||
|
// because it may be buggy if the user is here looking at the boot page
|
||||||
|
// to figure out some problem.
|
||||||
|
const url = new URL(removeTrailingSlash(document.location.href));
|
||||||
|
url.pathname += '/probe';
|
||||||
|
fetch(url.href).then(async resp => {
|
||||||
|
const _probes = await resp.json();
|
||||||
|
this.probes.set(_probes.probes);
|
||||||
|
}).catch(e => reportError(e));
|
||||||
|
}
|
||||||
|
|
||||||
|
const rootNode = dom('div',
|
||||||
|
dom.domComputed(
|
||||||
|
use => {
|
||||||
|
return pagePanels({
|
||||||
|
leftPanel: {
|
||||||
|
panelWidth: Observable.create(this, 240),
|
||||||
|
panelOpen: Observable.create(this, false),
|
||||||
|
hideOpener: true,
|
||||||
|
header: null,
|
||||||
|
content: null,
|
||||||
|
},
|
||||||
|
headerMain: cssHeader(dom('h1', 'Grist Boot')),
|
||||||
|
contentMain: this.buildBody(use, {errMessage}),
|
||||||
|
});
|
||||||
|
}
|
||||||
|
),
|
||||||
|
);
|
||||||
|
return rootNode;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The body of the page is very simple right now, basically a
|
||||||
|
* placeholder. Make a section for each probe, and kick them off in
|
||||||
|
* parallel, showing results as they come in.
|
||||||
|
*/
|
||||||
|
public buildBody(use: UseCBOwner, options: {errMessage?: string}) {
|
||||||
|
if (options.errMessage) {
|
||||||
|
return cssBody(cssResult(this.buildError()));
|
||||||
|
}
|
||||||
|
return cssBody([
|
||||||
|
...use(this.probes).map(probe => {
|
||||||
|
const {id} = probe;
|
||||||
|
let result = this.results.get(id);
|
||||||
|
if (!result) {
|
||||||
|
result = Observable.create(this, {});
|
||||||
|
this.results.set(id, result);
|
||||||
|
}
|
||||||
|
let request = this.requests.get(id);
|
||||||
|
if (!request) {
|
||||||
|
request = new BootProbe(id, this);
|
||||||
|
this.requests.set(id, request);
|
||||||
|
}
|
||||||
|
request.start();
|
||||||
|
return cssResult(
|
||||||
|
this.buildResult(probe, use(result), probeDetails[id]));
|
||||||
|
}),
|
||||||
|
]);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* This is used when there is an attempt to access the boot page
|
||||||
|
* but something isn't right - either the page isn't enabled, or
|
||||||
|
* the key in the URL is wrong. Give the user some information about
|
||||||
|
* how to set things up.
|
||||||
|
*/
|
||||||
|
public buildError() {
|
||||||
|
return dom(
|
||||||
|
'div',
|
||||||
|
dom('p',
|
||||||
|
'A diagnostics page can be made available at:',
|
||||||
|
dom('blockquote', '/boot/GRIST_BOOT_KEY'),
|
||||||
|
'GRIST_BOOT_KEY is an environment variable ',
|
||||||
|
' set before Grist starts. It should only',
|
||||||
|
' contain characters that are valid in a URL.',
|
||||||
|
' It should be a secret, since no authentication is needed',
|
||||||
|
' to visit the diagnostics page.'),
|
||||||
|
dom('p',
|
||||||
|
'You are seeing this page because either the key is not set,',
|
||||||
|
' or it is not in the URL.'),
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* An ugly rendering of information returned by the probe.
|
||||||
|
*/
|
||||||
|
public buildResult(info: BootProbeInfo, result: BootProbeResult,
|
||||||
|
details: ProbeDetails|undefined) {
|
||||||
|
const out: (HTMLElement|string|null)[] = [];
|
||||||
|
out.push(dom('h2', info.name));
|
||||||
|
if (details) {
|
||||||
|
out.push(dom('p', '> ', details.info));
|
||||||
|
}
|
||||||
|
if (result.verdict) {
|
||||||
|
out.push(dom('pre', result.verdict));
|
||||||
|
}
|
||||||
|
if (result.success !== undefined) {
|
||||||
|
out.push(result.success ? '✅' : '❌');
|
||||||
|
}
|
||||||
|
if (result.done === true) {
|
||||||
|
out.push(dom('p', 'no fault detected'));
|
||||||
|
}
|
||||||
|
if (result.details) {
|
||||||
|
for (const [key, val] of Object.entries(result.details)) {
|
||||||
|
out.push(dom(
|
||||||
|
'div',
|
||||||
|
key,
|
||||||
|
dom('input', dom.prop('value', JSON.stringify(val)))));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return out;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Represents a single diagnostic.
|
||||||
|
*/
|
||||||
|
export class BootProbe {
|
||||||
|
constructor(public id: string, public boot: Boot) {
|
||||||
|
const url = new URL(removeTrailingSlash(document.location.href));
|
||||||
|
url.pathname = url.pathname + '/probe/' + id;
|
||||||
|
fetch(url.href).then(async resp => {
|
||||||
|
const _probes: BootProbeResult = await resp.json();
|
||||||
|
const ob = boot.results.get(id);
|
||||||
|
if (ob) {
|
||||||
|
ob.set(_probes);
|
||||||
|
}
|
||||||
|
}).catch(e => console.error(e));
|
||||||
|
}
|
||||||
|
|
||||||
|
public start() {
|
||||||
|
let result = this.boot.results.get(this.id);
|
||||||
|
if (!result) {
|
||||||
|
result = Observable.create(this.boot, {});
|
||||||
|
this.boot.results.set(this.id, result);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Create a stripped down page to show boot information.
|
||||||
|
* Make sure the API isn't used since it may well be unreachable
|
||||||
|
* due to a misconfiguration, especially in multi-server setups.
|
||||||
|
*/
|
||||||
|
createAppPage(appModel => {
|
||||||
|
return dom.create(Boot, appModel);
|
||||||
|
}, {
|
||||||
|
useApi: false,
|
||||||
|
});
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Basic information about diagnostics is kept on the server,
|
||||||
|
* but it can be useful to show extra details and tips in the
|
||||||
|
* client.
|
||||||
|
*/
|
||||||
|
const probeDetails: Record<string, ProbeDetails> = {
|
||||||
|
'boot-page': {
|
||||||
|
info: `
|
||||||
|
This boot page should not be too easy to access. Either turn
|
||||||
|
it off when configuration is ok (by unsetting GRIST_BOOT_KEY)
|
||||||
|
or make GRIST_BOOT_KEY long and cryptographically secure.
|
||||||
|
`,
|
||||||
|
},
|
||||||
|
|
||||||
|
'health-check': {
|
||||||
|
info: `
|
||||||
|
Grist has a small built-in health check often used when running
|
||||||
|
it as a container.
|
||||||
|
`,
|
||||||
|
},
|
||||||
|
|
||||||
|
'host-header': {
|
||||||
|
info: `
|
||||||
|
Requests arriving to Grist should have an accurate Host
|
||||||
|
header. This is essential when GRIST_SERVE_SAME_ORIGIN
|
||||||
|
is set.
|
||||||
|
`,
|
||||||
|
},
|
||||||
|
|
||||||
|
'system-user': {
|
||||||
|
info: `
|
||||||
|
It is good practice not to run Grist as the root user.
|
||||||
|
`,
|
||||||
|
},
|
||||||
|
|
||||||
|
'reachable': {
|
||||||
|
info: `
|
||||||
|
The main page of Grist should be available.
|
||||||
|
`
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Information about the probe.
|
||||||
|
*/
|
||||||
|
interface ProbeDetails {
|
||||||
|
info: string;
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,22 @@
|
|||||||
|
|
||||||
|
export type BootProbeIds =
|
||||||
|
'boot-page' |
|
||||||
|
'health-check' |
|
||||||
|
'reachable' |
|
||||||
|
'host-header' |
|
||||||
|
'system-user'
|
||||||
|
;
|
||||||
|
|
||||||
|
export interface BootProbeResult {
|
||||||
|
verdict?: string;
|
||||||
|
success?: boolean;
|
||||||
|
done?: boolean;
|
||||||
|
severity?: 'fault' | 'warning' | 'hmm';
|
||||||
|
details?: Record<string, any>;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface BootProbeInfo {
|
||||||
|
id: BootProbeIds;
|
||||||
|
name: string;
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,185 @@
|
|||||||
|
import { ApiError } from 'app/common/ApiError';
|
||||||
|
import { BootProbeIds, BootProbeResult } from 'app/common/BootProbe';
|
||||||
|
import { removeTrailingSlash } from 'app/common/gutil';
|
||||||
|
import { expressWrap, jsonErrorHandler } from 'app/server/lib/expressWrap';
|
||||||
|
import { GristServer } from 'app/server/lib/GristServer';
|
||||||
|
import * as express from 'express';
|
||||||
|
import fetch from 'node-fetch';
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Self-diagnostics useful when installing Grist.
|
||||||
|
*/
|
||||||
|
export class BootProbes {
|
||||||
|
// List of probes.
|
||||||
|
public _probes = new Array<Probe>();
|
||||||
|
|
||||||
|
// Probes indexed by id.
|
||||||
|
public _probeById = new Map<string, Probe>();
|
||||||
|
|
||||||
|
public constructor(private _app: express.Application,
|
||||||
|
private _server: GristServer,
|
||||||
|
private _base: string) {
|
||||||
|
this._addProbes();
|
||||||
|
}
|
||||||
|
|
||||||
|
public addEndpoints() {
|
||||||
|
// Return a list of available probes.
|
||||||
|
this._app.use(`${this._base}/probe$`, expressWrap(async (_, res) => {
|
||||||
|
res.json({
|
||||||
|
'probes': this._probes.map(probe => {
|
||||||
|
return { id: probe.id, name: probe.name };
|
||||||
|
}),
|
||||||
|
});
|
||||||
|
}));
|
||||||
|
|
||||||
|
// Return result of running an individual probe.
|
||||||
|
this._app.use(`${this._base}/probe/:probeId`, expressWrap(async (req, res) => {
|
||||||
|
const probe = this._probeById.get(req.params.probeId);
|
||||||
|
if (!probe) {
|
||||||
|
throw new ApiError('unknown probe', 400);
|
||||||
|
}
|
||||||
|
const result = await probe.apply(this._server, req);
|
||||||
|
res.json(result);
|
||||||
|
}));
|
||||||
|
|
||||||
|
// Fall-back for errors.
|
||||||
|
this._app.use(`${this._base}/probe`, jsonErrorHandler);
|
||||||
|
}
|
||||||
|
|
||||||
|
private _addProbes() {
|
||||||
|
this._probes.push(_homeUrlReachableProbe);
|
||||||
|
this._probes.push(_statusCheckProbe);
|
||||||
|
this._probes.push(_userProbe);
|
||||||
|
this._probes.push(_bootProbe);
|
||||||
|
this._probes.push(_hostHeaderProbe);
|
||||||
|
this._probeById = new Map(this._probes.map(p => [p.id, p]));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* An individual probe has an id, a name, an optional description,
|
||||||
|
* and a method that returns a probe result.
|
||||||
|
*/
|
||||||
|
export interface Probe {
|
||||||
|
id: BootProbeIds;
|
||||||
|
name: string;
|
||||||
|
description?: string;
|
||||||
|
apply: (server: GristServer, req: express.Request) => Promise<BootProbeResult>;
|
||||||
|
}
|
||||||
|
|
||||||
|
const _homeUrlReachableProbe: Probe = {
|
||||||
|
id: 'reachable',
|
||||||
|
name: 'Grist is reachable',
|
||||||
|
apply: async (server, req) => {
|
||||||
|
const url = server.getHomeUrl(req);
|
||||||
|
try {
|
||||||
|
const resp = await fetch(url);
|
||||||
|
if (resp.status !== 200) {
|
||||||
|
throw new ApiError(await resp.text(), resp.status);
|
||||||
|
}
|
||||||
|
return {
|
||||||
|
success: true,
|
||||||
|
};
|
||||||
|
} catch (e) {
|
||||||
|
return {
|
||||||
|
success: false,
|
||||||
|
details: {
|
||||||
|
error: String(e),
|
||||||
|
},
|
||||||
|
severity: 'fault',
|
||||||
|
};
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
const _statusCheckProbe: Probe = {
|
||||||
|
id: 'health-check',
|
||||||
|
name: 'Built-in Health check',
|
||||||
|
apply: async (server, req) => {
|
||||||
|
const baseUrl = server.getHomeUrl(req);
|
||||||
|
const url = new URL(baseUrl);
|
||||||
|
url.pathname = removeTrailingSlash(url.pathname) + '/status';
|
||||||
|
try {
|
||||||
|
const resp = await fetch(url);
|
||||||
|
if (resp.status !== 200) {
|
||||||
|
throw new Error(`Failed with status ${resp.status}`);
|
||||||
|
}
|
||||||
|
const txt = await resp.text();
|
||||||
|
if (!txt.includes('is alive')) {
|
||||||
|
throw new Error(`Failed, page has unexpected content`);
|
||||||
|
}
|
||||||
|
return {
|
||||||
|
success: true,
|
||||||
|
};
|
||||||
|
} catch (e) {
|
||||||
|
return {
|
||||||
|
success: false,
|
||||||
|
error: String(e),
|
||||||
|
severity: 'fault',
|
||||||
|
};
|
||||||
|
}
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
const _userProbe: Probe = {
|
||||||
|
id: 'system-user',
|
||||||
|
name: 'System user is sane',
|
||||||
|
apply: async () => {
|
||||||
|
if (process.getuid && process.getuid() === 0) {
|
||||||
|
return {
|
||||||
|
success: false,
|
||||||
|
verdict: 'User appears to be root (UID 0)',
|
||||||
|
severity: 'warning',
|
||||||
|
};
|
||||||
|
} else {
|
||||||
|
return {
|
||||||
|
success: true,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
const _bootProbe: Probe = {
|
||||||
|
id: 'boot-page',
|
||||||
|
name: 'Boot page exposure',
|
||||||
|
apply: async (server) => {
|
||||||
|
if (!server.hasBoot) {
|
||||||
|
return { success: true };
|
||||||
|
}
|
||||||
|
const maybeSecureEnough = String(process.env.GRIST_BOOT_KEY).length > 10;
|
||||||
|
return {
|
||||||
|
success: maybeSecureEnough,
|
||||||
|
severity: 'hmm',
|
||||||
|
};
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Based on:
|
||||||
|
* https://github.com/gristlabs/grist-core/issues/228#issuecomment-1803304438
|
||||||
|
*
|
||||||
|
* When GRIST_SERVE_SAME_ORIGIN is set, requests arriving to Grist need
|
||||||
|
* to have an accurate Host header.
|
||||||
|
*/
|
||||||
|
const _hostHeaderProbe: Probe = {
|
||||||
|
id: 'host-header',
|
||||||
|
name: 'Host header is sane',
|
||||||
|
apply: async (server, req) => {
|
||||||
|
const host = req.header('host');
|
||||||
|
const url = new URL(server.getHomeUrl(req));
|
||||||
|
if (url.hostname === 'localhost') {
|
||||||
|
return {
|
||||||
|
done: true,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
if (String(url.hostname).toLowerCase() !== String(host).toLowerCase()) {
|
||||||
|
return {
|
||||||
|
success: false,
|
||||||
|
severity: 'hmm',
|
||||||
|
};
|
||||||
|
}
|
||||||
|
return {
|
||||||
|
done: true,
|
||||||
|
};
|
||||||
|
},
|
||||||
|
};
|
@ -0,0 +1,15 @@
|
|||||||
|
<!doctype html>
|
||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<meta charset="utf8">
|
||||||
|
<!-- INSERT BASE -->
|
||||||
|
<link rel="icon" type="image/x-icon" href="icons/favicon.png" />
|
||||||
|
<link rel="stylesheet" href="icons/icons.css">
|
||||||
|
<!-- INSERT LOCALE -->
|
||||||
|
<!-- INSERT CONFIG -->
|
||||||
|
<title>Loading...<!-- INSERT TITLE SUFFIX --></title>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<script crossorigin="anonymous" src="boot.bundle.js"></script>
|
||||||
|
</body>
|
||||||
|
</html>
|
@ -0,0 +1,52 @@
|
|||||||
|
import {assert, driver} from 'mocha-webdriver';
|
||||||
|
import * as gu from 'test/nbrowser/gristUtils';
|
||||||
|
import {server, setupTestSuite} from 'test/nbrowser/testUtils';
|
||||||
|
import * as testUtils from 'test/server/testUtils';
|
||||||
|
|
||||||
|
describe('Boot', function() {
|
||||||
|
this.timeout(30000);
|
||||||
|
setupTestSuite();
|
||||||
|
|
||||||
|
let oldEnv: testUtils.EnvironmentSnapshot;
|
||||||
|
|
||||||
|
afterEach(() => gu.checkForErrors());
|
||||||
|
|
||||||
|
async function hasPrompt() {
|
||||||
|
assert.include(
|
||||||
|
await driver.findContentWait('p', /diagnostics page/, 2000).getText(),
|
||||||
|
'A diagnostics page can be made available');
|
||||||
|
}
|
||||||
|
|
||||||
|
it('gives prompt about how to enable boot page', async function() {
|
||||||
|
await driver.get(`${server.getHost()}/boot`);
|
||||||
|
await hasPrompt();
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('with a GRIST_BOOT_KEY', function() {
|
||||||
|
before(async function() {
|
||||||
|
oldEnv = new testUtils.EnvironmentSnapshot();
|
||||||
|
process.env.GRIST_BOOT_KEY = 'lala';
|
||||||
|
await server.restart();
|
||||||
|
});
|
||||||
|
|
||||||
|
after(async function() {
|
||||||
|
oldEnv.restore();
|
||||||
|
await server.restart();
|
||||||
|
});
|
||||||
|
|
||||||
|
it('gives prompt when key is missing', async function() {
|
||||||
|
await driver.get(`${server.getHost()}/boot`);
|
||||||
|
await hasPrompt();
|
||||||
|
});
|
||||||
|
|
||||||
|
it('gives prompt when key is wrong', async function() {
|
||||||
|
await driver.get(`${server.getHost()}/boot/bilbo`);
|
||||||
|
await hasPrompt();
|
||||||
|
});
|
||||||
|
|
||||||
|
it('gives page when key is right', async function() {
|
||||||
|
await driver.get(`${server.getHost()}/boot/lala`);
|
||||||
|
await driver.findContentWait('h2', /Grist is reachable/, 2000);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
Loading…
Reference in new issue