README

Your personal job-search assistant

About

JobsToMail is an open source web application that allows users to sign up to receive emails with jobs from one of several job boards supported by the JobApis project. Users can sign up to receive jobs for free at jobs-to-mail.herokuapp.com or use the setup instructions below to run the application on their own server.

This application is built on Laravel 5.5 using the Jobs Multi and Jobs Common packages. The frontend uses Bootstrap v4 and Gulp.

Mission

JobApis makes job board and company data more accessible through open source software. To learn more, visit JobApis.com, or contact us at admin@jobapis.com.

Setup

Requirements

This application is only designed to work with PHP 7.0+ and Postgres 9.5+. Some backwards compatibility may be possible, but is not officially supported at this time.

Installation requires the following:

PHP 7.1+
Postgresql 9.5
Composer
Node 6.0+
NPM
Gulp
A web server (Nginx recommended)

Local installation

The recommended installation method is Composer.

Use composer to create a new project:

composer create-project jobapis/jobs-to-mail

Copy .env.example to .env and customize it with your environmental variables.
Run npm install && gulp to build the frontend.
Run the built-in web server to serve the application: php artisan serve.
Visit the local application at localhost:8000.
Once at least one user has signed up, you can run the job collection and email command: php artisan jobs:email.

Docker installation

After you've got Docker installed and running:

Install composer dependencies: docker run --rm -v $(pwd):/app composer:latest install
Copy .env.example to .env and customize it with your environmental variables.
Run docker-compose build and then docker-compose up -d to get the services running.
Run npm install && node node_modules/.bin/gulp to build the frontend.
Run migrations: docker exec jobstomail_web_1 php artisan migrate.
Run the collect and email command: docker exec jobstomail_web_1 php artisan jobs:email.

You can run tests with docker exec jobstomail_web_1 vendor/bin/phpunit.

Heroku installation

Use the one-click Deploy to Heroku button:
After it's deployed, you should be able to visit your app and see the home page.
Set an application key by running heroku run "php artisan key:generate --show" --app=j2m and adding the key that is displayed to your app's config variables.
Add a job in Heroku Scheduler to run php artisan jobs:email every night. This will ensure that users receive their emails.

Server installation

Additional Requirements

A server running Linux Ubuntu 16.04+
PHP-FPM
NGINX

Use composer to create a new project:

composer create-project jobapis/jobs-to-mail

Copy .env.example to .env and customize it with your environmental variables.
Run npm install && gulp to build the frontend.
Point NGINX to serve to the /public directory. Your NGINX config block should look something like this:

server {
    listen       80;
    server_name  yourdomain.com;
    
    root   /home/user/jobs-to-mail/public;
    index index.html index.htm index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        fastcgi_pass   127.0.0.1:9000;
        fastcgi_index  index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include        fastcgi_params;
    }
}

Ensure that PHP-FPM is running, and ensure that your site is running at your domain.
Create a cron job to run the job collection and notification process nightly: php artisan jobs:email.

Command Line

After users sign up for a job search, the only thing needed to collect jobs and send them emails is the following command:

php artisan jobs:email

This command will loop through each user, collect jobs based on their search criteria, and then email them when their list has been compiled.

Because this job search can take a long time, it is best to use a worker and run the job in the background (via cron job). Instructions for setting this up in Heroku are above, but if you have trouble, you can post a question to the Issues tab in the Github repository.

You can also run this job for only one email address in your system when testing or debugging:

php artisan jobs:email --email=karl@jobstomail.com

Testing

Tests are run using PHPUnit. We also employ Faker to help with producing fake data and Mockery to mock dependencies in unit tests.

Run all tests

vendor/bin/phpunit

Code coverage reports are automatically generated, and can be found in the /build directory after running the test suite.

Seeding data

If you're doing local development, you may find it handy to seed the database with some test data. Using Laravel's seed commands you can do just that:

Truncate and seed the database tables

php artisan db:seed

Seed only

php artisan db:seed --class=TestingDatabaseSeeder

Truncate only

php artisan db:seed --class=DatabaseTruncater

Note: Truncation is permanent, so be careful running this in your production environment.

Contributing

Contributions are welcomed and encouraged! Please see JobApis' contribution guidelines for details, or create an issue in Github if you have any questions.

Legal

Disclaimer

This package is not affiliated with or supported by any job boards and we are not responsible for any use or misuse of this software.

License

This package uses the Apache 2.0 license. Please see the License File for more information.

jobapis / jobs-to-mail

Maintainers

Details