updated readme
Massimo Melina committed
Feb 14, 2022 at 10:54 UTC
d4c87cf8fd732b060c778b11ffbd221a1dd21283
2 files changed
+87
-94
README.md
+86
-93
@@ -47,104 +47,18 @@ As you can see from the list above, we already have some goods that you can't fi
47
## Windows
48
49
1. go on https://github.com/rejetto/hfs/releases
50
-2. pick your version
51
-3. among the zip files, we suggest the one with "exe" in the name. Download ti and unzip somewhere on your computer
52
-4. first time you should rename `config-example` to `config`, and `accounts-example` to `accounts`. Preserve the `yaml` extension.
53
-
54
- Future upgrades you may probably want to keep your existing config, and possibly use the example as an inspiration.
55
- You should edit config to suite your needs. Surely you want at least to change what files and folders are accessible
56
- by the browser, and you'll find that under the `vfs` entry. For further details please check the `Configuration` section below.
57
-
58
-you are now ready to launch the `hfs.exe` file
50
+2. **download** the latest version zip with "exe" in the name
51
+3. **unzip** somewhere on your computer. You actually need only the exe, the plugins folder is optional.
52
+4. **double click** on `hfs.exe`
53
54
## Linux
55
56
1. install node.js version 16+ from https://nodejs.org/
57
2. download and unzip the latest package from https://github.com/rejetto/hfs/releases/
64
-3. first time you should rename `config-example` to `config`, and `accounts-example` to `accounts`. Preserve the `yaml` extension.
65
-4. chmod +x run.bat
58
+3. chmod +x run.bat
59
60
you are now ready to launch `run.bat`
61
69
-# Configuration
70
-
71
-At the moment there's no administration UI. You must edit the configuration file, that basically a structured text file.
72
-General configuration is read by default from file `config.yaml`.
73
-When not specified, default values will be used.
74
-Supported entries are:
75
-- `port` where to accept http connections. Default is 80.
76
-- `vfs` the files and folders you want to expose. For details see the dedicated following section.
77
-- `admin_port` the port where to reach admin interface. Default is 63636.
78
-- `admin_network` the network address where to reach admin interface. Default is 127.0.0.1 .
79
-- `log` path of the log file. Default is `access.log`.
80
-- `error_log` path of the log file for errors. Default is `error.log`.
81
-- `errors_in_main_log` if you want to use a single file for both kind of entries. Default is false.
82
-- `accounts` path of the accounts file. Default is `accounts.yaml`.
83
-- `mime` command what mime-type to be returned with some files.
84
- E.g.: `"*.jpg": image/jpeg`
85
- You can specify multiple entries, or separate multiple file masks with a p|pe.
86
- You can use the special value `auto` to attempt automatic detection.
87
-- `max_kbps` throttle output speed. Default is Infinity.
88
-- `max_kbps_per_ip` throttle output speed on a per-ip basis. Default is Infinity.
89
-- `zip-calculate-size-for-seconds` how long should we wait before the zip archive starts streaming, trying to understand its finale size. Default is 1.
90
-- `open_browser_at_start` should HFS open browser on localhost on start? Default is true.
91
-- `https_port` listen on a specific port. Default is 443.
92
-- `cert` use this file for https certificate. Minimum to start https is to give a cert and a private_key. Default is none.
93
-- `private_key` use this file for https private key. Default is none.
94
-- `plugins_config` this is a generic place where you can find/put configuration for each plugin, at least those that need configuration.
95
-
96
-## Virtual File System (VFS)
97
-
98
-The virtual file system is a tree of files and folders, collectively called *nodes*.
99
-By default, a node is a folder, unless you provide for it a source that's a file.
100
-Valid keys in a node are:
101
-- `name`: how to display it. If not provided HFS will infer it from the source.
102
-- `source`: absolute or relative path of where to get the content
103
-- `children`: just for folders, specify its virtual children.
104
- Value is a list and its entries are nodes.
105
-- `hidden`: this must not be listed, but it's still downloadable.
106
-- `forbid`: set `true` to forbid listing for this folder
107
-- `hide`: similar to hidden, but it's from the parent node point of view.
108
- Use this to hide children read from the source, not listed in the VFS.
109
- Value is a file mask.
110
-- `remove`: use this to not only hide files but also prevent downloads in a folder with a source. Value is a file mask.
111
-- `rename`: similar to name, but it's from the parent node point.
112
- Use this to change the name of entries that are read from the source, not listed in the VFS.
113
- Value is a dictionary, where the key is the original name.
114
-- `perm`: specify who can see this.
115
- Use this to limit access to this node.
116
- Value is a dictionary, where the key is the username, and the value is `r`.
117
-- `mime`: specify what mime to use for this resource. Use "auto" for automatic detection.
118
-- `default`: to be used with a folder where you want to serve a default html. E.g.: "index.html". Using this will make `mime` default to "auto".
119
-
120
-# Accounts
121
-
122
-Accounts are kept in `accounts.yaml` if any, or you can decide another file by passing parameter `--accounts`.
123
-Inside the file, all accounts should go under `accounts:` key, as a dictionary where the key is the username.
124
-E.g.
125
-```
126
-accounts:
127
- admin:
128
- password: hello123
129
- belongs: group1
130
- guest:
131
- password: guest
132
- group1:
133
-```
134
-
135
-As soon as the file is read HFS will encrypt passwords in a non-reversible way. It means that `password` property is replaced with an encrypted property: `srp`.
136
-For this reason HFS needs that your accounts file is writable.
137
-
138
-As you can see in the example, `group1` has no password. This implies that you cannot log in as `group1`, but still `group1` exists and its purpose is to
139
-gather multiple accounts and refer to them collectively as `group1`, so you can quickly share powers among several accounts.
140
-
141
-## Account options
142
-
143
-Other options you can define as properties of an account:
144
-
145
-- `ignore_limits` to ignore speed limits. Default is `false`.
146
-- `redirect` provide a URL if you want the user to be redirected upon login. Default is none.
147
-
62
# Building instructions
63
64
0. Install [Node.js](https://nodejs.org/) 16+
@@ -203,7 +117,7 @@ Let's first look at the things you can return:
117
118
- `frontend_css: string | string[]` path to one or more css files that you want the frontend to load. These are to be placed in the `public` folder (refer below).
119
- `frontend_js: string | string[]` path to one or more js files that you want the frontend to load. These are to be placed in the `public` folder (refer below).
206
-- `middleware: (Context) => void | true` a function that will be used as a middleware: it can interfere with http activity.
120
+- `middleware: (Context) => void | true | function` a function that will be used as a middleware: it can interfere with http activity.
121
122
To know what the Context object contains please refer to [Koa's documentation](https://github.com/koajs/koa/blob/master/docs/api/context.md).
123
You don't get the `next` parameter as in standard Koa's middlewares because this is different, but we are now explaining how to achieve the same results.
@@ -234,7 +148,7 @@ The `api` object you get as parameter of the `init` contains the following:
148
- `srcDir: string` this can be useful if you need to import some extra function not available in `api`.
149
```js
150
exports.init = api => {
237
- const { BUILD_TIMESTAMP } = api.require(api.srcDir + '/index')
151
+ const { BUILD_TIMESTAMP } = api.require(api.srcDir + '/const')
152
console.log(BUILD_TIMESTAMP)
153
}
154
```
@@ -258,6 +172,7 @@ Depending on the event you'll have an object with parameters in it, and may retu
172
This is a list of available frontend events, with respective parameters and output.
173
174
- `additionalEntryProps`
175
+ - you receive each entry of the list, and optionally produce HTML code that will be added in the `entry-props` container.
176
- parameters `{ entry: Entry }`
177
178
The `Entry` type is an object with the following properties:
@@ -267,4 +182,82 @@ This is a list of available frontend events, with respective parameters and outp
182
- `c?: Date` creation-time.
183
- `m?: Date` modified-time.
184
- output `string | void`
270
- - you receive each entry of the list, and optionally produce HTML code that will be added in the `entry-props` container.
185
+
186
+# File formats
187
+
188
+General configuration is read by default from file `config.yaml`.
189
+When not specified, default values will be used.
190
+Supported entries are:
191
+- `port` where to accept http connections. Default is 80.
192
+- `vfs` the files and folders you want to expose. For details see the dedicated following section.
193
+- `admin_port` the port where to reach admin interface. Default is 63636.
194
+- `admin_network` the network address where to reach admin interface. Default is 127.0.0.1 .
195
+- `log` path of the log file. Default is `access.log`.
196
+- `error_log` path of the log file for errors. Default is `error.log`.
197
+- `errors_in_main_log` if you want to use a single file for both kind of entries. Default is false.
198
+- `accounts` path of the accounts file. Default is `accounts.yaml`.
199
+- `mime` command what mime-type to be returned with some files.
200
+ E.g.: `"*.jpg": image/jpeg`
201
+ You can specify multiple entries, or separate multiple file masks with a p|pe.
202
+ You can use the special value `auto` to attempt automatic detection.
203
+- `max_kbps` throttle output speed. Default is Infinity.
204
+- `max_kbps_per_ip` throttle output speed on a per-ip basis. Default is Infinity.
205
+- `zip-calculate-size-for-seconds` how long should we wait before the zip archive starts streaming, trying to understand its finale size. Default is 1.
206
+- `open_browser_at_start` should HFS open browser on localhost on start? Default is true.
207
+- `https_port` listen on a specific port. Default is 443.
208
+- `cert` use this file for https certificate. Minimum to start https is to give a cert and a private_key. Default is none.
209
+- `private_key` use this file for https private key. Default is none.
210
+- `plugins_config` this is a generic place where you can find/put configuration for each plugin, at least those that need configuration.
211
+
212
+## Virtual File System (VFS)
213
+
214
+The virtual file system is a tree of files and folders, collectively called *nodes*.
215
+By default, a node is a folder, unless you provide for it a source that's a file.
216
+Valid keys in a node are:
217
+- `name`: how to display it. If not provided HFS will infer it from the source.
218
+- `source`: absolute or relative path of where to get the content
219
+- `children`: just for folders, specify its virtual children.
220
+ Value is a list and its entries are nodes.
221
+- `hidden`: this must not be listed, but it's still downloadable.
222
+- `forbid`: set `true` to forbid listing for this folder
223
+- `hide`: similar to hidden, but it's from the parent node point of view.
224
+ Use this to hide children read from the source, not listed in the VFS.
225
+ Value is a file mask.
226
+- `remove`: use this to not only hide files but also prevent downloads in a folder with a source. Value is a file mask.
227
+- `rename`: similar to name, but it's from the parent node point.
228
+ Use this to change the name of entries that are read from the source, not listed in the VFS.
229
+ Value is a dictionary, where the key is the original name.
230
+- `perm`: specify who can see this.
231
+ Use this to limit access to this node.
232
+ Value is a dictionary, where the key is the username, and the value is `r`.
233
+- `mime`: specify what mime to use for this resource. Use "auto" for automatic detection.
234
+- `default`: to be used with a folder where you want to serve a default html. E.g.: "index.html". Using this will make `mime` default to "auto".
235
+
236
+# Accounts
237
+
238
+Accounts are kept in `accounts.yaml` if any, or you can decide another file by passing parameter `--accounts`.
239
+Inside the file, all accounts should go under `accounts:` key, as a dictionary where the key is the username.
240
+E.g.
241
+```
242
+accounts:
243
+ admin:
244
+ password: hello123
245
+ belongs: group1
246
+ guest:
247
+ password: guest
248
+ group1:
249
+```
250
+
251
+As soon as the file is read HFS will encrypt passwords in a non-reversible way. It means that `password` property is replaced with an encrypted property: `srp`.
252
+For this reason HFS needs that your accounts file is writable.
253
+
254
+As you can see in the example, `group1` has no password. This implies that you cannot log in as `group1`, but still `group1` exists and its purpose is to
255
+gather multiple accounts and refer to them collectively as `group1`, so you can quickly share powers among several accounts.
256
+
257
+## Account options
258
+
259
+Other options you can define as properties of an account:
260
+
261
+- `ignore_limits` to ignore speed limits. Default is `false`.
262
+- `redirect` provide a URL if you want the user to be redirected upon login. Default is none.
263
+
admin/src/ConfigPage.ts
+1
-1
@@ -19,7 +19,7 @@ export default function ConfigPage() {
19
})
20
let snap = useSnapState()
21
const [status, reloadStatus] = useApi(res && 'get_status')
22
- useEffect(reloadStatus, [res])
22
+ useEffect(reloadStatus, [res, reloadStatus])
23
if (isValidElement(res))
24
return res
25
const { changes } = snap