slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: web: clarify the run modes

Browse Source
This commit is contained in:
Simon Michael 2022-11-03 07:43:53 -10:00
parent 90a1b7ad20
commit d95786d2f2
1 changed files with 23 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
hledger-web/hledger-web.m4.md
View File

@ -13,8 +13,9 @@ _man_({{
# SYNOPSIS # SYNOPSIS
}}) }})
`hledger-web [OPTIONS]`\ `hledger-web [OPTIONS] # run temporarily & browse`\
`hledger web -- [OPTIONS]` `hledger-web --serve [OPTIONS] # run without stopping`\
`hledger-web --serve-api [OPTIONS] # run JSON server only`\
_man_({{ _man_({{
# DESCRIPTION # DESCRIPTION
@ -31,23 +32,34 @@ _web_({{
</div> </div>
}}) }})
hledger-web is hledger's web interface. It starts a simple web hledger-web is a simple web application for browsing and adding transactions.
application for browsing and adding transactions, and optionally
opens it in a web browser window if possible.
It provides a more user-friendly UI than the hledger CLI or It provides a more user-friendly UI than the hledger CLI or
hledger-ui interface, showing more at once (accounts, the current hledger-ui TUI, showing more at once (accounts, the current account register,
account register, balance charts) and allowing history-aware data balance charts) and allowing history-aware data entry, interactive searching,
entry, interactive searching, and bookmarking. and bookmarking.
hledger-web also lets you share a ledger with multiple users, or even the public web. hledger-web also lets you share a journal with multiple users, or even the public web.
There is no access control, so if you need that you should put it There is no access control, so if you need that you should put it
behind a suitable web proxy. As a small protection against data loss behind a suitable web proxy. As a small protection against data loss
when running an unprotected instance, it writes a numbered backup of when running an unprotected instance, it writes a numbered backup of
the main journal file (only ?) on every edit. the main journal file (only) on every edit.
Like hledger, it reads _files_ Like hledger, it reads _files_
For more about this see hledger(1). For more about this see hledger(1).
hledger-web can be run in three modes:
- Transient mode (the default):
your default web browser will be opened to show the app if possible,
and the app exits automatically after two minutes of inactivity
(no requests received and no open browser windows viewing it).
- With `--serve`: the app runs without stopping, and without opening a browser.
- With `--serve-api`: only the JSON API is served.
In all cases hledger-web runs as a foreground process, logging requests to stdout.
# OPTIONS # OPTIONS
Command-line options and arguments may be used to set an initial Command-line options and arguments may be used to set an initial
@ -58,7 +70,7 @@ Note: if invoking hledger-web as a hledger subcommand, write `--` before options
as shown in the synopsis above. as shown in the synopsis above.
`--serve` `--serve`
: serve and log requests, don't browse or auto-exit : serve and log requests, don't browse or auto-exit after timeout
`--serve-api` `--serve-api`
: like --serve, but serve only the JSON web API, without the server-side web UI : like --serve, but serve only the JSON web API, without the server-side web UI
@ -107,16 +119,6 @@ A @FILE argument will be expanded to the contents of FILE,
which should contain one command line option/argument per line. which should contain one command line option/argument per line.
(To prevent this, insert a `--` argument before.) (To prevent this, insert a `--` argument before.)
By default, hledger-web starts the web app in "transient mode" and
also opens it in your default web browser if possible. In this mode
the web app will keep running for as long as you have it open in a
browser window, and will exit after two minutes of inactivity (no
requests and no browser windows viewing it).
With `--serve`, it just runs the web app without exiting, and logs
requests to the console.
With `--serve-api`, only the JSON web api (see below) is served,
with the usual HTML server-side web UI disabled.
By default the server listens on IP address 127.0.0.1, accessible only to local requests. By default the server listens on IP address 127.0.0.1, accessible only to local requests.
You can use `--host` to change this, eg `--host 0.0.0.0` to listen on all configured addresses. You can use `--host` to change this, eg `--host 0.0.0.0` to listen on all configured addresses.