diff --git a/CHANGELOG.md b/CHANGELOG.md index f07c0c30..936c4a24 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,11 +2,11 @@ All notable changes to this project will be documented in this file. - + The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - + - + ## [Unreleased] @@ -32,3 +32,5 @@ Using the following categories, list your changes in this order: [unreleased]: https://github.com/Archmonger/Conreq/compare/0.100.0...HEAD [0.100.0]: https://github.com/Archmonger/Conreq/releases/tag/0.100.0 + + diff --git a/conreq/_core/initialization/views.py b/conreq/_core/initialization/views.py index 17b113f2..44866a33 100644 --- a/conreq/_core/initialization/views.py +++ b/conreq/_core/initialization/views.py @@ -7,6 +7,7 @@ INITIALIZED = False +# TODO: Have an "IMPORT BACKUP" button that will import a backup file, if one exists. def initialize(request): # pylint: disable=global-statement # Check cached value if we've already initialized diff --git a/conreq/_core/server_settings/forms.py b/conreq/_core/server_settings/forms.py index ecbc478f..bc81c8c2 100644 --- a/conreq/_core/server_settings/forms.py +++ b/conreq/_core/server_settings/forms.py @@ -171,7 +171,7 @@ class WebserverSettingsForm(EnvFormMixin, ModelForm): env_name="WEBSERVER_WORKERS", initial=settings.WEBSERVER_WORKERS, required=True, - help_text="Number of separate worker processes for the webserver to use. Each worker uses additional memory.", + help_text="Number of separate worker processes for the webserver to use. Each worker uses approximately 80MB additional memory.", ) webserver_debug = EnvBooleanField( env_name="WEBSERVER_DEBUG", diff --git a/conreq/app/register/__init__.py b/conreq/app/register/__init__.py index 551c0d63..791b565a 100644 --- a/conreq/app/register/__init__.py +++ b/conreq/app/register/__init__.py @@ -1,21 +1,21 @@ from conreq.app.register import ( - component, + components, homepage, http, startup, tabs, - template, - view, + templates, + views, websockets, ) __all__ = [ "websockets", - "component", + "components", "homepage", "startup", "tabs", - "template", - "view", + "templates", + "views", "http", ] diff --git a/conreq/app/render/__init__.py b/conreq/app/register/backup.py similarity index 100% rename from conreq/app/render/__init__.py rename to conreq/app/register/backup.py diff --git a/conreq/app/register/component.py b/conreq/app/register/components.py similarity index 100% rename from conreq/app/register/component.py rename to conreq/app/register/components.py diff --git a/conreq/app/register/http.py b/conreq/app/register/http.py index 2c99ccf6..e2673b1b 100644 --- a/conreq/app/register/http.py +++ b/conreq/app/register/http.py @@ -40,6 +40,11 @@ def decorator(view): return decorator +def csrf_origin(url: str): + # TODO: Implement this later + return None + + def _register_view(view, url_pattern, url_patterns, name, use_regex): registered_view = view.as_view() if hasattr(view, "as_view") else view dotted_path = f"{view.__module__}.{view.__name__}".replace("<", "").replace(">", "") diff --git a/conreq/app/register/notification.py b/conreq/app/register/notifications.py similarity index 100% rename from conreq/app/register/notification.py rename to conreq/app/register/notifications.py diff --git a/conreq/app/register/template.py b/conreq/app/register/templates.py similarity index 100% rename from conreq/app/register/template.py rename to conreq/app/register/templates.py diff --git a/conreq/app/register/view.py b/conreq/app/register/views.py similarity index 100% rename from conreq/app/register/view.py rename to conreq/app/register/views.py diff --git a/conreq/app/register/websockets.py b/conreq/app/register/websockets.py index dfa63fbb..293f2665 100644 --- a/conreq/app/register/websockets.py +++ b/conreq/app/register/websockets.py @@ -5,29 +5,18 @@ from conreq.utils.environment import get_base_url BASE_URL = get_base_url(prepend_slash=False, empty_if_unset=True) +# TODO: Implement ASGI middleware -def websocket(path: str, use_regex: bool = False) -> AsyncConsumer: +def websocket(path: str, use_regex: bool = False): """Decorates a websocket consumer class.""" - def decorator(class_: AsyncConsumer): - + def decorator(consumer: AsyncConsumer): websockets = config.asgi.websockets if not use_regex: - websockets.append(urls.path(BASE_URL + path, class_.as_asgi())) + websockets.append(urls.path(BASE_URL + path, consumer.as_asgi())) # type: ignore else: - websockets.append(urls.re_path(BASE_URL + path, class_.as_asgi())) - - return class_ + websockets.append(urls.re_path(BASE_URL + path, consumer.as_asgi())) # type: ignore + return consumer return decorator - - -def middleware( - dotted_path: str, - positioning_elements: list[str] = None, - positioning: str = "before", - reverse: bool = False, -) -> None: - """Shortcut to add ASGI middleware to Django.""" - # TODO: Implement ASGI middleware diff --git a/conreq/app/render/home.py b/conreq/app/render/home.py deleted file mode 100644 index ae196a5f..00000000 --- a/conreq/app/render/home.py +++ /dev/null @@ -1,23 +0,0 @@ -"""Helpers to render IDOM elements on the page""" -from typing import Callable - -from conreq import AuthLevel, ViewportSelector - -# TODO: Create viewport render functions -# pylint: disable=unused-argument,unused-variable,unnecessary-pass - - -def viewport( - selector: ViewportSelector = ViewportSelector.primary, - auth_level: AuthLevel = AuthLevel.user, -) -> Callable: - """Decorates an IDOM component. Forcibly changes the viewport content.""" - - def decorator(func): - return func - - return decorator - - -def background(css_string: str): - """Changes the homescreen's background to a specific CSS string.""" diff --git a/conreq/app/render/modal.py b/conreq/app/render/modal.py deleted file mode 100644 index 537558a5..00000000 --- a/conreq/app/render/modal.py +++ /dev/null @@ -1,12 +0,0 @@ -"""Helpers to render IDOM elements on the page""" - -# TODO: Create modal render functions -# pylint: disable=unused-argument,unused-variable,unnecessary-pass - - -def modal() -> object: - """Decorates a Modal class (not yet created).""" - - -def modal_close() -> None: - """Closes a modal.""" diff --git a/conreq/app/render/toast_message.py b/conreq/app/render/toast_message.py deleted file mode 100644 index 7b8464d4..00000000 --- a/conreq/app/render/toast_message.py +++ /dev/null @@ -1,15 +0,0 @@ -"""Helpers to render IDOM elements on the page""" - -# TODO: Create toast message render function -# pylint: disable=unused-argument,unused-variable,unnecessary-pass - - -def toast_message( - title: str, - message: str, - icon: str, - params: dict = None, -) -> None: - """Renders a toast message with a specific message.""" - - pass diff --git a/docs/src/changelog/index.md b/docs/src/changelog/index.md new file mode 100644 index 00000000..17174200 --- /dev/null +++ b/docs/src/changelog/index.md @@ -0,0 +1,5 @@ +???+ note "Attribution" + + {% include-markdown "../../../CHANGELOG.md" start="" end="" trailing-newlines=false %} + +{% include-markdown "../../../CHANGELOG.md" start="" end="" %} diff --git a/docs/src/developers/interface/python.md b/docs/src/developers/contribute/source.md similarity index 100% rename from docs/src/developers/interface/python.md rename to docs/src/developers/contribute/source.md diff --git a/docs/src/placeholder.md b/docs/src/developers/interface/python/components.md similarity index 100% rename from docs/src/placeholder.md rename to docs/src/developers/interface/python/components.md diff --git a/docs/src/developers/interface/python/fields.md b/docs/src/developers/interface/python/fields.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/developers/interface/python/forms.md b/docs/src/developers/interface/python/forms.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/developers/interface/python/models.md b/docs/src/developers/interface/python/models.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/developers/interface/python/register/backup.md b/docs/src/developers/interface/python/register/backup.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/developers/interface/python/register/components.md b/docs/src/developers/interface/python/register/components.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/developers/interface/python/register/homepage.md b/docs/src/developers/interface/python/register/homepage.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/developers/interface/python/register/http.md b/docs/src/developers/interface/python/register/http.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/developers/interface/python/register/notifications.md b/docs/src/developers/interface/python/register/notifications.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/developers/interface/python/register/startup.md b/docs/src/developers/interface/python/register/startup.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/developers/interface/python/register/tabs.md b/docs/src/developers/interface/python/register/tabs.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/developers/interface/python/register/templates.md b/docs/src/developers/interface/python/register/templates.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/developers/interface/python/register/views.md b/docs/src/developers/interface/python/register/views.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/developers/interface/python/register/websockets.md b/docs/src/developers/interface/python/register/websockets.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/developers/interface/python/services/email.md b/docs/src/developers/interface/python/services/email.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/developers/interface/python/validators.md b/docs/src/developers/interface/python/validators.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/developers/interface/python/views.md b/docs/src/developers/interface/python/views.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/developers/interface/python/widgets.md b/docs/src/developers/interface/python/widgets.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/install/freebsd.md b/docs/src/install/freebsd.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/install/macos.md b/docs/src/install/macos.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/stylesheets/extra.css b/docs/src/stylesheets/extra.css index a3c118e9..b8b324f0 100644 --- a/docs/src/stylesheets/extra.css +++ b/docs/src/stylesheets/extra.css @@ -1,5 +1,5 @@ .md-footer__inner { - display: none; + display: none !important; } .md-typeset :is(.admonition, details) { diff --git a/docs/src/users/getting_started.md b/docs/src/users/getting_started.md new file mode 100644 index 00000000..95047f0e --- /dev/null +++ b/docs/src/users/getting_started.md @@ -0,0 +1,7 @@ +Start Conreq + +Navigate to http://xxxx:7575 + +Follow the setup procedures + +Feel free to expose Conreq to the internet diff --git a/docs/src/users/optimizations.md b/docs/src/users/optimizations.md new file mode 100644 index 00000000..523e33c3 --- /dev/null +++ b/docs/src/users/optimizations.md @@ -0,0 +1,20 @@ +Include security and performance changes that can be made + +## Security + +- Configure Conreq to use SSL +- Use system variables for secret keys +- Limit allowed hosts to only include URLs Conreq will be served at (local URLs can also be safe) +- Limit CSRF trusted origins +- Ensure Debug Mode is turned off whenever exposing Conreq to the internet +- Reduce max session age +- Enable Rotate Secret Key +- Configure email settings to receive security alerts + +## Performance + +- Use Nginx with `X-Accel` (View reverse proxy docs) +- Increase worker count +- Reduce logging +- Use a production database, such as MySQL +- Use a high performance cache, such as Redis diff --git a/docs/src/users/reverse_proxy.md b/docs/src/users/reverse_proxy.md new file mode 100644 index 00000000..defa9774 --- /dev/null +++ b/docs/src/users/reverse_proxy.md @@ -0,0 +1,7 @@ +???+ Summary + + You can reverse proxy Conreq, but make sure to allow websockets and set your proxy headers. + +There are situations that you may want to reverse proxy Conreq, such as with distributed computing or for traffic optimization. + +1. Set Allowed Forwarding IPs diff --git a/mkdocs.yml b/mkdocs.yml index e7cb029b..2e19cd48 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,33 +2,58 @@ nav: - Home: index.md - Install: - - Operating System: - - Unraid: install/unraid.md - - Windows: install/windows.md - - Linux 🚧: install/linux.md - - MacOS 🚧: placeholder.md + - Unraid: install/unraid.md + - Windows: install/windows.md + - Linux: install/linux.md + - MacOS: install/macos.md + - FreeBSD: install/freebsd.md - User's Guide: - - Installing Apps 🚧: users/install_apps.md + - Getting Started: users/getting_started.md + - Installing Apps: users/install_apps.md + - Reverse Proxy: users/reverse_proxy.md + - Optimizations: users/optimizations.md - Configuring Conreq: - Server Settings Interface: users/configure/server_settings.md - Settings Config File: users/configure/env_vars.md - - Custom CSS/JS 🚧: users/configure/static_files.md + - Custom CSS/JS: users/configure/static_files.md - Developer's Guide: - Setup a Conreq Enviroment: - 1. Install Requirements: developers/setup/requirements.md - 2. Run Conreq from Source: developers/setup/run.md - - Programmer's Interface: - - Command Line Interface 🚧: developers/interface/cli.md - - Python Interface 🚧: developers/interface/python.md + - Command Line Interface: developers/interface/cli.md + - Python Interface: + - Front-End: + - components: developers/interface/python/components.md + - views: developers/interface/python/views.md + - Database & Forms: + - forms: developers/interface/python/forms.md + - fields: developers/interface/python/fields.md + - models: developers/interface/python/models.md + - validators: developers/interface/python/validators.md + - widgets: developers/interface/python/widgets.md + - Startup Registration: + - backup: developers/interface/python/register/backup.md + - components: developers/interface/python/register/components.md + - homepage: developers/interface/python/register/homepage.md + - http: developers/interface/python/register/http.md + - notifications: developers/interface/python/register/notifications.md + - startup: developers/interface/python/register/startup.md + - tabs: developers/interface/python/register/tabs.md + - templates: developers/interface/python/register/templates.md + - views: developers/interface/python/register/views.md + - websockets: developers/interface/python/register/websockets.md + - Services: + - email: developers/interface/python/services/email.md - Creating Your First App: - - Getting Started 🚧: developers/apps/getting_started.md - - App File Structure 🚧: developers/apps/file_structure.md - - Creating "Hello World" 🚧: developers/apps/hello_world.md + - Getting Started: developers/apps/getting_started.md + - App File Structure: developers/apps/file_structure.md + - Creating "Hello World": developers/apps/hello_world.md - Contributing: - - Conreq Source Code Explained 🚧: developers/contribute/code_tldr.md - - Updating Conreq Source Code 🚧: placeholder.md + - Conreq Source Code Explained: developers/contribute/code_tldr.md + - Updating Conreq Source Code: develoeprs/contribute/source.md - Updating Conreq Docs: developers/contribute/docs.md - - Listing an App 🚧: developers/contribute/apps.md + - Listing an App: developers/contribute/apps.md + - Changelog: changelog/index.md theme: name: material