Skip to content

Latest commit

 

History

History
266 lines (186 loc) · 10.9 KB

INSTALL_AND_RUN.md

File metadata and controls

266 lines (186 loc) · 10.9 KB
Raw

Installing and Running PANIC

This page will guide you through the steps required to get PANIC up and running, including the Web UI and the installation of dependencies and preliminaries. Some steps are optional.

We recommend that PANIC is installed on a Linux system, given the simpler installation and running process. Nevertheless, instructions on how to install the alerter on a Windows system are also provided.

Requirements

The major requirements to run the alerter are Python 3 and the Polkadot API Server. However, to unlock the full potential of the alerter, we recommend that you install or set up as many of the below requirements as possible:

  • Python v3.7.4+ with pip package manager and pipenv packaging tool.
  • The Polkadot API Server
  • Optional: Telegram account and bots, for Telegram alerts and commands.
  • Optional: Twilio account, for highly effective phone call alerts.
  • Optional: Redis server, to keep a backup of the alerter state and to have some control over the alerter such as to snooze phone call alerts using Telegram commands. Redis will also be used to get real-time data in the UI dashboard.
  • Optional: MongoDB, to store any alert that is generated by PANIC. These alerts will then be shown in real-time in the Web UI alerts log page.

If you want to make use of the Web UI (which we highly encourage you to do so), MongoDB and Redis are not optional. In addition to this, you must also install Node.js v12.16.2+ and npm v6.14.4+ (links below):

Install

  • Python (with pip and pipenv): Follow this guide to install Python, pip and pipenv.
  • Polkadot API Server: If you haven't already installed the Polkadot API Server, follow the guides here.
  • Telegram: Click here if you want to set up a Telegram account with bots.
  • Twilio: Click here if you want to set up a Twilio account.
  • Node.js and npm: Click here if you want to install Node.js and npm.
  • Redis server: Click here if you want to set up a Redis server.
  • MongoDB: Click here if you want to set up MongoDB.

Running PANIC

Start by cloning the panic_polkadot repository and navigating into the directory:

git clone https://github.com/SimplyVC/panic_polkadot
cd panic_polkadot

The next step is to decide whether you want to run PANIC using docker or from source.

Running from Source

Running the Web UI

First start by setting up the UI as described here.

Continue by navigating into the UI directory and installing the packages defined in package.json

cd src/web/ui
npm ci --only=production                  # use sudo in linux if necessary

Build the UI, re-direct to the PANIC Polkadot directory, and start the UI.

npm run-script build                      # use sudo in linux if necessary
cd ../../../
bash run_ui_server.sh                     # use sudo in linux if necessary

By default the UI will start on port 9000. If you wish to modify it, change the port number inside the panic_polkadot/run_ui_server.sh file.

You should now access the UI with your authentication details.

Running the Alerter

You can now proceed by setting up the alerter using this guide.

After setting-up you will be glad to find out that running the alerter is a breeze. To start up the alerter simply run the following commands in the project directory:

pipenv sync                               # use sudo in linux if necessary
pipenv run python run_alerter.py          # use sudo in linux if necessary
# If multiple versions of Python are installed, the python executable may be `python3.6`, `python3.7`, etc.

Assuming that the setup process was followed till the end, the above commands will start up all of the necessary node, blockchain, and GitHub monitors. These will all start monitoring (and alerting) immediately.

It is recommended to check the console output or general log to make sure that all monitors started-up. Alternatively, you can use the Web UI by confirming that the data is being updated in the dashboard.

Running the UI and Alerter as a Linux Service (Optional)

Running a program as a service means that it starts up automatically on boot and restarts automatically if it runs into some issue and stops running. To do so, we recommend the following steps:

# Add a new user to run the UI and alerter
sudo adduser <USER>

# Grant permissions
sudo chown -R <USER>:<USER> <PANIC_DIR>/                     # ownership of alerter
sudo chmod -R 700 <PANIC_DIR>/logs                           # write permissions for logs
sudo chmod -R 700 <PANIC_DIR>/src/web/ui/sessions            # write permissions for session files
sudo chmod +x <PANIC_DIR>/run_alerter_setup.py               # execute permission for runner (1)
sudo chmod +x <PANIC_DIR>/run_ui_setup.py                    # execute permission for runner (2)
sudo chmod +x <PANIC_DIR>/run_alerter.py                     # execute permission for runner (3)
sudo chmod +x <PANIC_DIR>/run_ui_server.sh                   # execute permission for runner (4)

# Create virtual environment using pipenv
cd <PANIC_DIR>
su <USER> -c "pipenv sync"

