Stockturn API

Stockturn API is a REST JSON API for the Stockturn application which provides products CRUD, bulk upsert via CSV and stock timeline.

Frontend in https://github.com/guizoxxv/stockturn-app

Tools

• PHP v8.0.2
• Laravel v8.29.0
• PostgreSQL v13.2
• Docker v20.10.5
• docker-compose v1.27.4
• Composer v2.0.11
• RAML v1.0

Configuration

1. The application uses Laravel Sanctum SPA authentication which requires that the frontend and backend must use the same domain. To run local you may edit your /etc/hosts.

127.0.0.1   local.test
127.0.0.1   api.local.test

The backend (this application) is hosted at http://api.local.test:8001 and the frontend at http://local.test:3000.

If you change the hosts names be sure to update the variables SESSION_DOMAIN, SANCTUM_STATEFUL_DOMAINS and FORTIFY_DOMAIN in the .env file.

Installation

Using local machine

1. Clone or download this repository to your machine

2. Create two databases in PostgreSQL: stockturn and stockturn_test

stockturn_test will be used for testing and must be referenced in the .env.testing file DATABASE section.

3. Copy the content of .env.example to a new file .env

cp .env.example .env

4. Provide your databases information to the DATABASE section in the .env and .env.testing

5. Follow the steps in the Common section bellow

6. Start the application

php artisan serve

Using docker

1. Clone or download this repository to your machine

2. Create the containers

docker-compose up -d

The application will run on host port 8001 and the database on port 3001 by default.

3. Access the app container

docker-compose exec app bash

4. Copy the content of .env.docker to a new file .env

cp .env.docker .env

5. Follow the steps in the Common section bellow

Common

1. Install the dependencies

composer install

2. Generate the application key (used for cookies)

php artisan key:generate

3. Run the migrations (create tables)

php artisan migrate

4. Generate random data (Optional)

php artisan db:seed

5. Generate admin user

php artisan app:create-admin

This command will ask the name, email and password of the user. You can use the -D flag to generate a default user name:Admin, email:admin@example.com, password:secret.

5. Generate random data (Optional)

php artisan db:seed

6. Set permissions to write in the storage folder

sudo chmod -R 777 storage

Avoid using 777 permission in production.

7. Configure queue listener to process messages

php artisan queue:listen

In production use supervisor to keep the process running in the background and restart on fails.

Documentation

Navigate to /api/doc. This documentation was build with RAML. You can import the postman collection and environment variables from etc/postman with the requests.

The Postman resources include a pre-request script to set the cookie.

Testing

Execute the following command in this project root directory to run the tests:

php artisan test