Several changes, revealed during smoke test on final stages (#61)

* Several changes, revealed during smoke test on final stages

+ documentation start

* Added instructions steps

* Contributors added

README.md

@@ -1,154 +1,78 @@
-![Imgur](https://i.imgur.com/V2k2seh.png)
+![overview](docs/images/gen_photo.jpg "overview")
 
-PRISMO Admin Panel
+PRISMO Access system
 ===================
 
-Prismo is a fully open-source and easy-to-install access system designed to 
+PRISMO is a fully open-source and easy-to-install access system designed to 
 control access to tools and equipment in maker spaces. Our goal is to 
 create a system that any maker space in the world can easily set up for
 its own use. The system is completely open-source, including the backend, 
 reader firmware, and PCB schematics.
 
+⚠️ ☢️ 🚀 **Attention!!! Disclaimer!!!** PRISMO is in early alpha, NOT for production use! 
+Expect bugs, limitations, and security risks. Use only in controlled 
+environments. We take no responsibility for damages. Contribute 
+responsibly!
 
-## Config handling
-By default, PRISMO searches for a file named `config_default.json` inside 
-the `/app` directory. This is suitable for development purposes, but for 
-production deployments, you should specify your own configuration file and
-pass its path as the `PRISMO_CONFIG` environment variable. When running
-PRISMO in a Docker container, this path is specified in the `Dockerfile` 
-like so:
+## Setup on Raspberry Pi OS
+Simplest way to bring PRISMO to your life is to use Raspberry Pi and graphical
+desktop environment. Here is full description how to do this: [instruction](docs/rpi_installation_instructions.md)
 
-```commandline
-ENV PRISMO_CONFIG=/app/external/config_docker.json
-```
-In this example, the path `app/external/config_docker.json` is relative to 
-the container's internal directory and mapped from an external directory 
-(see the following paragraph for details).
+## Reader hardware build
 
-## Running in `Docker`
+Readers itself has their own repository and building instructions, 
+follow [repo](https://github.com/hacklabkyiv/prismo-reader) to build your own beautiful reader.
 
-Running PRISMO in a separate Docker container offers several advantages. It 
-isolates data and ensures a well-defined environment for smooth operation. 
-You can verify everything is ready for Docker deployment by running the
-following command:
-```commandline
-$ docker build --no-cache -t prismo-app .
-```
-This command build a container and sets all environment variables from dockerfile.
-```commandline
-$ docker run --name=prismo-app -p 80:5000 --restart always --detach -v "$(pwd)/data/:/app/external/" prismo-app
-```
-This command runs the newly built container and starts the server on port 80. Note that on some systems, port 80 might be 
-unavailable for non-privileged users. For development purposes, you can use 
-the alternative mapping \`5000\:5000\` instead\.
-As shown in the command, the `-v "</span>(pwd)/data/:/app/external/"` 
-option mounts an external volume where you should store your `database.db` 
-and `config_docker.json` files. This volume persists data and configuration 
-outside the container, ensuring they are not lost even if the container is 
-deleted.
+## Reader software flashing
 
-**Additional Notes:**
+Once you got your PRISMO Reader, it is time to flash it with firmware. Flashing reader is performed from Raspberry Pi itself. To flash your brand new,
+fresh reader you need to perform such steps.
+1. Set correct WiFi credentials in system settings. Go go "Settings" Tab in PRISMO webapp(http://prismo.local):
+![wifi settings](docs/images/wifi_settings.png "wifi settings")
+2. Connect your PRISMO Reader HW to Raspberry Pi via USB Cable:
+![flash reader animation](docs/images/flash_reader.webp "flash reader")
+3. Reboot Raspberry Pi
+4. Go to "Devices" Tab fill "Device Name" field and Press "Add Device" button.
+![flash reader](docs/images/flash_reader.png "flash reader")
+5. Press "Start" and wait to complete! That is all!
 
-- Remember to replace the placeholder values for environment variables like `DATABASE_URL` and `SECRET_KEY` with your actual settings in the example commands.
+## Add new users to database
 
-## Installation by docker
+Ok, after flashing new reader you can add new tags and users to database.
 
-- Install docker on the host machine.
-  Check [the tutorial for Raspberry Pi 4](https://github.com/codingforentrepreneurs/Pi-Awesome/blob/main/how-tos/Docker%20%26%20Docker%20Compose%20on%20Raspberry%20Pi.md)
-- Create a folder `data` - the folder use for keep all persistent data, like a database.
-- Run docker container:
+1. Bring new RFID tag to PRISMO Reader. You should hear "Deny" sound and purple light signal from it.
 
-```bash
-docker run --name=prismo-app -p 80:5000 --restart always --detach -v "$(pwd)/data/:/app/external/" hacklabkyiv/prismo-app:0.1.7
-```
+![Access denied](docs/images/access_denied.webp "Access denied")
 
-Add docker to autostart:
+2. Go to "Users" Tab in PRISMO App, you should see latest time of tag use. Add new user name in field below:
 
-```bash
-sudo systemctl enable docker
-```
+![add user](docs/images/add_user.png "add user")
 
-The application ready to work and available on `http://localhost:5000`
+That is all! Now you can toggle checkbox with PRISMO Reader name, and user will have an access for this device!
+But to apply changes on PRISMO Reader you need to reboot it or to use any tag again, because reader updates its keys
+only during boot or after any key use.
 
-### The reader firmware
+![Access Granted](docs/images/access_granted.webp "Access Granted")
 
-The reader is a device which connected to the network and read RFID cards. The reader firmware is stored in
-the `prismo-reader` [repository](https://github.com/hacklabkyiv/prismo-reader/tree/micropython_pn532).
+## Contribution
 
-## Development
+As we said, PRISMO is in early alpha stage, a lot of improvements needed, so
+contact us and join our team! We also can provide more detailed instructions about
+building HW part.
 
-### Preconditions
+List of contributors:
 
-- Python 3.10+ with pip
-- git
-- supervisor(optional)
+- [Artem Synytsyn](https://github.com/leechwort)
+- [Anna Deeva](https://github.com/temhota)
+- [Volodymyr Stelmashchuk](https://github.com/VovaStelmashchuk)
+- [Oleksandr Ivanchuk](https://github.com/Sashkoiv)
+- [Volodymyr Babii](https://github.com/atari-zero)
 
-### Step-by-step installation
+## Financial support
 
-1. Clone the repository:
+System is developed mainly on a volunteering basis, but finantial support for writing documentation was 
+given by TOLOCAR program in Ukraine: a project funded by the German Government @bmz_bund 
+and implemented by the GIZ with support of At Stake gGmbH in close collaboration with Ukrainian and international partners.
 
-    ```sh
-    git clone [email protected]:hacklabkyiv/prismo.git
-    ```
-   or by https:
-    ```sh
-    git clone https://github.com/hacklabkyiv/prismo.git
-    ```
+Also, please support our hackerspace at [Patreon](https://www.patreon.com/join/HackLabKyiv) to keep our PRISMO development active!
 
-2. Install virtualenv in project's directory:
-
-    ```sh
-    $ python3 -m venv ./virtualenv
-    ```
-
-3. Activate virtual environment
-
-    ```
-    source ./virtualenv/bin/activate
-    ```
-
-4. Install required packages:
-
-    ```sh
-    pip3 install -r requirements.txt
-    ```
-
-5. Run for debugging and development: (it will reload app on code changes and enable debug mode)
-
-```sh
-export FLASK_APP=application.py
-flask run --debug
-```
-if you want to autorestart you app on Flask changes, you can do `export FLASK_DEBUG=1`. In case of `Import Error` run `pip3 install --upgrade watchdog`.
-By default, this should be run by Prismo admin process, but for debugging purpose you should run this commands by
-yourself.
-
-## Database
-
-All information about the database is stored in [doc/database.md](docs/database.md) file.
-
-## API
-
-The docs for API is stored in [docs/api.md](docs/api.md) file.
-
-## Slack
-
-Slack integration works with slack bot. You need to create slack bot in your slack workspace and get token for it.
-Scope:
-
-- chat:write
-- files:write
-- incoming-webhook
-
-## Build final docker image and deployment
-
-The main target platform is `linux/arm64/v8` (Raspberry Pi 4). To build docker image for this platform you should use
-buildx.
-
-Execute `docker login` with hacklabkyiv credentials.
-Execute this commands in the root directory of the project:
-
-```
-docker buildx create --use
-docker buildx build --platform linux/arm64/v8 -t hacklabkyiv/prismo-app:<version> --push .
-```

docker-compose.yml

@@ -6,12 +6,11 @@ services:
     build: .
     environment:
       HOST_HOSTNAME: $HOST_HOSTNAME
-      HOST_WIFI_SSID: $HOST_WIFI_SSID
-      HOST_WIFI_PASSWORD: $HOST_WIFI_PASSWORD
     container_name: prismo-app
     restart: always
     ports:
-      - 5000:5000
+      - 80:5000
+    privileged: true
     volumes:
       - "./data/:/app/external/"
       - /run/udev:/run/udev:ro

docker_run.sh

@@ -1,7 +1,5 @@
 #!/bin/bash
 
 export HOST_HOSTNAME=$(hostnamectl hostname)
-export HOST_WIFI_SSID=$(nmcli -s device wifi show-password | grep "SSID"| cut -d" " -f2)
-export HOST_WIFI_PASSWORD=$(nmcli -s device wifi show-password | grep "Password"| cut -d" " -f2)
 
 docker compose up

docs/development.md

@@ -0,0 +1,80 @@
+Developers info
+====================================
+
+### Preconditions
+
+- Python 3.10+ with pip
+- git
+- supervisor(optional)
+
+### Step-by-step installation
+
+1. Clone the repository:
+
+    ```sh
+    git clone [email protected]:hacklabkyiv/prismo.git
+    ```
+   or by https:
+    ```sh
+    git clone https://github.com/hacklabkyiv/prismo.git
+    ```
+
+2. Install virtualenv in project's directory:
+
+    ```sh
+    $ python3 -m venv ./virtualenv
+    ```
+
+3. Activate virtual environment
+
+    ```
+    source ./virtualenv/bin/activate
+    ```
+
+4. Install required packages:
+
+    ```sh
+    pip3 install -r requirements.txt
+    ```
+
+5. Run for debugging and development: (it will reload app on code changes and enable debug mode)
+
+```sh
+export FLASK_APP=application.py
+flask run --debug
+```
+if you want to autorestart you app on Flask changes, you can do `export FLASK_DEBUG=1`. In case of `Import Error` run `pip3 install --upgrade watchdog`.
+By default, this should be run by Prismo admin process, but for debugging purpose you should run this commands by
+yourself.
+
+## Config handling
+By default, PRISMO searches for a file named `config_default.json` inside 
+the `/app` directory. This is suitable for development purposes, but for 
+production deployments, you should specify your own configuration file and
+pass its path as the `PRISMO_CONFIG` environment variable. When running
+PRISMO in a Docker container, this path is specified in the `Dockerfile` 
+like so:
+
+```commandline
+ENV PRISMO_CONFIG=/app/external/config_docker.json
+```
+In this example, the path `app/external/config_docker.json` is relative to 
+the container's internal directory and mapped from an external directory 
+(see the following paragraph for details).
+
+## Database
+
+All information about the database is stored in [doc/database.md](docs/database.md) file.
+
+## API
+
+The docs for API is stored in [docs/api.md](docs/api.md) file.
+
+## Slack
+
+Slack integration works with slack bot. You need to create slack bot in your slack workspace and get token for it.
+Scope:
+
+- chat:write
+- files:write
+- incoming-webhook

docs/docker.md

@@ -1,9 +1,28 @@
 Docker tips and tricks
 ================================================
 
-Some problems, which can occurs during work with docker.
+## Running in `Docker`
 
-Use official documentaion for installation on desktop.
-https://docs.docker.com/engine/install/ubuntu/
+Running PRISMO in a separate Docker container offers several advantages. It 
+isolates data and ensures a well-defined environment for smooth operation. 
+You can verify everything is ready for Docker deployment by running the
+following command:
+```commandline
+$ docker build --no-cache -t prismo-app .
+```
+This command build a container and sets all environment variables from dockerfile.
+```commandline
+$ docker run --name=prismo-app -p 80:5000 --restart always --detach -v "$(pwd)/data/:/app/external/" prismo-app
+```
+This command runs the newly built container and starts the server on port 80. Note that on some systems, port 80 might be 
+unavailable for non-privileged users. For development purposes, you can use 
+the alternative mapping \`5000\:5000\` instead\.
+As shown in the command, the `-v "</span>(pwd)/data/:/app/external/"` 
+option mounts an external volume where you should store your `database.db` 
+and `config_docker.json` files. This volume persists data and configuration 
+outside the container, ensuring they are not lost even if the container is 
+deleted.
 
-To be continued....:)
+**Additional Notes:**
+
+- Remember to replace the placeholder values for environment variables like `DATABASE_URL` and `SECRET_KEY` with your actual settings in the example commands.

docs/rpi_installation_instructions.md

@@ -0,0 +1,50 @@
+Installing PRISMO Access System on Raspberry Pi OS
+==================================================
+## Prerequisites:
+
+* Raspberry Pi device
+* Raspberry Pi Imager tool(https://www.raspberrypi.com/software/)
+* Internet connection
+
+## Raspberry Pi OS installation
+
+Install Raspberry Pi OS as usual:
+* Use the Pi Imager tool to flash Raspberry Pi OS onto a microSD card.
+* During the initial setup, press "Edit settings" in the "Use OS customization?" dialog.
+* Set the hostname to "prismo" (or your preferred hostname).
+* Configure the Wi-Fi settings correctly.
+
+![Customization settings](images/customization_settings.png "customization settings")
+
+
+* Insert the microSD card and power on the Raspberry Pi.
+
+## Install Docker and Docker Compose:
+
+* Open a terminal window and run the following command:
+```commandline
+curl -sSL https://get.docker.com | sh
+```
+
+* Add the current user to the docker group:
+```commandline
+sudo usermod -aG docker ${USER}
+```
+
+* Reboot the Raspberry Pi:
+```commandline
+sudo reboot
+```
+
+* Clone the PRISMO Repository and run docker script:
+
+```commandline
+git clone https://github.com/hacklabkyiv/prismo.git
+cd prismo
+./docker-run.sh
+```
+
+
+* Access PRISMO: Open a web browser on your computer or mobile device.
+Navigate to the address `prismo.local` (or the hostname you set).
+You should see the PRISMO entry screen.