The service file for the UI will now be created:

# Create the service file
sudo nano /etc/systemd/system/panic_ui.service

It should contain the following, replacing <USER> with the created user's name and <PANIC_DIR> with PANIC's installation directory.

[Unit]
Description=PANIC UI
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
User=<USER>
TimeoutStopSec=90s
WorkingDirectory=<PANIC_DIR>/
ExecStart=/bin/bash run_ui_server.sh

[Install]
WantedBy=multi-user.target

The service file for the alerter will now be created:

# Create the service file
sudo nano /etc/systemd/system/panic_alerter.service

It should contain the following, replacing <USER> with the created user's name and the two <PANIC_DIR> with PANIC's installation directory. This assumes that pipenv is found under /usr/local/bin/pipenv and that the Python executable is python (if multiple versions of Python are installed, the python executable may be python3.6, python3.7, etc.). We recommend that you run the command set for ExecStart manually to check that it works before starting the service.

[Unit]
Description=PANIC
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
User=<USER>
TimeoutStopSec=90s
WorkingDirectory=<PANIC_DIR>/
ExecStart=/usr/local/bin/pipenv run python <PANIC_DIR>/run_alerter.py

[Install]
WantedBy=multi-user.target

Lastly, we will enable and start the services:

sudo systemctl enable panic_ui.service
sudo systemctl enable panic_alerter.service
sudo systemctl start panic_alerter.service
sudo systemctl start panic_ui.service

Check out systemctl status panic_ui or journalctl -f -u panic_ui.service to confirm that the UI is running.

Check out systemctl status panic_alerter or the logs in <PANIC_DIR>/logs/ to confirm that the alerter is running. Alternatively, if you set up Telegram, try interacting with the Telegram bot (using /help).

Run using Docker

Important: If you are choosing to run PANIC using docker, then the Web UI, MongoDB and Redis must also run using Docker if you want to use them.

To run PANIC using Docker, you will first need to install Docker along with Docker-Compose. You will then obtain the Docker images and run everything.

At any stage, you can use the command docker ps to confirm that the installed component (Redis, MongoDB, the UI and alerter) is running

Installing Docker and Docker Compose on your Machine

To install Docker and Docker Compose on your machine, follow this guide

Running MongoDB

Since you chose to run PANIC using Docker, it is important that if you are going to use MongoDB, it is also run inside a Docker container.

To install MongoDB using docker please run the following command inside the project directory:

docker-compose up -d mongo

By default, the above command will run MongoDB on port 27017. If you would like to run MongoDB on some other port please change the MONGO_HOST_PORT value inside the panic_polkadot/.env file.

Running Redis

Since you chose to run PANIC using Docker, it is important that if you are going to use Redis, it is also run inside a Docker container.

To install Redis using Docker, please run the following command inside the project directory:

docker-compose up -d redis

By default, the above command will run Redis on port 6397. If you would like to run Redis on some other port please change the REDIS_HOST_PORT value inside the panic_polkadot/.env file.

Running the Web UI

First start by setting up the UI as described here.

Obtaining Docker Image

This part can be done in either of two ways, either by building the docker image yourself, or by downloading it from Docker Hub

Option 1: Building The Docker Image

Run the following command to build the image:

docker-compose build ui

Option 2: Downloading the Pre-Built Docker Image from Docker Hub

The pre-built Docker image can simply be downloaded by running the following command:

docker pull simplyvc/panic_polkadot_ui:2.4.0
Running the Docker Image

Now that the Docker image is on your machine, you can run it as follow:

docker-compose up -d ui

By default, the above command will run the UI on port 9000. If you would like to run the UI on some other port please change the UI_HOST_PORT value inside the panic_polkadot/.env file.

You should now access the UI with your authentication details.

Running the Alerter

Having installed and executed the necessary components for PANIC, you can now proceed by setting up PANIC using this guide.

Important note: the redis host parameter set inside config/user_config_main.ini must be the full IP (local or external) of the machine running the Redis container, and not localhost. This also applies to the Mongo host and the API polkadot_api_endpoint parameters.

Obtaining Docker Image

This part can be done in either of two ways, either by building the docker image yourself, or by downloading it from Docker Hub

Option 1: Building The Docker Image

Run the following command to build the image:

docker-compose build alerter

Option 2: Downloading the Pre-Built Docker Image from Docker Hub

The pre-built Docker image can simply be downloaded by running the following command:

docker pull simplyvc/panic_polkadot:2.4.0
Running the Docker Image

Now that the Docker image is on your machine, you can run it as follow:

docker-compose up -d alerter

Back to front page