move docs to main branch

docs/mkdocs.yml

@@ -0,0 +1,79 @@
+nav:
+    - Home: index.md
+    - Install:
+          - Docker: install/docker.md
+          - Windows NSSM: install/nssm.md
+    - Configuration:
+          - Environment Variables: configure/env_vars.md
+          - Built-in Webserver: configure/webserver.md
+          - Custom CSS/JS: configure/static_files.md
+          - Organizr Authentication: configure/organizr.md
+          - MySQL Database: configure/mysql.md
+    - Development:
+          - Running Conreq Manually: develop/run_conreq.md
+          - Building the Docker: develop/build_docker.md
+          - Creating Custom Apps: develop/creating_apps.md
+    - Contribute:
+          - Updating the Docs: contrib/docs.md
+          - Create an App Store listing: contrib/apps.md
+
+theme:
+    name: material
+    palette:
+        primary: teal
+        accent: teal
+    features:
+        - navigation.instant
+        - navigation.tabs
+        - navigation.tabs.sticky
+        - navigation.top
+        - content.code.copy
+        - search.highlight
+        - navigation.sections
+        - toc.integrate
+
+    icon:
+        repo: fontawesome/brands/github
+
+markdown_extensions:
+    - toc:
+          permalink: true
+    - pymdownx.emoji:
+          emoji_index: !!python/name:material.extensions.emoji.twemoji
+          emoji_generator: !!python/name:material.extensions.emoji.to_svg
+    - pymdownx.tabbed:
+          alternate_style: true
+    - pymdownx.highlight:
+          linenums: true
+    - pymdownx.superfences
+    - pymdownx.details
+    - pymdownx.inlinehilite
+    - admonition
+    - attr_list
+    - md_in_html
+    - pymdownx.keys
+
+plugins:
+    - search
+    - include-markdown
+    - git-authors
+    - minify:
+          minify_html: true
+          minify_js: true
+          minify_css: true
+          cache_safe: true
+    - git-revision-date-localized:
+          fallback_to_build_date: true
+    - spellcheck:
+          known_words: dictionary.txt
+          allow_unicode: no
+          ignore_code: yes
+
+site_name: Conreq Documentation
+site_author: Archmonger
+site_description: Conreq Web Platform
+repo_url: https://github.com/Archmonger/Conreq/
+site_url: https://archmonger.github.io/Conreq/
+repo_name: Archmonger/Conreq
+edit_uri: edit/main/docs/src/
+docs_dir: src

docs/src/configure/env_vars.md

