diff --git a/README.md b/README.md index fd6f80358b255bd5cddaa13598af2885d51b4d2e..37e58a8024882d11a78035a694d88184e374a544 100644 --- a/README.md +++ b/README.md @@ -1,443 +1,5 @@ # 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 +## MOVED +This repository moved to [here](https://git.cccv.de/fejao/c3infodesk-printer)