diff --git a/README.md b/README.md index d250496..2cd54d9 100644 --- a/README.md +++ b/README.md @@ -9,146 +9,16 @@ 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. +## 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) -## 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: +## Reader hardware build -```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). +Readers itself has their own repository and building instructions, +follow [repo](https://github.com/hacklabkyiv/prismo-reader) to build your own beautiful reader. -## Running in `Docker` +## Reader software flashing -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. +Flashing reader is performed from Raspberry Pi itself...(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. - -## Installation by docker - -- 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: - -```bash -docker run --name=prismo-app -p 80:5000 --restart always --detach -v "$(pwd)/data/:/app/external/" hacklabkyiv/prismo-app:0.1.7 -``` - -Add docker to autostart: - -```bash -sudo systemctl enable docker -``` - -The application ready to work and available on `http://localhost:5000` - -### The reader firmware - -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). - -## Development - -### 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. - -## 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/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/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