Backend Setup

Use this guide for backend-specific local configuration that is not covered in docs/setup.md.

Prerequisites

• Complete the repository quickstart in docs/setup.md, including container startup and Laravel bootstrap.
• Use this page after you can already run the app locally.

Local backend configuration

Set these values in your local .env:

• ASSETS_URL=http://core.test/brand-assets
• USE_CLOUD_STORAGE=false

If you work with templates, follow the internal brand templates setup guide.

The assets repository is only needed when you need local brand images or templates:

cd ..
git clone git@bitbucket.org:giftcartdev/rc-assets.git assets

Core's Docker configuration mounts ../assets to public/brand-assets, so the folder name and location relative to the Core repository matter. Restart Core containers after changing asset/template configuration.

For cloud-hosted development assets/templates, use:

• ASSETS_URL=https://assets.tillo.dev
• USE_CLOUD_STORAGE=true

If local templates still do not appear, check whether the brand has has_template enabled in the database.

Queue workers

Local development includes the core.worker service for queue processing.

Primary worker command (inside core.web):

php artisan queue:work --timeout=30 --queue default,requestGC,requestGC-retry,fetchCodeGC,issuance-emails,bulk-buy-orders,bulk-buy-gift-cards,bulk-buy-gift-card-urls,retryWrapprCreateUrl,reports,lowest-priority,audit-log,webhooks,asset-processing,bulk-buy-async-request-card,bulk-buy-async-fetch-card --tries 1

Scale workers from the host if you need higher local throughput:

AWS_PROFILE=internal-services docker-compose up --scale core.worker=5 -d

Allow-list your IP for manual API testing

To call Core's public gift-card API in tools like Postman, add an allow-list entry for the selected Buyer:

1. Run rc-wizard inside core.web.
2. Select Configure a Partner's Whitelisted IPs.
3. Select the Buyer slug.
4. Select your master user.
5. Select Add New.
6. Enter * for the IP address.
7. Enter a comment and save.

First-run database note

Before running initial migrations on a fresh environment, ensure core.db has finished first-run scripts from local/.

If first-run migrations fail with AWS credential errors, add temporary dummy values to Core .env, rerun migrations, then comment them out:

AWS_ACCESS_KEY_ID=dummy
AWS_SECRET_ACCESS_KEY=dummy

If migrations fail after configuration changes, clear Laravel caches and retry:

php artisan optimize:clear
php artisan migrate -vvv

Local service ports

To access the Core MySQL CLI:

just shell-core-db

To reset a local Core Docker database volume, identify the volume and remove it carefully:

docker volume ls
docker volume rm <name_of_volume>

This deletes the stored local data for that volume.

Testing

Use docs/backend/testing.md for test suite setup and commands.