gferraro/cacophony-api

API server where Cacophony Project recordings are stored & managed

cacophony-api

cacophony-api is a Node server that provides an REST API server for uploading, processing and retrieving media collected for the Cacophony Project. This server used to be known as "Full_Noise".

License

This project is licensed under the Affero General Public License (https://www.gnu.org/licenses/agpl-3.0.en.html).

Running the server

For development and testing purposes it is easiest to run cacophony-api using Docker. To do this:

• Ensure your user account is set up to run commands as root using sudo.
• Ensure the Docker is installed (sudo apt install docker.io on Ubuntu)
• Run cacophony-api using ./run

This will build a Docker container which includes all the services that cacophony-api relies on and then runs the container. The end result is a fully functioning API server. The container name is "cacophony-api".

The first time ./run is used will be somewhat slow as dependencies are downloaded. Future executions are quite fast as Docker caches the images it creates.

Once the container is running, you can start a bash session inside the container with docker exec -it cacophony-api bash. You can then use psql to query the database sudo -i -u postgres psql cacophonytest

Note that the source code is mounted on to the docker image, so any changes causes the server to reload. However, running ./run --isolate will run the server independently of the source code, include the node_modules.

If you would like to run without sudo (for example your user is already in the docker user group) you can use ./run --no-sudo

Running the tests

The Cacophony API server has a comprehensive function test suite. This requires Python 3.

To run the tests, you need to do these steps once:

• Create a virtualenv using your preferred method. Ensure that the virtualenv using Python 3. One approach way to create a virtualenv is: python3 -m venv /path/to/venvs/cacophony-api-tests. You may also want to consider virtualenvwrapper.
• Activate the virtualenv. For example: source /path/to/venvs/cacophony-api-tests/bin/activate
• cd test
• Install dependencies: pip install -r requirements.txt

To run the tests:

• Start the API server as described above.
• Activate the virtualenv created earlier.
• cd test
• Run the tests with: pytest -s

API Documentation

API documentation can be generated by running npm run apidoc. The resulting documentation ends up in the apidoc directory.

The API server also serves up the generated API documentation at it's root URL.

Database Migrations

To run any pending database migrations: npm run db-migrate

To create a new database migration file: npm run new-migration <name>

Releases

• Ensure all required changes have been merged into the master branch on Github.
• Ensure your local repository has the required release revision checked out.
• Tag the release (starting with a "v"), e.g.: git tag -a v1.2.3 -m "1.2.3 release"
• Push the tag to Github, e.g.: git push origin v1.2.3
• TravisCI will run the tests, create a release package and create a Github Release