multi-tenancy

Exemplo de aplicação web baseada no conceito "multi-tenant", desenvolvida com Laravel e o pacote Tenancy.

• Funcionalidades do sistema
• Procedimentos pós-clone
• Guia de desenvolvimento
• Configurando um Virtual Host

Funcionalidades

1. Sistema principal

1.1. Criação de tenats

Para criar um 'tenant' devemos passar os seguintes parâmetros:

• nome do responsável pela empresa: string não nula;
• nome fantasia: string não nula;
• razão social: string não nula;
• cidade: string não nula;
• CNPJ: inteiro não nulo. Cada tenant criado pode ser acessado através de um subdomínio da aplicação principal. Este subdomínio é criado em função do nome fantasia e da cidade.

2. Tenants

2.1. CRUD de Cargos

Para criar 'cargos' em cada um dos tenants devemos passar os seguintes parâmetros:

• nome: string não nula;
• código: inteiro não nulo;
• descrição: string;
• status: boolean, 0 ou 1;
• requerente: boolean, 0 ou 1.

Também é possível visualizar, editar e deletar um cargo específico, assim como listar todos que não foram deletados.

2.2. CRUD de Colaboradores

Para criar 'colaboradores' em cada um dos tenants devemos passar os seguintes parâmetros:

• matricula: string única;
• nome: string não nula;
• cargo_id: inteiro não nulo;
• admissao: date (valor padrão é a data atual);
• cracha: string;
• cpf: string;
• nascimento: date.

Também é possível visualizar, editar e deletar um cargo específico, assim como listar todos que não foram deletados.

Procedimentos pós-clone

1. Configurações gerais e de ambiente

1.1 Instalar as dependências via Composer

multi-tenant$ cd project
project$ composer install

1.2. Criar a Base de Dados e um usuário para Banco de Dados

CREATE DATABASE IF NOT EXISTS tenancy_db character set UTF8mb4 collate utf8mb4_unicode_ci;
CREATE USER IF NOT EXISTS tenancy_user@localhost IDENTIFIED BY '142536';
GRANT ALL PRIVILEGES ON *.* TO tenancy_user@localhost WITH GRANT OPTION;

Como os arquivos .env.example e config/database.php fazem parte do repositório do projeto, as credênciais de usuário para acesso ao Banco de Dados e o nome da Base de Dados usada no projeto são os mesmos usados no exemplo acima. Portanto, se você não mudou nada do bloco acima, basta apenas conferir os arquivos nos próximos passos.

Altere os arquivos de ambiente: .env e config/database.php

Faça uma cópia do arquivo .env.example para criar o .env:

project$ cp .env.example .env

Agora adicione as credênciais da Base de Dados e do usuário do Banco de Dados:

• no arquivo .env:

DB_CONNECTION=system
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=tenancy_db
DB_USERNAME=tenancy_user
DB_PASSWORD=142536

