Rin Minase's Anime Database
(Back-end API Service)

Introduction

Add info here

Table Of Contents

• Getting Started
  • Environment variables setup
  • Running the project
  • Job / Commands / Schedule updates
  • Managing the supervisor
  • Running the optional containers
  • Re-running the project
  • Running scheduled tasks
  • Running the Swagger Generator / API Documentation Generator
  • Running the Unit Tests
  • Project shorthands / aliases inside the PHP Docker container
• Project Structure
• Project Tech Stack

Getting Started

Environment variables setup

_{^{Return to the table of contents}}

1. Database

   Definition of terms:

   • DB_HOST - docker container name of the database
   • DB_PORT - port used by the database
   • DB_DATABASE - database name
   • DB_USERNAME - database username
   • DB_PASSWORD - database password

   Notes : DB_HOST should use docker container name of db, by default this is 'anidb-pgsql', but yours could be different. You can check this by running docker ps then check the container name of the postgres container.

2. Cloudinary

   • Fire up your browser and login your Cloudinary Account. If you have no account yet, you can create one for free.
   • After logging in, navigate to the Cloudinary Console to retrieve your Cloudinary URL
   • Copy the value of API Environment variable to CLOUDINARY_URL of your ENV file

Running the project

_{^{Return to the table of contents}}

1. Download and install Docker.

2. Clone the project, then install the dependencies

   git clone https://github.com/RinMinase/anidb-be.git
   cd anidb-be

3. Run the necessary docker containers

   docker compose up -d
   docker compose exec php sh

   This runs only the necessary containers. As for running the optional containers, please see the section below.

4. Inside the docker image, copy the env file, install the necessary dependencies and generate the necessary key for laravel

   cp .env.example .env
   composer install
   php artisan key:generate

5. Generate the necessary API key and take note of this is as this is REQUIRED to access the API

   php artisan app:generate-api-key

   or you can generate your own from any application, and add it under API_KEY in your .env file. Example:

   openssl rand -hex 36

6. Generate the necessary root password key and take note of this is as this is REQUIRED to create admin accounts

   php artisan app:generate-root-password

   or generate your own, and add it under APP_REGISTRATION_ROOT_PASSWORD in your .env file.

7. Run the database migrations

   php artisan migrate:fresh --seed

8. (Optional) If you want to start the scheduler and queue workers

   supervisorctl start worker:

9. Lastly, fire up your browser and go to localhost.

Note: If you need to access the container run, docker compose exec php sh

Job / Commands / Schedule updates and restarting the supervisor

_{^{Return to the table of contents}}

In cases there are any updates to:

• Jobs (found on app/Jobs)
• Commands (found on app/Commands)
• Schedules (found on bootstrap/app.php under withSchedule)

Please run the following:

1. Navigate inside the php docker container [how]

2. Run the command to restart the group (queue-worker and schedule-worker)

   supervisorctl restart worker:

Managing the supervisor

_{^{Return to the table of contents}}

This application runs supervisor on the php container. Supervisor runs these tasks:

Task Name	Group	Command	Description
php-fpm	-	php-fpm	Runs FastCGI Process Manager
queue-worker	worker	php artisan queue:work	Runs Laravel's Queue worker
schedule-worker	worker	php artisan schedule:work	Runs Laravel's Schedule worker

To manage the supervisor the commands below can be used:

Command	Description
supervisorctl reread	Re-reads changes in supervisor config files
supervisorctl update	Updates supervisor with changes after reread
supervisorctl status	Check status of all running tasks
supervisorctl start	Starts the task
supervisorctl stop	Stops the task
supervisorctl restart	Restarts the task

Please note: Supervisor logs are kept in ./docker/logs/supervisor.log

Running the optional containers

_{^{Return to the table of contents}}

List of optional containers:

Name	Description
(none)	None as of yet

You can run them individually by:

docker compose up -d <name>

Or run all of them by:

docker compose up -d --profile optional

Re-running the project

_{^{Return to the table of contents}}

1. Navigate inside the php docker container

   docker compose exec php sh

2. Run the migrations when necessary, then install the dependencies also when necessary

   php artisan migrate
   composer install

3. Fire up your browser and go to localhost.

Running the queue manually

_{^{Return to the table of contents}}

1. Navigate inside the php docker container [how]

2. Run the command to run the worker for the queue

   php artisan queue:work

Running the scheduled tasks manually

_{^{Return to the table of contents}}

1. Navigate inside the php docker container [how]

2. Run the command to run the scheduled tasks manually

   php artisan schedule:work

There are a few commands specific to running tasks:

Name	Description
schedule:run	Runs the scheduled tasks manually with respect to cron
schedule:work	Runs the scheduler worker
schedule:list	Lists the upcoming tasks to be run

Running the Swagger Generator / API Documentation Generator

_{^{Return to the table of contents}}

1. Navigate inside the php docker container [how]

2. Run the command to generate the documentations inside the container

   docs

3. Fire up your browser and go to localhost/docs to open Swagger UI.

Running the Unit Tests

_{^{Return to the table of contents}}

1. Navigate inside the php docker container [how]

2. Run the command below:

   php artisan test

   or if you want to run a specific test module

   php artisan test --filter <Class name of Test File | function name>
   

   or if you want to run a specific single test

   php artisan test --filter test_function_name tests/Location/of/TestCase.php

Project shorthands / aliases inside the PHP Docker container

_{^{Return to the table of contents}}

This shortcuts were created to reduce the need to keep typing the same long commands over and over again.

Shortcut	Long version
pa or artisan	php artisan
docs	composer docs
dump or da	composer dumpautoload
sv	supervisorctl

Project Structure

_{^{Return to the table of contents}}

.
├── app/                     # Application source code
│   ├── docs.blade.php       # Swagger page template
│   ├── index.blade.php      # Landing page template
│   └── ...                  # Other application-related files
├── bootstrap/               # Project initializers
│   ├── app.php              # Framework bootstrapper
│   ├── helpers.php          # Helper functions
│   └── routes.php           # Route definitions
├── config/                  # Laravel configuration files
├── database/                # Database migrations and seeders
├── docker/                  # Docker functions
│   ├── php-config/          # PHP settings for docker
│   ├── caddyfile            # Caddy container docker file
│   ├── php.dockerfile       # PHP container docker file
│   └── ...                  # Other docker-related files
├── public/                  # Project entry point
├── tests/                   # Project test files
├── .czrc                    # Commitizen configuration file
├── docker-compose.yml       # Main docker file
├── phpunit.xml              # Unit test configuration file
├── Procfile                 # Heroku process file
└── ...                      # Other project files

Built with

• Laravel 12 - Core Framework
• PHP 8.4 - Language syntax
• PostgreSQL - Database
• Caddy - Local HTTP Server
• Docker - Container platform
• Sentry - Application Monitoring
• Swagger - API Documentation
• Heroku - Hosting and Continuous Integration (CI) service
• PHPUnit - Unit Testing

Deployed to

• Heroku