@@ -0,0 +1,56 @@
+Environment variables can be used to customize core Conreq features at boot.
+
+## Environment Variables File
+
+Editing Conreq's `settings.env` file is the recommended way of adding environment variables.
+
+Here are some common locations of this file.
+
+| Operating System                   | Location                             |
+| ---------------------------------- | ------------------------------------ |
+| Manually Run (Windows/Linux/MacOS) | `<CONREQ_DIR>/data/settings.env`     |
+| Unraid Community Apps              | `<APP_DATA_DIR>/conreq/settings.env` |
+| Docker                             | `/config/settings.env`               |
+
+## System Variables
+
+Variables can alternatively be set through the system's environment variables.
+
+| Operating System | Location |
+| --- | --- |
+| Manually Run (Windows/Linux/MacOS) | [Varies depending on operating system.](https://www.twilio.com/en-us/blog/how-to-set-environment-variables-html) |
+| Unraid Docker | Through a docker's `Edit` menu, click `Add another Path, Port, Variable, Label, or Device`, and then under `Config Type` select `Variable`. |
+| Docker | Add as a `-e` parameter via command line, or [using the environment field in your compose file.](https://docs.docker.com/compose/environment-variables/#set-environment-variables-in-containers) |
+
+_Note: System environment variables take priority over those stored in `settings.env`._
+
+## Available Variables
+
+```bash
+# General Settings
+TZ = America/Los_Angeles                # default: UTC (Timezone for log files, in "TZ Database" format)
+BASE_URL = requests                     # default: None
+APP_NAME = RequestCentral               # default: Conreq
+APP_DESCRIPTION = Get yo stuff!         # default: Content Requesting
+ARR_REFRESH_INTERNAL = */15             # default: */1 (Cron minutes for Sonarr/Radarr library refresh)
+LOG_LEVEL = ERROR                       # default: WARNING
+CONREQ_ENV_PREFIX = CONREQ              # default: None
+
+# Data Storage
+DATA_DIR = /example/directory           # default: /config (Defaults to "data" outside of docker)
+DB_ENGINE = MYSQL                       # default: SQLITE3
+MYSQL_CONFIG_FILE = /config/mysql.cnf   # default: None
+
+# Security
+SSL_SECURITY = True                     # default: False (True enables advanced SSL security features)
+PWNED_VALIDATOR = False                 # default: True (False disables checking for compromised passwords)
+ALLOWED_HOST = 192.168.0.199            # default: * (Allows all hosts)
+DEBUG = False                           # default: False (Disable security features, only enable this during development. Defaults to True outside of docker.)
+
+# Email
+EMAIL_USE_TLS = False                   # default: True
+EMAIL_PORT = 587                        # default: None
+EMAIL_HOST = smtp.gmail.com             # default: None
+EMAIL_HOST_USER = [email protected]      # default: None
+EMAIL_HOST_PASSWORD = dogmemes123       # default: None
+```

docs/src/configure/mysql.md

@@ -0,0 +1,18 @@
+1.  Install and run MySQL using your preferred method.
+
+2.  Create a file within your Conreq data directory create a MySQL configuration file (`mysql.cnf`). At minimum you must include the following...
+
+    ```toml
+    [client]
+    database = conreq
+    user = db_username
+    password = db_password
+    host = 192.168.86.200
+    default-character-set = utf8
+    ```
+
+    _Take a look at [MySQL's docs](https://dev.mysql.com/doc/refman/8.0/en/option-files.html) for all available parameters._
+
+3.  Set your `DB_ENGINE ` variable to `MYSQL` and your `MYSQL_CONFIG_FILE` variable to the path to your `mysql.cnf` file.
+
+    _If using Unraid/Docker, add this as a Docker variable. Otherwise, search "How to set environment variables in ... Windows 10"_

docs/src/configure/organizr.md

@@ -0,0 +1,24 @@
+1. Go to `Server Settings` within Conreq and enable `Organizr User Authentication`
+
+2. Set up a `nginx` reverse proxy.
+
+    _If you need help with this, join the [`organizr` Discord](https://discord.com/invite/TrNtY7N) and post in #groups._
+
+3. In your Conreq block within `nginx`, add the following...
+
+    ```nginx
+    # Sets Conreq to be accessible by all Organizr users. Google "Organizr ServerAuth" for more details.
+    auth_request /auth-4;
+
+    # Allows Conreq to log in as an Organizr user
+    auth_request_set $auth_user $upstream_http_x_organizr_user;
+    proxy_set_header X-WEBAUTH-USER $auth_user;
+
+    # Allows Conreq to know the email address of an Organizr user (optional)
+    auth_request_set $auth_email $upstream_http_x_organizr_email;
+    proxy_set_header X-WEBAUTH-EMAIL $auth_email;
+
+    # Allows Conreq to automatically configure Organizr Admins and Co-Admins as Conreq staff members (optional)
+    auth_request_set $auth_group $upstream_http_x_organizr_group;
+    proxy_set_header X-WEBAUTH-GROUP $auth_group;
+    ```

docs/src/configure/static_files.md

@@ -0,0 +1,8 @@
+Conreq can store and serve any custom files located within your data directory's "static" folder.
+
+In order to use this to serve custom CSS or JavaScript...
+
+1. Put a CSS/JS file into `DATA_DIR/static/`
+2. Restart Conreq
+3. Set your Conreq "Custom CSS/JS" to link to the new content, such as `/static/my_style.css`
+4. Done!

docs/src/configure/webserver.md

@@ -0,0 +1,17 @@
+We use [`hypercorn`](https://github.com/pgjones/hypercorn/) as Conreq's production-grade webserver. This webserver can be directly exposed to the internet. For more information beyond what is in this guide, check out the [`hypercorn` documentation](https://pgjones.gitlab.io/hypercorn/).
+
+---
+
+The Conreq webserver can be modified through a `hypercorn.toml` file.
+
+1.  Create a `hypercorn.toml` file within your Conreq data directory (such as `./conreq/data/hypercorn.toml`)
+
+2.  Populate this `toml` file with any property in the [`hypercorn`'s documentation](https://pgjones.gitlab.io/hypercorn/how_to_guides/configuring.html#configuration-options). For example...
+
+    ```toml
+    bind = "0.0.0.0:5357"
+    h11_max_incomplete_size = 4
+    keep_alive_timeout = 20
+    use_reloader = true
+    workers = 20
+    ```

docs/src/contrib/apps.md

@@ -0,0 +1 @@
+Work in Progress, Conreq app framework has not been finalized.

docs/src/contrib/docs.md

@@ -0,0 +1,30 @@
+We use [MkDocs](https://www.mkdocs.org/#overview) to create our documentation. For more information beyond what is in this guide, check out the [MkDocs Documentation](https://www.mkdocs.org/#getting-started).
+
+---
+
+## Setting Up the Environment
+
+1. Install `Python 3.x`
+2. Open a terminal at the root of the repository.
+3. Type `pip install -r requirements.txt` to install MkDocs.
+
+---
+
+## Starting the Preview Webserver
+
+MkDocs contains a tool to allow you to preview your documentation changes live! In order to use it...
+
+1. Open a terminal at the root of the repository.
+2. Type `cd docs` to enter the documentation's source code directory.
+3. Type `mkdocs serve` to start the preview webserver.
+4. Navigate to [`http://127.0.0.1:8000`](http://127.0.0.1:8000) to see the documentation and changes live!
+
+---
+
+## Adding/Editing a Docs Page
+
+1. Create a new markdown file within `source/docs/`, or edit an existing markdown file within this folder.
+2. Fill in this file with any markdown text you want!
+3. _If you made a new file:_ Add this file to the navigation bar within `mkdocs.yml`.
+4. Commit your changes to your GitHub branch.
+5. Submit a GitHub pull request to `Archmonger/Conreq:docs`.

docs/src/develop/build_docker.md

@@ -0,0 +1,9 @@
+## Software Required
+
+-   Install [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+
+## Building the Docker Image
+
+1. Pull the repository from GitHub.
+2. Open a terminal at the root of the repository.
+3. Type `docker build . --no-cache -t conreq` to build the Docker image.

docs/src/develop/creating_apps.md

@@ -0,0 +1 @@
+Work in Progress, Conreq app framework has not been finalized.

docs/src/develop/run_conreq.md

@@ -0,0 +1,35 @@
+There are two environments Conreq can exist in: [Development](#creating-a-development-environment) and [Production](#creating-a-production-environment).
+
+If you intend to edit Conreq's code, then proceed with the Development instructions.
+
+---
+
+## Software Required
+
+-   Install [Python 3.11+](https://www.python.org/downloads/)
+    -   Make sure to select "Add Python 3.x to PATH" during installation.
+    -   Easiest if this is the only version of python on your computer
+-   _If using Windows_: Install [Visual Studio C++](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (Within this installer, navigate to _C++ Build Tools_. Select _MSVC_ and _Windows 10 SDK_)
+-   _Optional_: Install [Visual Studio Code](https://code.visualstudio.com/) (Any editor would work)
+
+## Creating a Development Environment
+
+1. Pull the repository from GitHub.
+2. Open a terminal as administrator at the root of the repository.
+3. _If using Windows_
+    - Type `set-executionpolicy remotesigned` and select Yes to All to allow external Python scripts to run on your computer.
+4. Type `python -m venv .venv` to create a Python virtual environment called `.venv`.
+5. Type `./.venv/Scripts/activate` to enter the virtual environment.
+6. Type `pip install -r requirements.txt` to install all Python dependencies within the virtual environment.
+7. Type `python manage.py run_conreq` to run the webserver.
+
+---
+
+## Creating a Production Environment
+
+Follow all instructions laid out within [Creating a Development Environment](#creating-a-development-environment), but before running `python manage.py run_conreq` do the following:
+
+1. Set your environment variable of `DEBUG` to `false`. The method of doing this will [vary based on operating system](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html).
+    - Doing this enables _a lot_ of **security features**.
+2. The webserver is configured with good defaults for most cases. But if you want to configure the webserver see our [webserver documentation](../configure/webserver.md) for more information.
+3. Type `python manage.py run_conreq` to run the webserver.

docs/src/dictionary.txt

@@ -0,0 +1,5 @@
+conreq
+webserver
+unraid
+reddit
+django

docs/src/index.md

@@ -0,0 +1,13 @@
+[![Docker Hub](https://img.shields.io/badge/Docker-DockerHub-blue?style=flat-square)](https://hub.docker.com/r/archmonger/conreq) [![GitHub Container Registry](https://img.shields.io/badge/Docker-GitHub-blue?style=flat-square)](https://github.com/Archmonger/Conreq/pkgs/container/conreq) [![Discord](https://img.shields.io/discord/440067432552595457?style=flat-square&label=Discord&logo=discord)](https://discord.gg/gQhGZzEjmX "Chat with the community and get realtime support!")
+
+## Welcome to the Conreq Documentation
+
+Conreq is an extensible self-hosted web platform built around [Django](https://www.djangoproject.com/). Read through the docs to learn how to set up Conreq, or how to contribute to the Conreq repository!
+
+Want to join the community or have a question? Chat with us on [Discord](https://discord.gg/gQhGZzEjmX) or create a post on [GitHub Discussions](https://github.com/Archmonger/Conreq/discussions)!
+
+---
+
+## Communities
+
+[:fontawesome-brands-discord: Discord](https://discord.gg/gQhGZzEjmX){ .md-button .md-button--primary } [:fontawesome-brands-reddit: Reddit](https://www.reddit.com/r/conreq/){ .md-button .md-button--primary } [:fontawesome-brands-github: GitHub Discussions](https://github.com/Archmonger/Conreq/discussions){ .md-button .md-button--primary }

docs/src/install/docker.md

@@ -0,0 +1,41 @@
+These instructions configure Conreq to run within a Docker.
+
+Our dockers are published to both [DockerHub](https://hub.docker.com/r/archmonger/conreq/tags) and [GitHub Container Registry](https://github.com/Archmonger/Conreq/pkgs/container/conreq).
+
+---
+
+## Docker Compose
+
+1.  Create a `docker-compose.yml` file is located where you want Conreq to run.
+
+    === "`docker-compose.yml`"
+
+        ```yaml
+        services:
+            conreq:
+                image: ghcr.io/archmonger/conreq:latest # Other tags include `develop` and version numbers (e.g. `0.21.1`)
+                container_name: conreq
+                environment:
+                    - PUID=99 # Optional
+                    - PGID=100 # Optional
+                    - TZ=America/Los_Angeles # If not set, defaults to UTC
+                    # Any other Conreq environment variables can also be set here
+                volumes:
+                    - ./config:/config # You can replace ./config with the location you want to store Conreq's data.
+                ports:
+                    - 7575:7575
+        ```
+
+2.  Run `docker-compose up -d` to start Conreq. The `-d` flag runs the container in the background.
+
+## Docker Run
+
+1.  Run the following command to start Conreq.
+
+    ```bash
+    docker run -d --name=conreq -e PUID=99 -e PGID=100 -e TZ=America/Los_Angeles -v ./config:/config -p 7575:7575 ghcr.io/archmonger/conreq:latest
+    ```
+
+    _Note: You can replace `./config` with the location you want to store Conreq's data._
+
+    _Note 2: The `-d` flag runs the container in the background._

docs/src/install/nssm.md

@@ -0,0 +1,31 @@
+These instructions configure Non-Sucking Service Manager (NSSM) to automatically start Conreq as a Windows service.
+
+A traditional Windows installer is not yet available.
+
+---
+
+## Software Required
+
+-   Install [Python 3.11+](https://www.python.org/downloads/)
+    -   Make sure to select "Add Python 3.x to PATH" during installation.
+    -   Easiest if this is the only version of python on your computer
+    -   Steps below will not work with NSSM if using the "Windows App Store" version of Python.
+-   Install [Visual Studio C++](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (Within this installer, navigate to _C++ Build Tools_. Select _MSVC_ and _Windows 10 SDK_)
+-   Download [NSSM](https://nssm.cc/download)
+
+## Installation
+
+1. Create the folder `C:\Program Files\Conreq`
+2. Use this folder to follow steps [setting up a Conreq environment](../develop/run_conreq.md#creating-a-production-environment), excluding steps involving `python manage.py run_conreq`.
+3. Unzip NSSM in a separate directory where you can permanently keep it (such as `C:\Program Files\NSSM`).
+4. Open a terminal within your NSSM directory **as administrator**.
+5. Open NSSM by typing `.\win64\nssm.exe install Conreq`
+6. Under the Application tab, browse to the path of your **Conreq `venv`**.
+    - For example: `C:\Program Files\Conreq\.venv\Scripts\python.exe`
+7. Under the Application tab, browse to the path of your **Conreq repository**.
+    - For example: `C:\Program Files\Conreq\`
+8. Under the Application tab, set "Arguments" to `manage.py run_conreq`
+9. Click "Install Service".
+10. In your terminal, type `.\win64\nssm.exe start Conreq`.
+    - You can check to make sure its running as a service by running `nssm status Conreq`
+11. Open any internet browser and navigate to [`http://127.0.0.1:7575/`](http://127.0.0.1:7575/)

requirements.txt

@@ -1,2 +1,3 @@
 -r requirements/main.txt
--r requirements/dev.txt
+-r requirements/dev.txt
+-r requirements/docs.txt

requirements/docs.txt

@@ -0,0 +1,9 @@
+mkdocs
+mkdocs-material
+mkdocs-git-revision-date-localized-plugin
+mkdocs-include-markdown-plugin
+linkcheckmd
+mkdocs-spellcheck[all]
+mkdocs-git-authors-plugin
+mkdocs-minify-plugin
+mike