INSTALLATION WALKTHROUGH

3 minute read

Warning

You need to install Apiviz-backend to enjoy Apiviz-frontend to serve your configuration to the frontend.

Build and run

You have two different options to run (locally) Apiviz on your computer/server : with Python or with Docker, depending where your heart leans…

WITH DOCKER (locally or in production)

  • locally - in your browser check this url
    • install Docker (here for mac OS)
    • clone or download the repo
    • install MongoDB locally/on your server or get the URI of the MongoDB you’re using
    • go to your apiviz folder
    • launch docker and run : 
        make up
    • check the following URL in your browser : 
      http://localhost:8100
  • in production
    • install Docker on your server (here for Ubuntu 18) 
      sudo apt-get update
sudo apt-get remove docker docker-engine docker.io
sudo apt install docker.io
sudo systemctl start docker
sudo systemctl enable docker
    • set up UFW, GIT, NGINX, …
    • (optional) install MongoDB (if the ApiViz’s DB for config is hosted on your own server)
    • add the github repo
    • create and set of secret env variables at the project’s folder root based on example.env.global and example.env.mongodb
    • lauch docker and run the command : 
      make up-prod
    • test the following url in your browser : http://localhost:8100/backend/api/config/global?uuid=c5efafab-1733-4ad1-9eb8-d529bc87c481

WITHOUT DOCKER - LOCALLY

  1. clone or download the repo
  2. install MongoDB locally or get the URI of the MongoDB you’re using
  3. go to your apiviz folder
  4. install python pip and virtualenv 
     sudo apt install python-pip
 sudo apt install virtualenv
  5. install a virtual environment 
     virtualenv -p python3 venv
 source venv/bin/activate

  6. install the libraries

     sudo pip install -r requirements.txt
  7. optional : update the example.env.mongodb file with your mongoDB URI (if you’re not using default mongoDB connection

  8. Go to your app folder and run :

     python run_apiviz.py
  9. optional : you can also use some variables in the command line : 
     # get the list of available CLI options
 python run_apiviz.py --help

 # for example : run with a custom port number in testing mode
 python run_apiviz.py --port=8200 --mode=preprod
  10. test the following url in your browser : http://localhost:8081/backend/api/config/global?uuid=c5efafab-1733-4ad1-9eb8-d529bc87c481

WITHOUT DOCKER - IN PRODUCTION

  1. get a server - check digital ocean, OVH, …
  2. optionnal : get a domain name : check OVH, namecheap, godaddy…. + setup DNS
  3. follow (most of) these instructions
  4. create and set of secret env variables at the project’s folder root based on example.env.global and example.env.mongodb
  5. go to app folder and create a virtual env (for instance called “venv”)

  6. set up the gunicorn service and NGINX with supervisor

  7. … pray for all that to work as expected, and keep calm…

  8. update code and (re-)deploy

     cd /var/www/apiviz.net
 git pull origin master

 # start app with supervisor
 sudo supervisorctl start toktok

Environment variables

the .env files

The environment variables are stored in a couple of files at the root of the project :

  • example.env.global
  • example.env.mongodb
  • example.env.superadmins

If you want or need to use Apiviz in production you will have to duplicate those files at the same level with those new names :

  • .env.global
  • .env.mongodb
  • .env.superadmins

… then you will be able to change the environment variable you want and begin to use all of the available arguments like :

# with Docker
make up-prod

# with Python only
python run_apiviz.py mongodb=distant mode=dev_email

# with Gunicorn
gunicorn wsgi_prod:app --bind=0.0.0.0:4100

the variables

At the CLI level you can use :

@click.option('--mode',     default="default",     nargs=1,  help="The <mode> you need to run the app : default | testing | preprod | production" )
@click.option('--docker',   default="docker_off",  nargs=1,  help="Are you running the app with <docker> : docker_off | docker_on" )
@click.option('--mongodb',  default="local",       nargs=1,  help="The <mongodb> you need to run the app : local | distant | server" )
@click.option('--auth',     default="default",     nargs=1,  help="The <auth> mode you need to run the app : default | default_docker | server | server_docker | distant_preprod | distant_prod" )
@click.option('--host',     default="localhost",   nargs=1,  help="The <host> name you want the app to run on : <IP_NUMBER> " )
@click.option('--port',     default="8100",        nargs=1,  help="The <port> number you want the app to run on : <PORT_NUMBER>")
@click.option('--https',    default="false",       nargs=1,  help="The <https> mode you want the app to run on : true | false")

Within the .envfiles you can change the following variables :

  • example.env.global
RUN_MODE=default
DOCKER_MODE=docker_off
AUTH_MODE=default
HTTPS_MODE=false

### FLASK RELATED 
DEBUG=true
TESTING=true
DOMAIN_ROOT=localhost
DOMAIN_PORT=8100
SECRET_KEY=app_very_secret_key
SERVER_NAME_TEST=True

### MONGO DB RELATED
MONGODB_MODE=local
  • example.env.mongodb
### to build mongodb URI
MONGO_ROOT_LOCAL=localhost
MONGO_ROOT_DOCKER=host.docker.internal
MONGO_PORT_LOCAL=27017

MONGO_DBNAME=apiviz
MONGO_DBNAME_TEST=apiviz-test
MONGO_DBNAME_PREPROD=apiviz-preprod
MONGO_DBNAME_PROD=apiviz-prod

MONGO_ROOT_SERVER=127.0.0.1
MONGO_PORT_SERVER=27017
MONGO_USER_SERVER=MY-MONGODB-SERVER-USERNAME
MONGO_PASS_SERVER=MY-MONGODB-SERVER-USER-PASSWORD
MONGO_OPTIONS_SERVER=?MY-MONGODB-SERVER-OPTIONS

### for instance on MongodbAtlas
MONGO_DISTANT_URI=mongodb://<DISTANT-USERNAME>:<DISTANT-PASSWORD>@<DISTANT-HOST>:<DISTANT-PORT>
MONGO_DISTANT_URI_OPTIONS=?ssl=true&replicaSet=<REPLICA-SET>&authSource=admin&retryWrites=true


### collections
MONGO_COLL_CONFIG_GLOBAL=config_global
MONGO_COLL_CONFIG_NAVBAR=config_navbar
MONGO_COLL_CONFIG_TABS=config_tabs
MONGO_COLL_CONFIG_APP_STYLES=config_app_styles
MONGO_COLL_CONFIG_DATA_ENDPOINTS=config_data_endpoints
MONGO_COLL_CONFIG_ROUTES=config_routes
MONGO_COLL_CONFIG_FOOTER=config_footer
MONGO_COLL_CONFIG_SOCIALS=config_socials

You May Also Enjoy