amivapi

AMIV API is a Python-EVE based REST interface to manage members, events, mail forwards, job offers and study documents for a student organisation. It was created by AMIV an der ETH to restructure the existing IT infrastructure. If you are not from AMIV and think this is useful feel free to fork and modify.

Deploy using Docker

AMIV API is available as a docker container. If you do not have mongodb, you can also use docker to quickly start a database with the default settings used by AMIV API:

# Create a network s.t. database and api can communicate
docker network create --driver overlay backend
docker service create \
    --name mongodb -p 27017:27017 --network backend\
    -e MONGODB_DATABASE=amivapi \
    -e MONGODB_USERNAME=amivapi \
    -e MONGODB_PASSWORD=amivapi \
    bitnami/mongodb

Next, create a configuration with (at least) the mongodb credentials and save it as amivapi_config.py (or choose another name).

MONGO_HOST = 'mongodb'  # Use the name of your mongodb service
MONGO_PORT = 27017
MONGO_DBNAME = 'amivapi'
MONGO_USERNAME = 'amivapi'
MONGO_PASSWORD = 'amivapi'

Finally, create API service and give it access to the config using a docker secret:

# Create secret
docker secret create amivapi_config <path/to/amivapi_config.py>

# Create new API service with secret
# Map port 80 (host) to 8080 (container)
docker service create \
    --name amivapi  -p 80:8080 --network backend \
    --secret amivapi_config \
    amiveth/amivapi

If you want to use a different name for the secret (or cannot use secrets and have to mount the config manually), you can use the environment variable AMIVAPI_CONFIG to set the config path in the API container.

Installation

You need to have mongodb installed and running.

You should also use a virtual environment.

Clone and install AMIV API:

git clone https://github.com/amiv-eth/amivapi.git
cd amivapi
pip install -r requirements.txt

This will also install amivapi in editable mode (take a look at requirements.txt if you are curious) which allows us to use the command line interface of amivapi:

# Run a development server
amivapi run
# Get help, works for sub-commands as well
amivapi --help
amivapi run --help

Running in Production

If you want to use AMIV API properly behind a webserver, e.g. Apache or Nginx with uwsgi, you need to create a file, e.g. app.py, with the following content:

from amivapi import create_app

app = create_app()

Configuration

Now it's time to configure AMIVAPI. Create a file config.py (you can choose any other name as well) with the following content:

# Root password, *definitely* change this!
ROOT_PASSWORD = 'root'

# MongoDB Configuration
MONGO_HOST = 'localhost'
MONGO_PORT = 27017
MONGO_DBNAME = 'amivapi'
MONGO_USERNAME = ''
MONGO_PASSWORD = ''

# Mailing lists for groups (optional, uncomment if needed)
# MAILING_LIST_DIR = '/directory/to/store/mailing/list/files/'
    
# Remote mailings list files via ssh (optional)
# REMOTE_MAILING_LIST_ADDRESS = 'user@remote.host'
# REMOTE_MAILING_LIST_KEYFILE = ''
# REMOTE_MAILING_LIST_DIR = './'

# SMTP configuration for mails sent by AMIVAPI (optional)
# API_MAIL = 'api@amiv.ethz.ch'
# SMTP_SERVER = 'localhost'
# SMTP_PORT = '587'
# SMTP_USERNAME = ''
# SMTP_PASSWORD = ''

# LDAP connection (special LDAP user required, *not* nethz username & password)
# LDAP_USERNAME = ''
# LDAP_PASSWORD = ''

AMIV API looks for a configuration in the following order:

If using create_app, you can name the file explicitly:

app = create_app(config_file="/path/to/your/config.py")

If no file is specified, you can use the AMIVAPI_CONFIG environment variable:
```
$set AMIVAPI_CONFIG path/to/your/config.py
```
If no environment variable is specified either, AMIV API checks for a file name config.py in the current working directory

For amivapi run and all other amivapi commands you can also specify a config, see amivapi <command> --help, e.g. amivapi run --help

Running The Tests

Create a test user test_user with password test_pw in the test_amviapi database, which will be used for all tests.

mongo test_amivapi --eval \
'db.createUser({user:"test_user",pwd:"test_pw",roles:["readWrite"]});'

Install the test requirements:

pip install pytest tox

To run all tests:

tox

To run tests based on a keyword:

tox -- -k <keyword>

To run just one python version:

tox -e py36

Integration Tests

The integration tests for ssh mailing list creation and LDAP require additional information to be run, which should not be published. By default, these tests are skipped, as you can see in the tox summary.

SSH

Set the following environment variables:

SSH_TEST_ADDRESS, e.g. user@remote.host
SSH_TEST_KEYFILE(optional): file containing a key that is authorized to access the server
SSH_TEST_DIRECTORY(optional): Directory on remote server where test files are stored. Uses /tmp/amivapi-test/ by default

LDAP

LDAP_TEST_USERNAME and LDAP_TEST_PASSWORD (not your nethz, special LDAP account required)
LDAP_TEST_USER_NETHZ (required to test user import) The test will return the imported user data, be sure to verify it
LDAP_TEST_USER_PASSWORD (required to test user login)

Additionally, you need to be inside the ETH network, e.g. using a VPN, otherwise the ETH LDAP server can't be reached. Furthermore be patient, as the LDAP tests take a little time to complete.

Problems or Questions?

For any comments, bugs, feature requests please use the issue tracker, don't hasitate to create issues, if we don't like your idea we are not offended.

If you need help deploying the API or creating a client, feel free to message us at api@amiv.ethz.ch

guilhermaker/amivapi