Skip to content

Latest commit

 

History

History
129 lines (99 loc) · 4.19 KB

README.md

File metadata and controls

129 lines (99 loc) · 4.19 KB
Raw

VOST Portugal API

Digital Volunteers in Emergency Situations

Build Status Coverage Status

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

License

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