# reloadserver
HTTP(S) server with automatic refresh on file changes, based on Python\'s http.server
[](https://mit-license.org/)
[](https://travis-ci.com/github/Densaugeo/reloadserver)
## Supported Platforms
| Platform | Supported? | Notes |
|-|-|-|
| Python 3.10+ | Yes | Tested on 3.10 through 3.12 every release. |
| Python 3.9- | No | |
| Linux | Yes | Tested on Fedora and Ubuntu every release. |
| Windows | Yes | Occasional manual testing. Some features unavailable. |
| Mac | No | I don't have a Mac. It might partially work, but I don't know. |
## Installation
~~~
python3 -m pip install --user reloadserver
~~~
## Usage
~~~
python3 -m reloadserver
~~~
Accepts the same `port` and `bind` arguments as [http.server](https://docs.python.org/3/library/http.server.html), though the others differ. For a full list, run `python -m reloadserver -h`.
By default, monitors files in the current folder (and subfolders) for changes, and refreshes connected clients when a change is detected. Dotfiles and some commonly ignored folders are ignored (this is configurable, as described later). The monitoring is done by injecting a script tag into `.html` files as they're served. This script calls back to reloadserver via long-polling and triggers a reload when it gets the right response.
On Firefox, a full reload is triggered that bypasses cache, as if ctrl+F5 were pressed. Unfortunately, this ability is not available in other browsers (https://developer.mozilla.org/en-US/docs/Web/API/Location/reload).
## File Selection
Files to watch or ignore can be specified, as in these examples:
~~~
# Reload only when index.html or index.js changes
python3 -m reloadserver --watch index.html index.js
# Do not reload when any file in temp cahnges
python3 -m reloadserver --ignore 'temp/*'
~~~
## Trigger Reload by HTTP Request
If your workflow makes file watching complicated (or if you you want to use reloadserver on Windows where file watching doesn't work), a reload can be triggered by sending a `POST` to `/api-reloadserver/trigger-reload`:
~~~
curl -X POST http://localhost:8000/api-reloadserver/trigger-reload
~~~
## HTTPS Option
Why would you need HTTPS for a development environment? Because someone (who is an asshole) decided that several browser APIs such as gamepad and accelerometer APIs should only be available to pages served over HTTPS. So now my development environment needs have HTTPS, which is a headache, and part of why I needed a new reloading server instead of sticking with the existing livereload module for Python.
Run with HTTPS:
~~~
# Generate self-signed server certificate
openssl req -x509 -out server.pem -keyout server.pem -newkey rsa:2048 -nodes -sha256 -subj '/CN=server'
python3 -m reloadserver 8443 --certificate server.pem
~~~
Note: This uses a self-signed server certificate which clients such as web browser and cURL will warn about. Most browsers will allow you to proceed after adding an exception, and cURL will work if given the `-k`/`--insecure` option. Using your own certificate from a certificate authority will avoid these warnings.
## If Behind a Reverse Proxy
When run behind a reverse proxy, needs to handle serving any `.html` files that you want to automatically refresh (so it can inject a script tag), and needs `/api-realoadserver/*`.
If using Caddy, reloadserver works with this Caddyfile (replace HOSTNAME with your test server's name):
~~~
{
# Not necessary, I just don't like the admin API
admin off
}
http://:8080 {
file_server browse
root * .
@html {
path *.html
}
reverse_proxy /api-reloadserver/* http://localhost:8000
reverse_proxy @html http://localhost:8000
}
https://HOSTNAME:8443 {
tls internal
file_server browse
root * .
@html {
path *.html
}
reverse_proxy /api-reloadserver/* http://localhost:8000
reverse_proxy @html http://localhost:8000
}
~~~
## Acknowledgements
Much of `main()` was copied from Python's `http.server`. Many other elements were copied from https://github.com/Densaugeo/uploadserver (another of my projects), thanks to all the contributors over there too!
Thanks to kwyntes for the first pull requests! (Improved handling of malformed .html files and added debouncing).
Raw data
{
"_id": null,
"home_page": "https://github.com/Densaugeo/reloadserver",
"name": "reloadserver",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "",
"author": "Densaugeo",
"author_email": "author@example.com",
"download_url": "https://files.pythonhosted.org/packages/2f/4c/234eefe7a54c3ab7d2282f89f38e38508e63ac9626a267ef8427dd91c593/reloadserver-1.0.0.tar.gz",
"platform": null,
"description": "# reloadserver\n\nHTTP(S) server with automatic refresh on file changes, based on Python\\'s http.server \n\n[](https://mit-license.org/)\n[](https://travis-ci.com/github/Densaugeo/reloadserver)\n\n## Supported Platforms\n\n| Platform | Supported? | Notes |\n|-|-|-|\n| Python 3.10+ | Yes | Tested on 3.10 through 3.12 every release. |\n| Python 3.9- | No | |\n| Linux | Yes | Tested on Fedora and Ubuntu every release. |\n| Windows | Yes | Occasional manual testing. Some features unavailable. |\n| Mac | No | I don't have a Mac. It might partially work, but I don't know. |\n\n## Installation\n\n~~~\npython3 -m pip install --user reloadserver\n~~~\n\n## Usage\n\n~~~\npython3 -m reloadserver\n~~~\n\nAccepts the same `port` and `bind` arguments as [http.server](https://docs.python.org/3/library/http.server.html), though the others differ. For a full list, run `python -m reloadserver -h`.\n\nBy default, monitors files in the current folder (and subfolders) for changes, and refreshes connected clients when a change is detected. Dotfiles and some commonly ignored folders are ignored (this is configurable, as described later). The monitoring is done by injecting a script tag into `.html` files as they're served. This script calls back to reloadserver via long-polling and triggers a reload when it gets the right response.\n\nOn Firefox, a full reload is triggered that bypasses cache, as if ctrl+F5 were pressed. Unfortunately, this ability is not available in other browsers (https://developer.mozilla.org/en-US/docs/Web/API/Location/reload).\n\n## File Selection\n\nFiles to watch or ignore can be specified, as in these examples:\n~~~\n# Reload only when index.html or index.js changes\npython3 -m reloadserver --watch index.html index.js\n\n# Do not reload when any file in temp cahnges\npython3 -m reloadserver --ignore 'temp/*'\n~~~\n\n## Trigger Reload by HTTP Request\n\nIf your workflow makes file watching complicated (or if you you want to use reloadserver on Windows where file watching doesn't work), a reload can be triggered by sending a `POST` to `/api-reloadserver/trigger-reload`:\n~~~\ncurl -X POST http://localhost:8000/api-reloadserver/trigger-reload\n~~~\n\n## HTTPS Option\n\nWhy would you need HTTPS for a development environment? Because someone (who is an asshole) decided that several browser APIs such as gamepad and accelerometer APIs should only be available to pages served over HTTPS. So now my development environment needs have HTTPS, which is a headache, and part of why I needed a new reloading server instead of sticking with the existing livereload module for Python.\n\nRun with HTTPS:\n~~~\n# Generate self-signed server certificate\nopenssl req -x509 -out server.pem -keyout server.pem -newkey rsa:2048 -nodes -sha256 -subj '/CN=server'\n\npython3 -m reloadserver 8443 --certificate server.pem\n~~~\n\nNote: This uses a self-signed server certificate which clients such as web browser and cURL will warn about. Most browsers will allow you to proceed after adding an exception, and cURL will work if given the `-k`/`--insecure` option. Using your own certificate from a certificate authority will avoid these warnings.\n\n## If Behind a Reverse Proxy\n\nWhen run behind a reverse proxy, needs to handle serving any `.html` files that you want to automatically refresh (so it can inject a script tag), and needs `/api-realoadserver/*`.\n\nIf using Caddy, reloadserver works with this Caddyfile (replace HOSTNAME with your test server's name):\n~~~\n{\n # Not necessary, I just don't like the admin API\n admin off\n}\n\nhttp://:8080 {\n file_server browse\n root * .\n \n @html {\n path *.html\n }\n \n reverse_proxy /api-reloadserver/* http://localhost:8000\n reverse_proxy @html http://localhost:8000\n}\n\nhttps://HOSTNAME:8443 {\n tls internal\n \n file_server browse\n root * .\n \n @html {\n path *.html\n }\n \n reverse_proxy /api-reloadserver/* http://localhost:8000\n reverse_proxy @html http://localhost:8000\n}\n~~~\n\n## Acknowledgements\n\nMuch of `main()` was copied from Python's `http.server`. Many other elements were copied from https://github.com/Densaugeo/uploadserver (another of my projects), thanks to all the contributors over there too!\n\nThanks to kwyntes for the first pull requests! (Improved handling of malformed .html files and added debouncing).\n",
"bugtrack_url": null,
"license": "",
"summary": "HTTP(S) server with automatic refresh on file changes, based on Python's http.server",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/Densaugeo/reloadserver"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "41819adfc0c42407e0912a6c02436d7dbc97deaa6a5797fb7df277928748173c",
"md5": "03b74a99a76d89c4641d592a49204c56",
"sha256": "79c21eb4e72db0318cb2dd8bd6a013408442d6e4dd30fa0dbc909434f71aa9df"
},
"downloads": -1,
"filename": "reloadserver-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "03b74a99a76d89c4641d592a49204c56",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 7431,
"upload_time": "2023-11-24T20:10:49",
"upload_time_iso_8601": "2023-11-24T20:10:49.701224Z",
"url": "https://files.pythonhosted.org/packages/41/81/9adfc0c42407e0912a6c02436d7dbc97deaa6a5797fb7df277928748173c/reloadserver-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2f4c234eefe7a54c3ab7d2282f89f38e38508e63ac9626a267ef8427dd91c593",
"md5": "49c051a1ba058d150ba357ec2b540fad",
"sha256": "4160f862419d79a7d427d5515ba9e90fd3e826bffaa4d67028440d890350a3af"
},
"downloads": -1,
"filename": "reloadserver-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "49c051a1ba058d150ba357ec2b540fad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 6842,
"upload_time": "2023-11-24T20:10:51",
"upload_time_iso_8601": "2023-11-24T20:10:51.616028Z",
"url": "https://files.pythonhosted.org/packages/2f/4c/234eefe7a54c3ab7d2282f89f38e38508e63ac9626a267ef8427dd91c593/reloadserver-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-24 20:10:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Densaugeo",
"github_project": "reloadserver",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "reloadserver"
}
JSON
