Skip to content

Commit 81bb5ff

Browse files
ArchmongerArchmonger
committed
move docs to main branch
1 parent 8fa91ec commit 81bb5ff

17 files changed

Lines changed: 379 additions & 1 deletion

File tree

‎docs/mkdocs.yml‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
nav:
2+
- Home: index.md
3+
- Install:
4+
- Docker: install/docker.md
5+
- Windows NSSM: install/nssm.md
6+
- Configuration:
7+
- Environment Variables: configure/env_vars.md
8+
- Built-in Webserver: configure/webserver.md
9+
- Custom CSS/JS: configure/static_files.md
10+
- Organizr Authentication: configure/organizr.md
11+
- MySQL Database: configure/mysql.md
12+
- Development:
13+
- Running Conreq Manually: develop/run_conreq.md
14+
- Building the Docker: develop/build_docker.md
15+
- Creating Custom Apps: develop/creating_apps.md
16+
- Contribute:
17+
- Updating the Docs: contrib/docs.md
18+
- Create an App Store listing: contrib/apps.md
19+
20+
theme:
21+
name: material
22+
palette:
23+
primary: teal
24+
accent: teal
25+
features:
26+
- navigation.instant
27+
- navigation.tabs
28+
- navigation.tabs.sticky
29+
- navigation.top
30+
- content.code.copy
31+
- search.highlight
32+
- navigation.sections
33+
- toc.integrate
34+
35+
icon:
36+
repo: fontawesome/brands/github
37+
38+
markdown_extensions:
39+
- toc:
40+
permalink: true
41+
- pymdownx.emoji:
42+
emoji_index: !!python/name:material.extensions.emoji.twemoji
43+
emoji_generator: !!python/name:material.extensions.emoji.to_svg
44+
- pymdownx.tabbed:
45+
alternate_style: true
46+
- pymdownx.highlight:
47+
linenums: true
48+
- pymdownx.superfences
49+
- pymdownx.details
50+
- pymdownx.inlinehilite
51+
- admonition
52+
- attr_list
53+
- md_in_html
54+
- pymdownx.keys
55+
56+
plugins:
57+
- search
58+
- include-markdown
59+
- git-authors
60+
- minify:
61+
minify_html: true
62+
minify_js: true
63+
minify_css: true
64+
cache_safe: true
65+
- git-revision-date-localized:
66+
fallback_to_build_date: true
67+
- spellcheck:
68+
known_words: dictionary.txt
69+
allow_unicode: no
70+
ignore_code: yes
71+
72+
site_name: Conreq Documentation
73+
site_author: Archmonger
74+
site_description: Conreq Web Platform
75+
repo_url: https://github.com/Archmonger/Conreq/
76+
site_url: https://archmonger.github.io/Conreq/
77+
repo_name: Archmonger/Conreq
78+
edit_uri: edit/main/docs/src/
79+
docs_dir: src

‎docs/src/configure/env_vars.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
Environment variables can be used to customize core Conreq features at boot.
2+
3+
## Environment Variables File
4+
5+
Editing Conreq's `settings.env` file is the recommended way of adding environment variables.
6+
7+
Here are some common locations of this file.
8+
9+
| Operating System | Location |
10+
| ---------------------------------- | ------------------------------------ |
11+
| Manually Run (Windows/Linux/MacOS) | `<CONREQ_DIR>/data/settings.env` |
12+
| Unraid Community Apps | `<APP_DATA_DIR>/conreq/settings.env` |
13+
| Docker | `/config/settings.env` |
14+
15+
## System Variables
16+
17+
Variables can alternatively be set through the system's environment variables.
18+
19+
| Operating System | Location |
20+
| --- | --- |
21+
| Manually Run (Windows/Linux/MacOS) | [Varies depending on operating system.](https://www.twilio.com/en-us/blog/how-to-set-environment-variables-html) |
22+
| Unraid Docker | Through a docker's `Edit` menu, click `Add another Path, Port, Variable, Label, or Device`, and then under `Config Type` select `Variable`. |
23+
| 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) |
24+
25+
_Note: System environment variables take priority over those stored in `settings.env`._
26+
27+
## Available Variables
28+
29+
```bash
30+
# General Settings
31+
TZ = America/Los_Angeles # default: UTC (Timezone for log files, in "TZ Database" format)
32+
BASE_URL = requests # default: None
33+
APP_NAME = RequestCentral # default: Conreq
34+
APP_DESCRIPTION = Get yo stuff! # default: Content Requesting
35+
ARR_REFRESH_INTERNAL = */15 # default: */1 (Cron minutes for Sonarr/Radarr library refresh)
36+
LOG_LEVEL = ERROR # default: WARNING
37+
CONREQ_ENV_PREFIX = CONREQ # default: None
38+
39+
# Data Storage
40+
DATA_DIR = /example/directory # default: /config (Defaults to "data" outside of docker)
41+
DB_ENGINE = MYSQL # default: SQLITE3
42+
MYSQL_CONFIG_FILE = /config/mysql.cnf # default: None
43+
44+
# Security
45+
SSL_SECURITY = True # default: False (True enables advanced SSL security features)
46+
PWNED_VALIDATOR = False # default: True (False disables checking for compromised passwords)
47+
ALLOWED_HOST = 192.168.0.199 # default: * (Allows all hosts)
48+
DEBUG = False # default: False (Disable security features, only enable this during development. Defaults to True outside of docker.)
49+
50+
# Email
51+
EMAIL_USE_TLS = False # default: True
52+
EMAIL_PORT = 587 # default: None
53+
EMAIL_HOST = smtp.gmail.com # default: None
54+
EMAIL_HOST_USER = myself@gmail.com # default: None
55+
EMAIL_HOST_PASSWORD = dogmemes123 # default: None
56+
```

