installation.md

Installation

These instructions are for the initial installation of this application.

• Create project
• Define environment variables
• Configure the app
• Set file permissions
• Database migration
• Scheduled jobs
• Exception links
• Message events
• Resource pruning
• Deployment
• Assets

Create project

composer create-project bayfrontmedia/bones-api PROJECT_NAME

Define environment variables

Rename .env.example to .env and update. (See docs)

NOTE: Be sure to define a cryptographically secure app key for the APP_KEY variable.

Once Bones is installed, you can use the php bones install:key command to replace SECURE_APP_KEY with a valid key, or you can use the php bones make:key command to generate a key you can define manually.

Configure the app

Update all configuration files at config/*.php as needed. (See configuration)

Set file permissions

The web server must have write permissions to the storage/app directory. Typically, this is done by granting the www-data group ownership and write access:

chgrp -R www-data /path/to/storage/app
chmod -R 775 /path/to/storage/app

Database migration

Run the initial database migration using:

php bones migrate:up

The API service includes an optional database seeding to add an initial admin user and all the necessary permissions:

php bones api:seed [email protected] password

# Force seeding (no input/confirmation required)
php bones api:seed [email protected] password --force

The password is optional. If not provided, one will be created automatically.

Scheduled jobs

The php bones schedule:run command must be setup to run every minute. If a cron job will be used to run the scheduled jobs, add a new entry to your crontab to run every minute:

* * * * * cd /path/to/your/app && php bones schedule:run >> /dev/null 2>&1

# Path to PHP binary may need to be defined
* * * * * /path/to/php/bin cd /path/to/your/app && php bones schedule:run >> /dev/null 2>&1

Exception links

Update the resources/api/api-errors.php file as needed to provide links to be returned with API errors.

For more information, see exceptions.

Message events

The app/Events/MessageEvents event subscriber exists for events which may send messages. These events must be updated to be handled as desired.

Until these are set up, authentication abilities may be restricted if a TFA/OTP code is required.

Resource pruning

All soft-deleted resources which no longer need to exist in the database should be periodically pruned with purgeTrashed. In addition, the logs table should be periodically exported/saved and pruned.

These can be done using a scheduled job.

Deployment

Self-hosted

Self-hosted deployment can be handled with the deploy:app console command.

DigitalOcean

To deploy to DigitalOcean app platform:

When deploying to DigitalOcean, be sure to update the environment variables in .do/deploy.template.yaml and encrypt the APP_KEY and applicable DB_* values.

Assets

Postman collection and environment export files which cover all the routes and functionality of this project are available in the API service repository.