VOST Portugal API

Digital Volunteers in Emergency Situations

Project setup

The easiest way to get the API started is using Docker compose.

Container Matrix

Service / Project	Container Name	Host:Port
MariaDB	vost_mariadb	localhost:3306
NGINX	vost_nginx	localhost:80 / api.vost.test:80
Redis	vost_redis	localhost:6379

Hostnames

Make sure to add api.vost.test to the /etc/hosts file, so it can be properly resolved:

127.0.0.1 api.vost.test

Running the infrastructure

Jump start the VOST API with the following command:

docker-compose up --detach --build

Once the services are all up and running, you should see the following output:

Starting vost_api           ... done
Starting vost_mariadb       ... done
Starting vost_redis         ... done
Starting vost_nginx         ... done
Starting vost_test_database ... done

In order to run commands (composer, artisan, ...) in the API container, log into it via:

docker exec -it vost_api bash

Once logged in, finish the configuration by following these steps:

Install dependencies:

composer install

Copy the .env file:

cp .env.example .env

Generate an encryption key:

php artisan key:generate

Generate a JWT secret key:

php artisan jwt:secret

Execute the migrations and seeders:

php artisan migrate:fresh --seed

Jobs/Tasks & Commands

In order to run the scheduled tasks automatically, make sure the main job scheduler is properly set in the system cron table:

* * * * * cd /path/to/the/project/root && php artisan schedule:run >> /dev/null 2>&1

Each available job/task, has a corresponding artisan command for local development and testing purposes.

Scope	Description	Class	Runs every	Artisan command
ProCiv	Fetch ProCiv occurrences	OccurrenceFetcher	5 minutes	php artisan prociv:fetch:occurrences
ProCiv	Close ProCiv occurrences	OccurrenceCloser	30 minutes	php artisan prociv:close:occurrences
IPMA	Fetch IPMA warnings	WarningFetcher	30 minutes	php artisan ipma:fetch:warnings
IPMA	Fetch IPMA surface observations	SurfaceObservationFetcher	30 minutes	php artisan ipma:fetch:surface-observations
API	Bust API response cache	ResponseCacheBuster	5 minutes	php artisan api:bust:response-cache

NOTE: Job/Task & Command output is sent to the application log file (storage/logs/laravel-YYYY-MM-DD.log).

Queues

The best way to handle queues is using Supervisor.

Once installed, add the following configuration (with the proper adaptations) and start the service.

[program:api-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /path/to/api/artisan queue:work redis --sleep=3 --tries=3
autostart=true
autorestart=true
user=www-data
numprocs=4
redirect_stderr=true
stdout_logfile=/path/to/api/storage/logs/supervisor.log

For local development, the easiest way to test queued jobs is by running the following command:

php artisan queue:listen

API documentation

Documentation for the available API endpoints can be accessed locally or online.

Testing

To run the tests, execute:

vendor/bin/phpunit --testdox

Contributing

Contributions are always welcome, but before anything else, make sure you get acquainted with the CONTRIBUTING guide.

Credits

• VOST Portugal

License

This project is open source software licensed under the MIT LICENSE.