Get Started

Requirements

PHP (8.1 or more)
Composer
Node.js and npm
MySQL

Deploy project

1. Clone repository

git clone [email protected]:Andryxak4/service-dog-standards-be.git cd service-dog-standards-be

2. Install composer and npm requirements

composer install
npm install

3. Setup environment file

cp .env.example .env

Configure database connection settings and other necessary settings in .env.

4. Web server setup

Setup .htaccess for apache in ./public

<IfModule mod_rewrite.c>
    <IfModule mod_negotiation.c>
        Options -MultiViews -Indexes
    </IfModule>

    RewriteEngine On

    # Handle Authorization Header
    RewriteCond %{HTTP:Authorization} .
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

    # Redirect Trailing Slashes If Not A Folder...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_URI} (.+)/$
    RewriteRule ^ %1 [L,R=301]

    # Send Requests To Front Controller...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
</IfModule>

server {
    listen 80;
    server_name your-domain.com;
    root /path-to-your-project/public;

    index index.php index.html index.htm;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.0-fpm.sock; # Убедитесь, что версия PHP соответствует вашей установке
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }
}

5. Create robots.txt

(if on public server)

User-agent: *
Disallow: /

6. Generate application key

php artisan key:generate

7. Run database migrations

php artisan migrate

php artisan db:seed

8. Link the storage

php artisan storage:link

9. Build JS/CSS assets

npm run build

10. Run tests (optional)

php artisan test

11. Operations with tenants

# make migrations in tenant
php artisan tenant:db tenant1 --action=migrate

# Rollback two migrations
php artisan tenant:db tenant1 --action=rollback --step=2

# Run seeders for tenant
php artisan tenant:db tenant1 --action=seed

# Run some seeder for tenant
php artisan tenant:db tenant1 --action=seed --class=ProductsSeeder

# Cleanup and recreate database with run seeders
php artisan tenant:db tenant1 --action=fresh --seed

# Check migrations statuses
php artisan tenant:db tenant1 --action=status

# Run migrations for all tenants
php artisan tenant:db all --action=migrate

General description of tenants

The project uses a multi-tenant architecture that allows serving multiple clients (tenants) on a single codebase, each with its own database. This enables data separation between clients while maintaining unified application logic. Tenant implementation is based on database connection switching that occurs with each request. The current tenant can be determined in two ways:

By subdomain (the "domain" mode) - tenant1.example.com, tenant2.example.com
By cookie (the "cookie" mode) - the user selects a tenant through the interface

Tenant configuration

Tenant settings are located in the config/tenants.php file, which includes:

Operating mode (domain/cookie)
Default tenant data
List of additional tenants with their parameters

Each tenant has:

A unique key (used as a subdomain in domain mode)
A name displayed to users
A database name
An API key for API access

Working with tenants

Migrations and data

The application can work in two modes: with a regular database or with a tenant database Standard Laravel commands (migrate, db:seed) use the main database The tenant:db command is used to work with tenant databases
API requests to tenants
When accessing the API, you must specify the X-API-Key header with the value from the configuration The API automatically determines the tenant by the API key and connects to the appropriate database

Twill CMS users

Twill users are created only in the main database
To synchronize users between tenants, use the command:
php artisan tenant:sync-twill-users

Development and debugging

To view the current tenant, use the /debug-tenant route
The X-Current-Tenant header with the current tenant name is added to API responses
In templates, the tenants variables are available

Creating new tenants

Add tenant information to config/tenants.php
Create a database using the command:
php artisan tenants:setup-databases
Run migrations for the new tenant:
php artisan tenant:db new_tenant --action=migrate --seed

Recommendations

Don't create Twill users in tenants, only in the main database
When developing new features, consider that they should work for all tenants
For local testing in domain mode, add entries to your hosts file
Use the --path parameter to run specific migrations for individual tenants

31 March 2025