feat(webui): initial web ui release (#171)

natelandau · Aug 16, 2024 · 94560d2 · 94560d2
1 parent 7f190f7
commit 94560d2
Show file tree

Hide file tree

Showing 117 changed files with 5,507 additions and 647 deletions.
diff --git a/.env b/.env
@@ -1,6 +1,18 @@
 # Default configuration values. These are overwritten by docker-compose.yml environment variables
-VALENTINA_LOG_FILE = "/valentina/valentina.log"
-VALENTINA_LOG_LEVEL_AWS = "ERROR"     # Log level for AWS S3 client
-VALENTINA_LOG_LEVEL_HTTP = "INFO"     # Log level for discord HTTP, gateway, webhook, client events
-VALENTINA_LOG_LEVEL = "INFO"          # Overall log level for the bot
-VALENTINA_LOG_LEVEL_PYMONGO = "ERROR" # Log level for pymongo
+VALENTINA_LOG_FILE=/valentina.log
+VALENTINA_LOG_LEVEL_AWS=ERROR
+VALENTINA_LOG_LEVEL_HTTP=INFO
+VALENTINA_LOG_LEVEL=INFO
+VALENTINA_LOG_LEVEL_PYMONGO=ERROR
+
+VALENTINA_WEBUI_ENABLE=true
+VALENTINA_WEBUI_PORT=8088
+
+# Set to 0.0.0.0 in Docker
+VALENTINA_WEBUI_HOST=127.0.0.1
+
+# Used for Discord oauth callback url
+VALENTINA_WEBUI_BASE_URL=http://127.0.0.1:8088
+VALENTINA_WEBUI_LOG_LEVEL=DEBUG
+VALENTINA_WEBUI_DEBUG=true
+VALENTINA_REDIS_ADDR=127.0.0.1:6379
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -5,7 +5,7 @@ default_stages: [commit, manual]
 fail_fast: true
 repos:
     - repo: "https://github.com/commitizen-tools/commitizen"
-      rev: v3.27.0
+      rev: v3.29.0
       hooks:
           - id: commitizen
           #   - id: commitizen-branch
@@ -59,17 +59,23 @@ repos:
             entry: yamllint --strict --config-file .yamllint.yml
 
     - repo: "https://github.com/charliermarsh/ruff-pre-commit"
-      rev: "v0.5.1"
+      rev: "v0.5.7"
       hooks:
           - id: ruff
             exclude: tests/
           - id: ruff-format
 
     - repo: "https://github.com/crate-ci/typos"
-      rev: typos-v0.10.26
+      rev: v1.23.6
       hooks:
           - id: typos
 
+    - repo: "https://github.com/djlint/djLint"
+      rev: v1.34.1
+      hooks:
+          - id: djlint
+            args: ["--configuration", "pyproject.toml"]
+
     - repo: local
       hooks:
           # This calls a custom pre-commit script.

diff --git a/.typos.toml b/.typos.toml
@@ -6,4 +6,4 @@
         # nd     = "nd"     # Used in the context of '2nd'
 
 [files]
-    extend-exclude = ["*_cache", ".venv"]
+    extend-exclude = ["*_cache", ".env", ".env.secrets", ".venv", "static"]
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,6 @@
+{
+    "files.associations": {
+        "*.html": "jinja-html",
+        "*.html.j2": "jinja-html"
+    }
+}
diff --git a/README.md b/README.md
@@ -2,7 +2,24 @@
 
 # Valentina
 
-A discord bot to manage roll playing sessions for a highly customized version of Vampire the Masquerade. Major differences from the published game are:
+A Discord bot and optional web service to manage roll playing sessions for a highly customized version of the White Wolf series of TTRPGs. This project is not affiliated with White Wolf or [Paradox Interactive](https://www.paradoxinteractive.com/).
+
+## Topline Features
+
+-   Character creation and management
+-   Campaign management
+-   Dice rolling
+-   Storyteller tools
+-   Other niceties such as:
+    -   Optional Web UI
+    -   Github integration
+    -   Image uploads
+    -   Statistic tracking
+    -   And more!
+
+## Ruleset Overview
+
+Major differences from the games published by White Wolf are:
 
 1. Dice are rolled as a single pool of D10s with a set difficulty. The number of success determines the outcome of the roll.
 
@@ -16,54 +33,74 @@ To play with traditional rules I strongly recommend you use [Inconnu Bot](https:
 
 **For more information on the features and functionality, see the [User Guide](user_guide.md)**
 
-## Install and run
+# Install and run
 
-### Prerequisites
+## Prerequisites
 
 Before running Valentina, the following must be configured or installed.
 
+<details>
+<summary>Discord Bot</summary>
+
 -   Docker and Docker Compose
 -   A valid Discord Bot token. Instructions for this can be found on [Discord's Developer Portal](https://discord.com/developers/docs/getting-started)
--   To use image uploads, an AWS S3 Bucket must be configured with appropriate permissions. _(Instructions on how to do this are out of scope for this document)_
-
-    -   Public must be able to read objects from the bucket
-    -   An IAM role must be created with read/write/list access and the credentials added to the environment variables.
-
-        ```json
-        {
-            "Version": "2012-10-17",
-            "Statement": [
-                {
-                    "Sid": "GetBucketLocation",
-                    "Effect": "Allow",
-                    "Action": ["s3:GetBucketLocation"],
-                    "Resource": ["arn:aws:s3:::Bucket-Name"]
-                },
-                {
-                    "Sid": "ListObjectsInBucket",
-                    "Effect": "Allow",
-                    "Action": ["s3:ListBucket"],
-                    "Resource": ["arn:aws:s3:::Bucket-Name"]
-                },
-                {
-                    "Sid": "AllObjectActions",
-                    "Effect": "Allow",
-                    "Action": "s3:*Object",
-                    "Resource": ["arn:aws:s3:::Bucket-Name/*"]
-                }
-            ]
-        }
-        ```
-
-### Run the bot
+
+</details>
+
+<details>
+<summary>Web UI (Optional)</summary>
+
+-   A Redis instance for caching. This can be run locally or in a cloud service.
+-   Discord OAuth credentials for the bot. Instructions for this can be found on [Discord's Developer Portal](https://discord.com/developers/docs/topics/oauth2)
+-   Ability to run the Docker container on a public IP address or domain name. This is outside the scope of this document.
+</details>
+
+<details>
+<summary>Image Uploads (Optional)</summary>
+To allow image uploads, an AWS S3 bucket must be configured with appropriate permissions. Instructions for this can be found on the [AWS Documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html)
+
+-   Public must be able to read objects from the bucket
+-   An IAM role must be created with read/write/list access and the credentials added to the environment variables.
+
+    ```json
+    {
+        "Version": "2012-10-17",
+        "Statement": [
+            {
+                "Sid": "GetBucketLocation",
+                "Effect": "Allow",
+                "Action": ["s3:GetBucketLocation"],
+                "Resource": ["arn:aws:s3:::Bucket-Name"]
+            },
+            {
+                "Sid": "ListObjectsInBucket",
+                "Effect": "Allow",
+                "Action": ["s3:ListBucket"],
+                "Resource": ["arn:aws:s3:::Bucket-Name"]
+            },
+            {
+                "Sid": "AllObjectActions",
+                "Effect": "Allow",
+                "Action": "s3:*Object",
+                "Resource": ["arn:aws:s3:::Bucket-Name/*"]
+            }
+        ]
+    }
+    ```
+
+</details>
+
+## Run the bot
 
 1. Copy the `docker-compose.yml` file to a directory on your machine
 2. Edit the `docker-compose.yml` file
     - In the `volumes` section replace `/path/to/data` with the directory to hold persistent storage
-    - In the `environment` section add correct values to each environment variable. All available environment variables are below.
+    - In the `environment` section add correct values to each environment variable.
 3. Run `docker compose up`
 
-#### Environment Variables
+### Environment Variables
+
+Settings for Valentina are controlled by environment variables. The following is a list of the available variables and their default values.
 
 | Variable | Default Value | Usage |
 | --- | --- | --- |
@@ -83,14 +120,25 @@ Before running Valentina, the following must be configured or installed.
 | VALENTINA_MONGO_DATABASE_NAME | `valentina` | Production Database name |
 | VALENTINA_GITHUB_REPO |  | Optional: Sets the Github repo to use for Github integration `username/repo` |
 | VALENTINA_GITHUB_TOKEN |  | Optional: Sets the Github API Access token to use for Github integration |
+| VALENTINA_WEBUI_ENABLE | `false` | Optional: Enables the web UI. Set to `true` to enable. |
+| VALENTINA_WEBUI_HOST | `127.0.0.1` | Set the host IP for the web UI. Note: when running in Docker this should always be `0.0.0.0` |
+| VALENTINA_WEBUI_PORT | `8000` | Set the port for the web UI. |
+| VALENTINA_WEBUI_LOG_LEVEL | `INFO` | Sets the log level for the web UI. One of `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
+| VALENTINA_WEBUI_BASE_URL | `http://127.0.0.1:8088` | Base URL for the web service. |
+| VALENTINA_WEBUI_DEBUG | `false` | Enables debug mode for the web UI. Set to `true` to enable. |
+| VALENTINA_REDIS_ADDRESS | `127.0.0.1:6379` | Sets the IP and port for the Redis instance |
+| VALENTINA_REDIS_PASSWORD |  | Optional: Sets the password for the Redis instance |
+| VALENTINA_WEBUI_SECRET_KEY |  | Sets the secret key for the web UI. This is required to run the web UI. |
+| VALENTINA_DISCORD_OAUTH_SECRET |  | Sets the secret for the Discord OAuth. This is required to run the web UI. |
+| VALENTINA_DISCORD_OAUTH_CLIENT_ID |  | Sets the ID for the Discord OAuth. This is required to run the web UI. |
 
 ---
 
-## Contributing
+# Contributing
 
 ## Setup: Once per project
 
-1. Install Python 3.11 and [Poetry](https://python-poetry.org)
+1. Install Python >= 3.11 and [Poetry](https://python-poetry.org)
 2. Clone this repository. `git clone https://github.com/natelandau/valentina.git`
 3. Install the Poetry environment with `poetry install`.
 4. Activate your Poetry environment with `poetry shell`.
@@ -114,6 +162,24 @@ Before running Valentina, the following must be configured or installed.
 -   Run `poetry remove {package}` from within the development environment to uninstall a runtime dependency and remove it from `pyproject.toml` and `poetry.lock`.
 -   Run `poetry update` from within the development environment to upgrade all dependencies to the latest versions allowed by `pyproject.toml`.
 
+## Packages Used
+
+**Discord Bot**
+
+-   [Pycord](https://docs.pycord.dev/en/stable/) - Discord API wrapper
+-   [Beanie ODM](https://beanie-odm.dev/) - MongoDB ODM
+-   [Typer](https://typer.tiangolo.com/) - CLI app framework
+-   [ConfZ](https://confz.readthedocs.io/en/latest/index.html) - Configuration management
+-   [Loguru](https://loguru.readthedocs.io/en/stable/) - Logging
+
+**Web UI**
+
+-   [Quart](https://quart.palletsprojects.com/en/latest/index.html) - Async web framework based on Flask
+-   [Bootstrap](https://getbootstrap.com/) - Frontend framework for the web UI
+-   [Jinja](https://jinja.palletsprojects.com/en/3.0.x/) - Templating engine for the web UI
+-   [JinjaX](https://jinjax.scaletti.dev/) - Super components powers for your Jinja templates
+-   [quart-wtf](https://quart-wtf.readthedocs.io/en/latest/index.html) - Integration of Quart and WTForms including CSRF and file uploading.
+
 ## Testing MongoDB locally
 
 To run the tests associated with the MongoDB database, you must have MongoDB installed locally. The easiest way to do this is with Docker. Set two additional environment variables to allow the tests to connect to the local MongoDB instance.
@@ -125,6 +191,10 @@ To run the tests associated with the MongoDB database, you must have MongoDB ins
 
 NOTE: Github CI integrations will ignore these variables and run the tests against a Mongo instance within the workflows.
 
+## Running the webui locally
+
+A convenience script that runs the webui locally without the Discord bot is available. After setting the required environment variables, and entering the Virtual Environment simply type `webui`. Note, a Redis instance is still required..
+
 ## Troubleshooting
 
 If connecting to Discord with the bot fails due to a certificate error, run `scripts/install_certifi.py` to install the latest certificate bundle.
diff --git a/TODO.md b/TODO.md
@@ -30,3 +30,5 @@
 -   [x] Refactor: Centralize pagination for long responses
 -   [x] Statistics: Track per campaign stats
 -   [x] Storyteller: Associate storyteller characters with campaigns
+-   [ ] WebUI: Allow production callback url in bot oath settings from Discord developer portal
+-   [ ] WebUI: Add bind to `0.0.0.0:8000` before release
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -1,16 +1,19 @@
 ---
-version: '3.8'
+version: "3.8"
 services:
-  valentina:
-    image: ghcr.io/natelandau/valentina:latest
-    hostname: valentina
-    container_name: valentina
-    network_mode: "bridge"
-    volumes:
-      - path/to/dir:/valentina          # Persistent storage for the database
-    environment:
-      - VALENTINA_DISCORD_TOKEN=TOKEN   # Your discord bot token
-      - VALENTINA_GUILDS=ID1,ID2        # Guild IDs where you will run the bot, comma separated
-      - VALENTINA_OWNER_IDS=ID1,ID2     # Discord user IDs for bot owners
-      - VALENTINA_LOG_LEVEL=INFO        # TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL
-    restart: unless-stopped
+    valentina:
+        image: ghcr.io/natelandau/valentina:latest
+        hostname: valentina
+        container_name: valentina
+        network_mode: "bridge"
+        # Uncomment if using the web interface
+        # ports:
+        #     - ${VALENTINA_WEBUI_PORT}:${VALENTINA_WEBUI_PORT}
+        volumes:
+            - path/to/dir:/valentina # Persistent storage for the database
+        environment:
+            - VALENTINA_DISCORD_TOKEN=TOKEN # Your discord bot token
+            - VALENTINA_GUILDS=ID1,ID2 # Guild IDs where you will run the bot, comma separated
+            - VALENTINA_OWNER_IDS=ID1,ID2 # Discord user IDs for bot owners
+            - VALENTINA_LOG_LEVEL=INFO # TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL
+        restart: unless-stopped