• e em config/database.php:

    ...
    'connections' => [
        ...
        'mysql' => [
            ...
        ],
        'system' => [
            'driver' => 'mysql',
            'host' => env('TENANCY_HOST', '127.0.0.1'),
            'port' => env('TENANCY_PORT', '3306'),
            'database' => env('TENANCY_DATABASE', 'tenancy_db'),
            'username' => env('TENANCY_USERNAME', 'tenancy_user'),
            'password' => env('TENANCY_PASSWORD', '142536'),
            'unix_socket' => env('DB_SOCKET', ''),
            'charset' => 'utf8mb4',
            'collation' => 'utf8mb4_unicode_ci',
            'prefix' => '',
            'strict' => true,
            'engine' => 'innoDB',
        ],
        'tenant' => [
            'driver' => 'mysql',
            'host' => env('TENANCY_HOST', '127.0.0.1'),
            'port' => env('TENANCY_PORT', '3306'),
            'database' => env('TENANCY_DATABASE', 'data_base_name'),
            'username' => env('TENANCY_USERNAME', 'tenancy_user'),
            'password' => env('TENANCY_PASSWORD', '142536'),
            'unix_socket' => env('DB_SOCKET', ''),
            'charset' => 'utf8mb4',
            'collation' => 'utf8mb4_unicode_ci',
            'prefix' => '',
            'strict' => true,
            'engine' => 'innoDB',
        ],
    ...

1.3. Crie uma nova chave para a aplicação

project$ php artisan key:generate

1.4. Gere o arquivo de cache das configurações de ambiente

project$ php artisan config:cache

1.5. Rode as migrations

project$ php artisan migrate:refresh

Guia de desenvolvimento (em construção)

• Capítulos 0 & 1 - Requisitos & Criando o projeto Laravel
• Capítulo 2 - Configurando o ambiente para instalação do pacote Tenancy
• Capítulo 3 - Criando tenants
• Capítulo 4 - Estrutura dos tenants
  • 4.1 - Estruturando nossa aplicação
  • 4.2 - CRUDs
    • 4.2.1 - Cargos
    • 4.2.2 - Colaboradores
    • 4.2.3 - Salários
    • 4.2.4 - Produtos

Configurando um Virtual Host no Apache

1. Arquivo de Virtual Host

Para testarmos nossa aplicação devemos configurar um Virtual Host no Apache. O primeiro passo para isso é criar um arquivo para o virtual host do nosso projeto, estes arquivos ficam no diretório /etc/apache2/sites-available/. Fazemos uma cópia do arquivo padrão nomeando-a como project.local.br.conf:

$ sudo cp /etc/apache2/sites-available/000-default.conf /etc/apache2/sites-available/project.local.br.conf

Suprimindo os comentários o arquivo ficará parecido com o bloco abaixo (provavelmente o este bloco não estará em seu arquivo, então basta colá-lo no final).

<VirtualHost *:80>
 ServerName
 ServerAlias
 DocumentRoot
 <Directory "">
	Options +Indexes +Includes +FollowSymLinks +MultiViews
	AllowOverride All
	Allow from all
	Require all granted
 </Directory>
</VirtualHost>

As diretivas que devemos preencher são:

• ServerName: estabelece o domínio de base que deve corresponder à esta definição de virtual host;
• ServerAlias: define outros nomes que devem corresponder como se fossem o nome de base (subdomínios, www, etc);
• DocumentRoot: reflete o diretório que contém o arquivo raiz do projeto (index.html, index.php, etc);
• Directory: contém o caminho do diretório raiz de nosso projeto.

Podemos obter o caminho do arquivo raiz utilizando o terminal, para isso navegue até a pasta 'public' do projeto Laravel e então rode o comando $ pwd (print working directory). Agora basta colar a saída deste comando na diretiva DocumentRoot.

project$ cd public
project/public$ pwd 

Para projetos Laravel, a raiz do projeto fica 1 (um) nível acima do arquivo raiz.

No meu caso, o bloco que deve ser adicionado ao arquivo de virtual host ficou assim:

<VirtualHost *:80>
 ServerName project.local.br
 ServerAlias *.project.local.br
 DocumentRoot "/home/bruno/repositorios/multi-tenancy/project/public"
 <Directory "/home/bruno/repositorios/multi-tenancy/project/">
	Options +Indexes +Includes +FollowSymLinks +MultiViews
	AllowOverride All
	Allow from all
	Require all granted
 </Directory>
</VirtualHost>

2. Ativando o arquivo de Virtual Host

Agora que temos um arquivo de virtual host para nossa aplicação, devemos ativa-lo. Isso pode ser feito utilizando uma ferramenta fornecida pelo Apache, rodando o comando:

$ sudo a2ensite project.local.br

Para que as alterações tenha efeito, é necessário reiniciar o Apache:

$ sudo systemctl restart apache2
ou
$ sudo service apache2 restart

3. Configurando o arquivo de hosts local

Nesta etapa adicionamos os domínios e subdomínios da nossa aplicação ao arquivo /etc/hosts. Dessa forma, estes serão resolvidos para o localhost, o que permitirá acessá-los:

127.0.0.1	localhost
127.0.0.1	project.local.br
127.0.0.1	subdominio.project.local.br
127.0.1.1	pv

4. Habilite mod_rewrite no Apache

Certifique-se de que o mod_rewrite do Apache está ativado. Para garantir isso, basta rodar:

$ cd /etc/apache2/mods-available
$ sudo a2enmod rewrite
$ sudo /etc/init.d/apache2 restart

5. Testando

Para testar o virtual host configurado, basta acessar o(s) domínio(s) pelo navegador.

http://project.local.br

(*) OBSERVAÇÃO 1: Note que para cada tenant criado, devemos adicionar seu subdomínio no arquivo /etc/hosts apontando para o localhost (127.0.0.1).

(*) OBSERVAÇÃO 2: Se você receber qualquer excessão sobre permissão, rode o comando abaixo. Mas tenha em mente que só estamos fazendo isso pois estamos no ambiente local, JAMAIS na devemos fazer isso em ambiente de produção.

$ sudo chmod -R 777 projeto/

por enquanto é isso ;)