Extensive user documentation is available at either of the following sites:
- Change directory to
PATHwhere you want to clone:cd PATH - Clone:
git clone https://github.com/PMA-2020/pma-api.git
A Python virtual environment is a way to isolate applications and their dependencies from one another in order to avoid conflicts. We recommend that you install virtualenv. The virtualenv documentation has installation steps as well as more information about the usefulness of virtual environments. Here's a summary of the installation steps:
- Install
virtualenvglobally:python3 -m pip install virtualenv - Change directory to where
pma-apiwas cloned:cd PATH/pma-api - Create a virtual environment called
env:virtualenv env - Use the virtualenv every time you want to work on the project
4a. Activate the virtuale environment:
cd PATH/pma-api&&source env/bin/activate4b. Deactivate when you're done. You can do this by closing the terminal session, or running:deactivate
python3 -m pip install -r requirements.txt
You can use a command line interface (e.g. psql) or graphical user interface (e.g. PgAadmin4) to set up the DB.
i. Create database a called 'pma-api'. CREATE DATABASE pma-api;
ii. Create a user called 'pma-api'. CREATE USER pma-api;
iii. Set a password for this user, by default 'pma-api'. You can change this later. ALTER USER pma-api WITH PASSWORD 'pma-api';
iv. Make user 'pma-api' a super user for DB 'pma-api'. GRANT ALL PRIVILEGES ON DATABASE pma-api TO pma-api;
a. Virtualenv setups: After installing the virtual environment, you should have a folder called env. Open up env/bin/activate in a text editor. Add the following text to the bottom of the file.
export ENV_NAME="development"
export DATABASE_URL="postgresql+psycopg2://pmaapi:pmaapi@localhost/pmaapi"
export STAGING_URL="http://api-staging.pma2020.org"
export PRODUCTION_URL="http://api.pma2020.org"b. Virtualenvwrapper setups: Add the following to your postactivate script. This is found in the root directory of wherever you installed virtualenvwrapper. Also, the text below assumes that you named your virtual environment "pma-api". If you are using virtualenvwrapper and named it something else, replace the text "pma-api" with whatever you named your environment.
if [ "$VIRTUAL_ENV" = "path/to/virtualenvs/pma-api" ]; then
export ENV_NAME="development"
export DATABASE_URL="postgresql+psycopg2://pmaapi:pmaapi@localhost/pmaapi"
export STAGING_URL="http://api-staging.pma2020.org"
export PRODUCTION_URL="http://api.pma2020.org"
fiSeed data into DB makefile command: make db. If you are on a Windows system or another system that cannot run makefiles, you can open up the makefile in a text editor and use it as a reference to run common commands. In the case of "make db", the equivalent command will be: python3 manage.py initdb --overwrite. This will execute a script that populates a database using data taken from the data directory.
After running the command to seed data into DB, check the terminal to see if it was a success. If you do not see any error messages and one of the last lines says "COMMIT", this means the process was probably successful.
- Run
pma-apion a local server process via the following makefile command:make serve. The equivalent command is:python3 manage.py runserver. - Verify that it is running in the browser by going to:
http://localhost:5000/v1/resources
You can: i. Navigate the API further by either (a) utilizing the URL links shown in the browser, or (b) looking at the available endpoints in the pma-api documentation. ii. Read the pma-api documentation for more information on use.
Run: make push-staging
Run: make push-production