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