readme.md

PROTON

The MIC stack genesis!

Proton is a high-level Python framework that facilitates rapid server-side development with clean & pragmatic design. Thanks for checking it out!

• Proton aims at easing server-side development for all Python enthusiasts.
• Proton bootstraps templated backend by relying on code generating code with minimum dev effort.
• A few CLI commands to setup production ready server side stack with managed DB connections (Proton ships with postgresql), managed caching (Proton ships with redis), managed JWT authenticated routes, descriptive logging, managed monitoring (Prometheus & Grafana) and auto-generated openAPI specs.
• Automates signup & login with necessaary validations.
• All of this, containerised

Anatomy

Getting Started

• Install latest version of docker on your development machine/server.
  • Linux - https://docs.docker.com/install/linux/docker-ce/ubuntu/
  • Mac - https://docs.docker.com/docker-for-mac/install/
  • Windows - https://docs.docker.com/docker-for-windows/install/
• Install latest version of docker-compose on your development machine/server (https://docs.docker.com/compose/install/)
• Clone git clone https://github.com/1x-eng/PROTON.git & Change directory cd ~/PROTON/`
• ./cproton.sh -U yes, please comply to CLI prompts(Use absolute address; not relative for file paths)
• Wait for the platform to bootstrap; once done, visit http://localhost:3000.
• Congratulations. you've got your server-side setup!

Features

• Proton comes with out-of-box support for Signup and Login.
• Use /signup route to sign up users to platform.
• You could swap db by changing db_flavor in POST payload. Supports sqlite & postgresql.
• signup and login validation for free. For example - What happens if someone tries to signup with the same email / username?
• Use '/login' route to login after successful signup.
• See the token post successful login - That one command to setup the platform has prepared JWT Token Authentication with minimum dev effort.
• Prometheus & grafana leveraged for monitoring purposes
• Ships with a few grafana dashboards out-of-the-box. Visit localhost:3000/proton-grafana in your favourite browser and login with default credentials:
  • username: admin
  • password: admin
  • You'll be prompted to change and choose your own strong password on first login.
  • Proton Monitor
  • Proton Stack - Holistic Monitor

The MIC stack - What, why & how?

Proton facilitates rapid API development (the Model Interface Controller stack) with templated code generated by a few CLI commands.

Why do we need this despite many zillion frameworks? Potentially, to help get away from some of these boring tasks:

• writing; rather, re-writing same boiler plate code everytime you wanted to generate a new API using the framework of your choice
• managing database connectivity and dealing with connectivity issues everytime you touch codebase
• configuring cacheing & performance tuning
• configuring logging & monitoring
• authentication & authorization
• container ready backend

Getting Started

• Generate new API (you can do all CRUD ops on that API) by this one command ./cproton.sh -n myNewApi

  • what you see above is an API endpoint auto-generated for the MIC name you provided.
  • a get route, post route and concurrency route.
  • GET call:
  • 
  • POST call:
  • 
  • And, if you wanted to target sqlite, just change db_flavour of your POST JSON payload to sqlite.
  • 
  • GET call involving Concurrency / Multi-threading
  • 
    • Notice how first call took about 1 second (if not for multi-threading, this takes about 5 seconds) and subsequent calls took only 25~35ms. Thanks for cacheing.

• For every new MIC stack that you create (via cproton.sh -s <your_api_name>), Proton generates a dedicated controller (to drive CRUD ops):

  • Example:

• Deploy using ./cproton.sh -s yes

  • Notice how the route considers id as a query parameter and results comply to this query parameter.
  • Results from this route also automatically get the best of PROTON in terms of cache support, logging etc.,

• Deleting made easy, while separating concerns.

  • Notice how login and signup routes remain unaffected. Similarly, if there were other MIC stacks and you destroyed one of them, all others remain as is; unaffected.

• Access logs here - ./PROTON/trace

• OpenAPI specs out-of-the-box

Miscellaneous

Automated Backup & Restoration

• Proton also ships with an ability to backup vitals (secrets + db volume mounts) to cold storage (Dropbox)

• To initiate backup,

  • Create a dropbox account for yourself and create an app - https://www.dropbox.com/developers/apps
    • An example would be:
      • API type - Dropbox API
      • Type of data access as "App folder - Access to a single folder created specifically for your app"
      • App name as "PROTON Backup"
      • Create App & then click on "Generate access token". You'll need this token later.
  • With your access token handy, now navigate to backup folder in Proton home directory.
  • Initiate backup using ./scripts/proton_backup_orchestrator.sh
  • Comply with command line prompts and provide access token when asked for.
  • There is an audit trail just in case. You may cat those reports available under backup/reports folder.

• Similar to backups, Proton also ships with ability to restore from remote dropbox location to your local machine or remote server.

• In order to initiate restoration, ensure you have the access token handy for your remote backup folder and navigate to backup folder.

  • Initiate restoration using ./scripts/proton_restore.sh

Deployment Instructions - (Tested on Ubuntu-18.04LTS)

• If you have a pre-configured DNS handy, use ./deployer.sh -d <your_dns>
• If you wanted to run the platform for the first time and ok to proceed with defaults; then use: ./deployer.sh -a yes
• If you were using Proton's backup services, to kickstart restoration use this: ./deployer.sh -r yes

Prefer manual approach? This could help:

• [Step - 1] Install Docker and Docker-Compose

    sudo apt-get update
    sudo apt-get install -y docker
    sudo apt-get install -y docker-compose

• [Step - 2] Enable USER to run docker

    sudo groupadd -e docker
    sudo gpasswd -a ${USER} docker
    newgrp docker

• [Step - 3] Install NGINX and configure HTTP reverse proxy

    sudo apt-get update
    sudo apt-get install -y nginx
    unlink /etc/nginx/sites-enabled/default
    cd /etc/nginx/sites-available
    cat <<EOT > reverse-proxy.conf
    server {
                    listen 80;
                    listen [::]:80;
                    server_name <dns here>;
    
                    access_log /var/log/nginx/reverse-access.log;
                    error_log /var/log/nginx/reverse-error.log;
    
                    location / {
                                proxy_pass http://127.0.0.1:3000;
                }
            }
    EOT
    ln -s /etc/nginx/sites-available/reverse-proxy.conf /etc/nginx/sites-enabled/reverse-proxy.conf
    sudo nginx -t
    sudo service nginx restart

• [Step - 4] Configure HTTPS in NGINX reverse proxy

    sudo apt-get update
    sudo apt-get install -y software-properties-common
    sudo add-apt-repository ppa:certbot/certbot -y
    sudo apt-get update
    sudo apt-get install -y python-certbot-nginx
    sudo certbot --nginx --non-interactive --agree-tos -m <email> -d <dns eg. temp.com here>

• [Step - 5] Grant permission to PROTON Stack

    cd ~/PROTON
    sudo chmod 777 -R ./

• Start Proton stack using - ./cproton.sh -U yes

Credits

PROTON is a product of Adroit Software Corporation (ABN 426 3819 0066) (https://adroitcorp.com.au)

License

BSD 3-Clause License

Copyright (c) 2018, Pruthvi Kumar & Adroit Software Corporation (https://www.adroitcorp.com.au) All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

• Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.