From d180ce5b24e6cb0d2875fe80e431e7d5bf971c8f Mon Sep 17 00:00:00 2001
From: fejao <mail@fejao.de>
Date: Mon, 27 Jan 2025 21:23:01 +0100
Subject: [PATCH] Fixed README.md file

---
 README.md | 444 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 442 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 37e58a8..040b0e6 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,445 @@
 # c3InfoDesk Printer
 
-## MOVED
-This repository moved to [here](https://git.cccv.de/fejao/c3infodesk-printer)
+
+
+## WIP
+- [x] Set the app for running over containers.
+- [x] Finish Makefile.
+- [ ] List on TODO.md file
+
+---
+
+## What is this?
+This is a repo for deploying the the printer system used at the c3infodesk for printing EXTREMILY NECESSARY documents
+
+---
+
+## TL;DR
+
+### 1- Clone the repo
+Clone this repo to your target system.
+
+### 2- Set the Variables
+Go tho the **docker/docker-compose.yml** file and edit the **environment variables** there.
+
+### 3- Build the Containers
+Just run the command:
+```bash
+make docker_build_all
+```
+
+### 4- Run the System
+Just run the command:
+```bash
+make docker_run
+```
+
+---
+
+## Using the system with Docker containers
+
+### CUPS Problem
+There's till the moment, no solution for setting the CUPS container without using the UI.
+If you know any other way for doing it, please make a merge request.
+
+#### Stopping the host CUPS
+First of all, at the host system, you should disable cups with:
+```bash
+systemctl stop cups
+```
+
+#### Find the Printer on the host
+For using it with docker, you have first scan at the host system which port is the printer set
+```bash
+lsusb
+```
+
+You should update this at the **docker-compose.yml** file at:
+```yaml
+  cups:
+    devices:
+      - /dev/bus/usb/001/007:/dev/bus/usb/001/007
+```
+
+So the container can connect to the printer.
+
+#### Setting the Printer with it's Driver
+Now you can go to the running CUPS from the container at the address:
+
+```
+http://localhosl:631
+```
+
+And at the administration set the printer with it's driver or PPD file.
+
+**NOTE**
+HP Printers are tricky to find the right driver.
+
+#### After printer with driver installed
+Now will can start/re-start the others containers from the system
+
+
+### Using InfluxDB
+For using the API functionalities, you have to set the **ENABLED_INFLUXDB** to **true**
+
+Please check also the values at the **docker-compose.yml** and adjust it to your needs.
+
+#### WIP
+At the moment, if the influxDB is enabled, I'm unable to set the App before generating a new token from the InfluxDB-UI :(
+
+The token used for generating the container can't be used for setting the organization, buckets and etc.
+This step have to also be genareted manually, as the same as setting the printer from the CUPS container.
+If you have an idea how to solve that, please make a merge request.
+
+So you have to start the system from the docker-compose and go trought the InfluxDB-UI for generating a new Token, then, update the value from **INFLUXDB_TOKEN** at the **docker-compose.yml** file with the new generated token.
+After that, it should work fine.
+Restart the containers from **docker-compose.yml** and the app container should be running.
+
+---
+
+## Printers list
+https://wiki.cccv.de/general/drucker
+
+
+---
+
+## Installing the the system
+Just clone this repo to your computer/Pi. Use the functions/commands setted over the **Makefile**
+
+---
+
+## Using the Makefile
+To list the possible commands run the command:
+
+```bash
+make help
+```
+
+Here is the list from the commands at the mmoment:
+
+```
+debug_container_connect_app    Connects to the app container.
+debug_container_connect_cups   Connects to the cups container.
+debug_container_connect_proxy  Connects to the proxy container.
+debug_proxy_remove             Debug remove the proxy container.
+debug_proxy_start              Debug start the proxy container.
+docker_build_all               Build local docker image from Dockerfile from all.
+docker_build_app               Build local docker image from Dockerfile from app.
+docker_build_cups              Build local docker image from Dockerfile from cups.
+docker_build_proxy             Build local docker image from Dockerfile from proxy.
+docker_create_all              Create all containers.
+docker_create_app              Create the local app container.
+docker_create_cups             Create the local cups container.
+docker_create_proxy            Create the local app container.
+docker_remove_all              Delete the local container.
+docker_run                     Runs the app at the containers.
+docker_start_all               Start all containers.
+docker_start_app               Start the local cups container.
+docker_start_cups              Start the local cups container.
+docker_start_proxy             Start the local proxy container.
+docker_stop_all                Stop the all containers.
+docker_stop_app                Stop the local app container.
+docker_stop_cups               Stop the local cups container.
+docker_stop_proxy              Stop the local proxy container.
+local_install_reqs             Install locally the necessary python requirements.
+local_run                      Runs locally the app locally.
+local_set_venv                 Sets locally a python Virtual Environment from the PYTHON_VENV_PATH setted variable.
+local_test_lint                Runs locally lint tests locally.
+local_test_pep                 Runs locally pep8 tests locally.
+local_test_unit                Runs locally unit-tests locally.
+```
+
+---
+
+## Adjusting the system
+You can adjust the system in 3 ways
+- Editing the **config.yml**
+- Setting **environmental variables**
+- Parsing values to the python command
+
+The hierarchy from each value will be over-writen is:
+
+```
+config.yml --> environmental variables --> parsed values
+```
+
+This means that the parsed values will have priority from the other 2 ones.
+
+### System Environments
+This are the system environments that can be set for running the script.
+
+- **PRINTER_NAME**=EPSON_ET_2820_Series_USB
+- **SERVER_PORT**=8000
+- **SERVER_SECRET_KEY**=123456
+- **DEBUG**=true
+- **DEBUG_DISABLE_PRINTING**=false
+- **VERBOSE**=true
+- **LOG_TO_FILE**=false
+- **PATH_UPLOAD**=/c3printing/uploads
+- **PATH_LOG_FILE**=/c3printing/logs/log_01.txt
+- **PATH_DATA**=/c3printing/data
+- **PATH_TEST_FILE**=/c3printing/tests/files/test_file.pdf
+- **LOGIN_USER_EMAIL**=foo@bar.net
+- **LOGIN_USER_PASSWD**=123456
+- **LOGIN_ADMIN_EMAIL**=foo@bar.net
+- **LOGIN_ADMIN_PASSWD**=123456
+- **LOGIN_API_EMAIL**=foo@bar.net
+- **LOGIN_API_PASSWD**=123456
+- **LOG_MODE**=append
+- **LOG_FORMAT**=%(asctime)s - %(levelname)s - %(module)s -  %(funcName)s - %(message)s
+- **KEEP_ALIVE_MIN**=15
+- **NUM_DIGITS**=9
+- **MAX_UPLOAD_BYTES_FOLDER**=4000000000
+- **MAX_UPLOAD_BYTES_FILE**=16000000
+- **DATE_FORMAT**=%Y-%m-%d_-_%H-%M-%S
+- **ALLOWED_FILE_EXTENSIONS**="{'png', 'jpg', 'jpeg', 'gif', 'pdf'}"
+- **USE_MEM_DB**=false
+- **ENABLED_PRINT_WITH_OPTIONS**=true
+- **ENABLED_QUESTIONS**=false
+- **ENABLED_ABOUT**=false
+- **ENABLED_API**=false
+- **ENABLED_INFLUXDB**=false
+- **FILE_PREVIEW_WIDTH**=800
+- **FILE_PREVIEW_HEIGHT**=600
+- **FILE_AUTO_DELETE_AFTER_PRINT**=false
+- **API_TOKEN_EXPIRE_HOURS**=120
+- **INFLUXDB_TOKEN**='Please set the influxdb token'
+- **INFLUXDB_PORT**=8086
+- **INFLUXDB_URL**='http://localhost'
+- **INFLUXDB_MEASUREMENT**='app-usage'
+- **INFLUXDB_ROTATION_MINUTES**=2
+- **INFLUXDB_BUCKET**='c3infodesk-print'
+- **INFLUXDB_BUCKET_DESCRIPTION**='Bucket used from InfoDesk at the 39c3'
+- **INFLUXDB_BUCKET_RETENTION_DAYS**=10
+
+
+### Parsing the values
+You can see the options by running the command:
+
+```bash
+python3 src/main.py --help
+```
+
+The options are:
+```bash
+usage: main.py [-h] [--debug] [--debug_disable_printing] [--verbose] [--log_to_file] [--use_mem_db] [--enabled_questions] [--enabled_about]
+               [--enabled_print_with_options] [--enabled_api] [--enabled_influxdb] [--file_auto_delete_after_print] [--path_to_upload PATH_TO_UPLOAD]
+               [--path_to_log PATH_TO_LOG] [--path_to_data PATH_TO_DATA] [--path_test_file PATH_TEST_FILE] [--port_server PORT_SERVER]
+               [--server_secret_key SERVER_SECRET_KEY] [--log_file_mode LOG_FILE_MODE] [--log_format LOG_FORMAT] [--printer_name PRINTER_NAME]
+               [--login_user_email LOGIN_USER_EMAIL] [--login_user_passwd LOGIN_USER_PASSWD] [--login_admin_email LOGIN_ADMIN_EMAIL]
+               [--login_admin_passwd LOGIN_ADMIN_PASSWD] [--login_api_email LOGIN_API_EMAIL] [--login_api_passwd LOGIN_API_PASSWD] [--keep_alive KEEP_ALIVE]
+               [--num_digits NUM_DIGITS] [--max_upload_bytes_folder MAX_UPLOAD_BYTES_FOLDER] [--max_upload_bytes_file MAX_UPLOAD_BYTES_FILE]
+               [--max_upload_pdf_pages MAX_UPLOAD_PDF_PAGES] [--max_upload_file_copies MAX_UPLOAD_FILE_COPIES] [--date_format DATE_FORMAT]
+               [--allowed_file_extensions ALLOWED_FILE_EXTENSIONS] [--file_preview_width FILE_PREVIEW_WIDTH] [--file_preview_height FILE_PREVIEW_HEIGHT]
+               [--api_token_expire_hours API_TOKEN_EXPIRE_HOURS] [--influxdb_token INFLUXDB_TOKEN] [--influxdb_organization INFLUXDB_ORGANIZATION]
+               [--influxdb_port INFLUXDB_PORT] [--influxdb_url INFLUXDB_URL] [--influxdb_measurement INFLUXDB_MEASUREMENT]
+               [--influxdb_rotation_minutes INFLUXDB_ROTATION_MINUTES] [--influxdb_bucket INFLUXDB_BUCKET]
+               [--influxdb_bucket_description INFLUXDB_BUCKET_DESCRIPTION] [--influxdb_bucket_retention_days INFLUXDB_BUCKET_RETENTION_DAYS]
+
+c3 InfoDesk Printer
+
+options:
+  -h, --help            show this help message and exit
+  --debug               Enable debugging information from execution.
+  --debug_disable_printing
+                        Disable the printing funcionallity for debugging.
+  --verbose             Enable printing information from execution.
+  --log_to_file         Enable writing the log to a file.
+  --use_mem_db          If using the TinyDB in memory or file.
+  --enabled_questions   If using the questions functionality.
+  --enabled_about       If using the about functionality.
+  --enabled_print_with_options
+                        If using the functionality for printing with options.
+  --enabled_api         If using the API functionality.
+  --enabled_influxdb    If using the InfluxDB functionality.
+  --file_auto_delete_after_print
+                        If auto deleting the file after printing.
+  --path_to_upload PATH_TO_UPLOAD
+                        Path where the printing files should be uploaded.
+  --path_to_log PATH_TO_LOG
+                        Path where the log file should be written.
+  --path_to_data PATH_TO_DATA
+                        Path where the app data should be written.
+  --path_test_file PATH_TEST_FILE
+                        Path where the test print file location.
+  --port_server PORT_SERVER
+                        The port of the system
+  --server_secret_key SERVER_SECRET_KEY
+                        The secret key from the server
+  --log_file_mode LOG_FILE_MODE
+                        Mode that the log file should be written, it can be: 'append' or 'new'.
+  --log_format LOG_FORMAT
+                        Log format to be used.
+  --printer_name PRINTER_NAME
+                        Name of the printer to be used.
+  --login_user_email LOGIN_USER_EMAIL
+                        Email to be used for login as user for printing.
+  --login_user_passwd LOGIN_USER_PASSWD
+                        Password to be used for login as user for printing.
+  --login_admin_email LOGIN_ADMIN_EMAIL
+                        Email to be used for login as admin.
+  --login_admin_passwd LOGIN_ADMIN_PASSWD
+                        Password to be used for login as admin.
+  --login_api_email LOGIN_API_EMAIL
+                        Email to be used for login as api.
+  --login_api_passwd LOGIN_API_PASSWD
+                        Password to be used for login as api.
+  --keep_alive KEEP_ALIVE
+                        The amount of minutes to keep the file at the server before deletion.
+  --num_digits NUM_DIGITS
+                        The lenght of the generated code from the file to be printed.
+  --max_upload_bytes_folder MAX_UPLOAD_BYTES_FOLDER
+                        The maximum size in bytes that can be upload folder can keep.
+  --max_upload_bytes_file MAX_UPLOAD_BYTES_FILE
+                        The maximum size in bytes from a file that can be uploaded.
+  --max_upload_pdf_pages MAX_UPLOAD_PDF_PAGES
+                        The maximum number of pages from a PDF file that can be uploaded.
+  --max_upload_file_copies MAX_UPLOAD_FILE_COPIES
+                        The maximum number of copies from a file that can be printed.
+  --date_format DATE_FORMAT
+                        The date format to be used handiling the system.
+  --allowed_file_extensions ALLOWED_FILE_EXTENSIONS
+                        The allowed file extensions that the system can use.
+  --file_preview_width FILE_PREVIEW_WIDTH
+                        The width at the webpage for previewing a file.
+  --file_preview_height FILE_PREVIEW_HEIGHT
+                        The height at the webpage for previewing a file.
+  --api_token_expire_hours API_TOKEN_EXPIRE_HOURS
+                        How many hours till the API token to expire.
+  --influxdb_token INFLUXDB_TOKEN
+                        The token to be used for InfluxDB.
+  --influxdb_organization INFLUXDB_ORGANIZATION
+                        The organization to be used for InfluxDB.
+  --influxdb_port INFLUXDB_PORT
+                        The port of the InfluxDB server.
+  --influxdb_url INFLUXDB_URL
+                        The URL of the InfluxDB server.
+  --influxdb_measurement INFLUXDB_MEASUREMENT
+                        The measurement name of the InfluxDB server.
+  --influxdb_rotation_minutes INFLUXDB_ROTATION_MINUTES
+                        how many minutes to refresh the values at the InfluxDB server.
+  --influxdb_bucket INFLUXDB_BUCKET
+                        The bucket name of the InfluxDB server.
+  --influxdb_bucket_description INFLUXDB_BUCKET_DESCRIPTION
+                        The description from the bucket of the InfluxDB server.
+  --influxdb_bucket_retention_days INFLUXDB_BUCKET_RETENTION_DAYS
+                        The retention days from the bucket of the InfluxDB server.
+```
+
+---
+
+## Accessing the System via Web
+Just go to the system IP addr from the system and to the things...
+if you haven't changed the SERVER_PORT, it will be 8000
+
+### Running Locally
+```
+http://localhost:8000
+```
+
+### Running from the containers
+```
+http://localhost
+```
+
+### User
+
+- **/**: GET
+  - Where you can upload your file.
+- **/upload**: POST
+  - The output with the code from upladed file
+- **/login**: GET
+  - To login at the app as administrator.
+- **/logout**: GET
+  - To logout at the app as administrator.
+
+### Admin
+These end-points are only accessible **when logged into the system**.
+
+- **/logout**: GET
+  - Logout as admin.
+- **/home-admin**: GET | POST
+  - Where the messages and the first page after login.
+- **/uploaded-list**: GET
+  - Show all the uploaded files. Here you can print or delete the uploaded files.
+- **/uploaded-clean**: GET
+  - Nuke all uploaded files
+- **/file-print**: POST
+  - Return page with the message from printing a file.
+- **/file-print-options**: POST
+  - Return page with the message from printing a file with printing options.
+- **/file-preview**: POST
+  - Opens a new Tab with the file content.
+- **/file-delete**: POST
+  - Return page with the message from deleting a file.
+- **/remove-all-files**: POST
+  - A route for nuking all files on the system.
+- **/docs/index.html**: GET
+  - A route for reading the documentaion of this project.
+
+### Debug
+These endpoints are only enable when **DEBUG** is set to **true**
+
+- **/debug-printers**: GET | POST
+  - Here you can list all the printers recognized from the app using CUPS and printing a test file.
+- **/debug-sys**: GET
+  - Display a couple of tips for debugging the system and also all the setted values.
+- **/debug-api**: GET
+  - Display the generated **token_access** and **token_refresh** values.
+
+### Questions
+These endpoints are only enable when **ENABLED_QUESTIONS** is set to **true**
+
+- **/most-asked-questions**: GET | POST
+  - Read, update and add a new most common questions.
+- **/set-question**: GET | POST
+  - Add or update the questions on the system.
+
+---
+
+---
+
+## Accessing the System via API
+For using the API functionalities, you have to set the **ENABLED_API** to **true**
+
+
+### POST /api/login
+Creating new tokens are only accessible when the app are running at **debug mode**
+
+```bash
+curl -X POST \
+  http://localhost:8000/api/login \
+  -u api@39c3.local:123456
+```
+
+### GET /api/create-refresh-token
+```bash
+curl -X POST \
+  http://localhost:8000/api/create-refresh-token \
+  -H 'Authorization: Bearer YOUR_REFRESH_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{"refresh_token": "YOUR_REFRESH_TOKEN"}'
+```
+
+### GET /api/test
+```bash
+curl -X GET \
+  http://your-app-url.local/api/test \
+  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
+  -H 'Content-Type: application/json'
+```
+
+---
+
+## InfoDesk Printer
+
+### 37c3
+https://support.hp.com/de-de/drivers/hp-laserjet-pro-m402dn/model/7458632
+
+### 38c3
+TODO: Find this in WIKI
+
+---
+
+## License
 
-- 
GitLab