diff --git a/README.md b/README.md index d250496..6eb8f41 100644 --- a/README.md +++ b/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 "(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 git@github.com: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: --push . -``` diff --git a/config_docker_default.json b/data/config_docker.json similarity index 100% rename from config_docker_default.json rename to data/config_docker.json diff --git a/docker-compose.yml b/docker-compose.yml index c76f602..35266e5 100644 --- a/docker-compose.yml +++ b/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 diff --git a/docker_run.sh b/docker_run.sh index 6803f86..9d93ce4 100755 --- a/docker_run.sh +++ b/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 diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..5aebfab --- /dev/null +++ b/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 git@github.com: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 \ No newline at end of file diff --git a/docs/docker.md b/docs/docker.md index c4472cc..a8e81d9 100644 --- a/docs/docker.md +++ b/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 "(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....:) \ No newline at end of file +**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. diff --git a/docs/images/access_denied.webp b/docs/images/access_denied.webp new file mode 100644 index 0000000..73bb08c Binary files /dev/null and b/docs/images/access_denied.webp differ diff --git a/docs/images/access_granted.webp b/docs/images/access_granted.webp new file mode 100644 index 0000000..5a34ea8 Binary files /dev/null and b/docs/images/access_granted.webp differ diff --git a/docs/images/add_user.png b/docs/images/add_user.png new file mode 100644 index 0000000..04f8c26 Binary files /dev/null and b/docs/images/add_user.png differ diff --git a/docs/images/customization_settings.png b/docs/images/customization_settings.png new file mode 100644 index 0000000..26dc929 Binary files /dev/null and b/docs/images/customization_settings.png differ diff --git a/docs/images/flash_reader.png b/docs/images/flash_reader.png new file mode 100644 index 0000000..174f1e3 Binary files /dev/null and b/docs/images/flash_reader.png differ diff --git a/docs/images/flash_reader.webp b/docs/images/flash_reader.webp new file mode 100644 index 0000000..befb005 Binary files /dev/null and b/docs/images/flash_reader.webp differ diff --git a/docs/images/gen_photo.jpg b/docs/images/gen_photo.jpg new file mode 100644 index 0000000..8b1b98e Binary files /dev/null and b/docs/images/gen_photo.jpg differ diff --git a/docs/images/wifi_settings.png b/docs/images/wifi_settings.png new file mode 100644 index 0000000..dca30dd Binary files /dev/null and b/docs/images/wifi_settings.png differ diff --git a/docs/rpi_installation_instructions.md b/docs/rpi_installation_instructions.md new file mode 100644 index 0000000..4e56ef4 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 479aacc..f8623e7 100644 --- a/requirements.txt +++ b/requirements.txt @@ -15,5 +15,5 @@ slack-bolt # Used by reader flasher script intelhex pyserial -adafruit-ampy +rshell esptool