‎docs/src/configure/mysql.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
1. Install and run MySQL using your preferred method.
2+
3+
2. Create a file within your Conreq data directory create a MySQL configuration file (`mysql.cnf`). At minimum you must include the following...
4+
5+
```toml
6+
[client]
7+
database = conreq
8+
user = db_username
9+
password = db_password
10+
host = 192.168.86.200
11+
default-character-set = utf8
12+
```
13+
14+
_Take a look at [MySQL's docs](https://dev.mysql.com/doc/refman/8.0/en/option-files.html) for all available parameters._
15+
16+
3. Set your `DB_ENGINE ` variable to `MYSQL` and your `MYSQL_CONFIG_FILE` variable to the path to your `mysql.cnf` file.
17+
18+
_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‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
1. Go to `Server Settings` within Conreq and enable `Organizr User Authentication`
2+
3+
2. Set up a `nginx` reverse proxy.
4+
5+
_If you need help with this, join the [`organizr` Discord](https://discord.com/invite/TrNtY7N) and post in #groups._
6+
7+
3. In your Conreq block within `nginx`, add the following...
8+
9+
```nginx
10+
# Sets Conreq to be accessible by all Organizr users. Google "Organizr ServerAuth" for more details.
11+
auth_request /auth-4;
12+
13+
# Allows Conreq to log in as an Organizr user
14+
auth_request_set $auth_user $upstream_http_x_organizr_user;
15+
proxy_set_header X-WEBAUTH-USER $auth_user;
16+
17+
# Allows Conreq to know the email address of an Organizr user (optional)
18+
auth_request_set $auth_email $upstream_http_x_organizr_email;
19+
proxy_set_header X-WEBAUTH-EMAIL $auth_email;
20+
21+
# Allows Conreq to automatically configure Organizr Admins and Co-Admins as Conreq staff members (optional)
22+
auth_request_set $auth_group $upstream_http_x_organizr_group;
23+
proxy_set_header X-WEBAUTH-GROUP $auth_group;
24+
```

‎docs/src/configure/static_files.md‎

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

‎docs/src/configure/webserver.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
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/).
2+
3+
---
4+
5+
The Conreq webserver can be modified through a `hypercorn.toml` file.
6+
7+
1. Create a `hypercorn.toml` file within your Conreq data directory (such as `./conreq/data/hypercorn.toml`)
8+
9+
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...
10+
11+
```toml
12+
bind = "0.0.0.0:5357"
13+
h11_max_incomplete_size = 4
14+
keep_alive_timeout = 20
15+
use_reloader = true
16+
workers = 20
17+
```

‎docs/src/contrib/apps.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Work in Progress, Conreq app framework has not been finalized.

‎docs/src/contrib/docs.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
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).
2+
3+
---
4+
5+
## Setting Up the Environment
6+
7+
1. Install `Python 3.x`
8+
2. Open a terminal at the root of the repository.
9+
3. Type `pip install -r requirements.txt` to install MkDocs.
10+
11+
---
12+
13+
## Starting the Preview Webserver
14+
15+
MkDocs contains a tool to allow you to preview your documentation changes live! In order to use it...
16+
17+
1. Open a terminal at the root of the repository.
18+
2. Type `cd docs` to enter the documentation's source code directory.
19+
3. Type `mkdocs serve` to start the preview webserver.
20+
4. Navigate to [`http://127.0.0.1:8000`](http://127.0.0.1:8000) to see the documentation and changes live!
21+
22+
---
23+
24+
## Adding/Editing a Docs Page
25+
26+
1. Create a new markdown file within `source/docs/`, or edit an existing markdown file within this folder.
27+
2. Fill in this file with any markdown text you want!
28+
3. _If you made a new file:_ Add this file to the navigation bar within `mkdocs.yml`.
29+
4. Commit your changes to your GitHub branch.
30+
5. Submit a GitHub pull request to `Archmonger/Conreq:docs`.

‎docs/src/develop/build_docker.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
## Software Required
2+
3+
- Install [Docker Desktop](https://www.docker.com/products/docker-desktop/)
4+
5+
## Building the Docker Image
6+
7+
1. Pull the repository from GitHub.
8+
2. Open a terminal at the root of the repository.
9+
3. Type `docker build . --no-cache -t conreq` to build the Docker image.

‎docs/src/develop/creating_apps.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Work in Progress, Conreq app framework has not been finalized.

0 commit comments

Comments
 (0)