| 1 | # HFS: HTTP File Server |
| 2 | |
| 3 |  |
| 4 | |
| 5 | ## Index |
| 6 | |
| 7 | - [Introduction](#introduction) |
| 8 | - [How does it work](#how-does-it-work) |
| 9 | - [Features](#features) |
| 10 | - [Installation](#installation) |
| 11 | - [Configuration](#configuration) |
| 12 | - [Internationalization](#internationalization) |
| 13 | - [Hidden features](#hidden-features) |
| 14 | - [Contribute](#contribute) |
| 15 | - [More](#more) |
| 16 | |
| 17 | ## Introduction |
| 18 | |
| 19 | Turn your computer into a file-sharing server in seconds. |
| 20 | |
| 21 | * **Unlimited space and bandwidth** — no cloud upload, files come directly from your disk |
| 22 | * **Instant ZIP downloads**, even for huge folders |
| 23 | * **Virtual file system** to organize what you share |
| 24 | * **Real-time activity monitoring** |
| 25 | * **Bandwidth throttling** to control transfer speed |
| 26 | * **Plugin system** to extend functionality |
| 27 | |
| 28 | Runs on: Windows, Linux, macOS, FreeBSD, Android |
| 29 | |
| 30 | ## How does it work |
| 31 | |
| 32 | - run HFS on your computer; an administration webpage automatically shows up |
| 33 | - select which files and folders you want to be accessible |
| 34 | - access those files from a phone or another computer just using a browser |
| 35 | - possibly create accounts and limit access to files |
| 36 | |
| 37 | ## Features |
| 38 | |
| 39 | - https |
| 40 | - easy certificate generation |
| 41 | - virtual file system |
| 42 | - mobile friendly |
| 43 | - search |
| 44 | - accounts |
| 45 | - resumable downloads & uploads |
| 46 | - download folders as zip archive |
| 47 | - delete, move and rename files |
| 48 | - plug-ins (anti-brute-force, thumbnails, ldap, themes, and more) |
| 49 | - simple website serving |
| 50 | - real-time monitoring of connections |
| 51 | - [show some files](https://github.com/rejetto/hfs/discussions/270) |
| 52 | - speed throttler |
| 53 | - geographic firewall |
| 54 | - admin web interface |
| 55 | - multi-language front-end |
| 56 | - virtual hosting |
| 57 | - [reverse-proxy support](https://github.com/rejetto/hfs/wiki/Reverse-proxy) |
| 58 | - comments in file descript.ion |
| 59 | - integrated media player |
| 60 | - [customizable with html, css, and javascript](https://github.com/rejetto/hfs/wiki/Customization) |
| 61 | - dynamic-dns updater |
| 62 | |
| 63 | ## Installation |
| 64 | |
| 65 | For Docker, see https://github.com/rejetto/hfs/wiki/Docker . |
| 66 | |
| 67 | For service installation, see https://github.com/rejetto/hfs/wiki/Service-installation. |
| 68 | |
| 69 | For Homebrew, just `brew install rejetto/hfs/hfs` |
| 70 | |
| 71 | The minimum Windows version required is 10 or Server 2019. |
| 72 | |
| 73 | 1. Download the zip file for your operating system from https://github.com/rejetto/hfs/releases |
| 74 | - ⚠️ Antivirus problems on Windows? [READ THIS](https://github.com/rejetto/hfs/wiki/Antivirus) |
| 75 | - ⚠️ If you have Linux ARM or other unlisted/unsupported platforms, please see the [Other systems](#other-systems) section. |
| 76 | 2. Unzip and launch the `hfs` file. |
| 77 | - ⚠️ Mac: if you get *"cannot be opened because it is from an unidentified developer"*, |
| 78 | you can hold `control` key while clicking, then click `open`. |
| 79 | 3. The browser should automatically open at `localhost`, so you can configure the rest in the Admin-panel. |
| 80 | |
| 81 | Troubleshooting |
| 82 | - If a browser cannot be opened on the computer where you are installing HFS, |
| 83 | you should enter this command in the HFS console: `create-admin <PASSWORD>` |
| 84 | - If you cannot access the console (like when you are running as a service), |
| 85 | you can [edit the config file to add your admin account](config.md#accounts) |
| 86 | - If you don't want to use an editor, you can create the file with this command: |
| 87 | |
| 88 | `echo "create-admin: PASSWORD" > config.yaml` |
| 89 | |
| 90 | By default, HFS does not require a login when you access the *Admin-panel* from localhost. |
| 91 | If you don't like this behavior, disable it in the Admin-panel or enter this console command `config localhost_admin false`. |
| 92 | |
| 93 | To uninstall, remove the files you unzipped and the configuration/data directory (see `config.md` for the location). |
| 94 | |
| 95 | ### Other systems |
| 96 | |
| 97 | If you can't or don't want to run our binary versions, you can try this: |
| 98 | |
| 99 | 1. [Install Node.js](https://nodejs.org) version 18 to 24 |
| 100 | 2. Run at the command line `npx hfs@latest` |
| 101 | |
| 102 | The `@latest` part is optional, and ensures that you are always up to date. |
| 103 | |
| 104 | If this procedure fails, it may be that you are missing one of [these requirements](https://github.com/nodejs/node-gyp#installation). |
| 105 | |
| 106 | Configuration and other files will be stored in `%HOME%/.vfs` |
| 107 | |
| 108 | ## Configuration |
| 109 | |
| 110 | For configuration please see [config.md](config.md); it explains also where all configurations are stored. |
| 111 | |
| 112 | ## Internationalization |
| 113 | |
| 114 | It is possible to show the Front-end in other languages. |
| 115 | Translation for some languages is already provided. If you find an error, consider reporting it |
| 116 | or [editing the source file](https://github.com/rejetto/hfs/tree/main/src/langs). |
| 117 | |
| 118 | In the Languages section of the Admin-panel you can install additional language files. |
| 119 | |
| 120 | If your language is missing, please consider [translating yourself](https://github.com/rejetto/hfs/wiki/Translation). |
| 121 | |
| 122 | ## Hidden features |
| 123 | |
| 124 | - Append `#LOGIN` to the URL to open the login dialog |
| 125 | - Append `?lang=CODE` to the URL to force a specific language |
| 126 | - `Right-click` on toggle-all checkbox to *invert* the state of all checkboxes |
| 127 | - Append `?login=USER:PASSWORD` to automatically log in to the browser |
| 128 | - Append `?search=PATTERN` to trigger a search on startup |
| 129 | - Append `?onlyFiles` or `?onlyFolders` to limit the type of results |
| 130 | - Append `?get=basic` to display a basic web interface, intended for older/simpler browsers |
| 131 | - This is automatic if a basic browser is detected. |
| 132 | - Append `?autoplay=shuffle` to trigger show & play; `?autoplay` will not shuffle, but also will not start until the list is complete |
| 133 | - `Right-click` on "check for updates" to enter a URL of a version to install |
| 134 | - `Shift+click` on a file to *show* and play |
| 135 | - `Ctrl+backspace` to navigate to the parent folder |
| 136 | - Start typing a filename to focus it in the list |
| 137 | - `--consoleFile PATH` to also output all stdout/stderr to a file |
| 138 | - Set env.var. `DISABLE_UPDATE=1` (for containers) |
| 139 | - Launch with `--debug` or env.var. `HFS_DEBUG=1` to generate additional console logs |
| 140 | - Launch with `--no-central` to skip fetching updated info from GitHub (uses built-in data only) |
| 141 | |
| 142 | ## Contribute |
| 143 | |
| 144 | There are several ways to contribute |
| 145 | |
| 146 | - [Report bugs](https://github.com/rejetto/hfs/issues/new?labels=bug&template=bug_report.md) |
| 147 | |
| 148 | It's very important to report bugs, and if you are not so sure about it, don't worry, we'll discuss it. |
| 149 | If you find important security problems, please [contact us privately](mailto:a@rejetto.com) so that we can publish a fix before |
| 150 | the problem is disclosed, for the safety of other users. |
| 151 | |
| 152 | - Use beta versions, and give feedback. |
| 153 | |
| 154 | While betas have more problems, you'll get more features and give a huge help to the project. |
| 155 | |
| 156 | - [Translate to your language](https://github.com/rejetto/hfs/wiki/Translation). |
| 157 | |
| 158 | - [Suggest ideas](https://github.com/rejetto/hfs/discussions) |
| 159 | |
| 160 | While the project should not become too complex, yours may be an idea for a plugin. |
| 161 | |
| 162 | - Write guides or make videos for other users. [We got a wiki](https://github.com/rejetto/hfs/wiki)! |
| 163 | |
| 164 | - Submit your code |
| 165 | |
| 166 | If you'd like to make a change yourself in the code, please first open an "issue" or "discussion" about it, |
| 167 | so we'll try to cooperate and understand what's the best path for it. |
| 168 | |
| 169 | - [Make a plugin](dev-plugins.md) |
| 170 | |
| 171 | A plugin can change the look (a theme), and/or introduce a new functionality. |
| 172 | |
| 173 | ## Code Signing Policy |
| 174 | |
| 175 | Free code signing 🙏 provided by SignPath.io, certificate by [SignPath Foundation](https://signpath.org). |
| 176 | |
| 177 | Author/Reviewer/Approver: Massimo Melina. |
| 178 | |
| 179 | Privacy: Update checks are opt-out; other outbound connections are user-triggered. |
| 180 | |
| 181 | ## More |
| 182 | |
| 183 | - [Additional information (Wiki)](https://github.com/rejetto/hfs/wiki) |
| 184 | |
| 185 | - [APIs](https://github.com/rejetto/hfs/wiki/APIs) |
| 186 | |
| 187 | - [Build yourself](dev.md) |
| 188 | |
| 189 | - [License](LICENSE.txt) |
| 190 | |
| 191 | - Flag images under MIT license from https://www.freakflagsprite.com |