Hospedagem Laravel: deploy de uma aplicação Laravel

Introdução

Para desenvolver e hospedar uma aplicação Laravel na Square Cloud, siga a sequência de configurações e pré-requisitos abaixo. Este guia cobre todo o processo, da configuração inicial ao deploy em produção.

Pré-requisitos

Conta Square Cloud: Cadastre-se através da página de cadastro usando seu e-mail.
Plano ativo: Garante recursos dedicados e desempenho otimizado para seu aplicativo. Confira nossos planos disponíveis e escolha o mais adequado às suas necessidades.

Este guia usa o runtime PHP.

Crie o projeto

Você precisa do PHP e do Composer na sua máquina. Instale o instalador do Laravel com o Composer:

composer global require laravel/installer

Depois, crie um projeto e inicie o servidor de desenvolvimento:

laravel new myapp
cd myapp
php artisan serve

O servidor de desenvolvimento normalmente escuta em http://localhost:8000. Aqui está uma rota básica em routes/web.php:

routes/web.php

<?php

use Illuminate\Support\Facades\Route;

Route::get('/', function () {
    return 'Hello World from Laravel!';
});

Faça o build para produção

A Square Cloud instala as suas dependências PHP com composer install antes de cada inicialização, a partir do composer.json e do composer.lock. Se a sua aplicação usa o Vite para os assets do frontend (o padrão), execute npm run build antes de criar o ZIP, para que a pasta public/build seja incluída.

Escolha um servidor de produção

Sem um comando START, a Square Cloud executa o servidor embutido do PHP (php -S 0.0.0.0:80) com a raiz do projeto como document root. O document root do Laravel é a pasta public/, então as suas rotas retornariam erros 404 e arquivos como o .env poderiam ficar expostos. Sempre defina um comando START que rode o próprio servidor do Laravel.

Porta e host

O php artisan serve precisa dos dois valores na linha de comando: --host=0.0.0.0 --port=80. Sem --host=0.0.0.0, ele escuta apenas em 127.0.0.1 e o seu site dá timeout.

Configure a Square Cloud

Crie um arquivo squarecloud.app na raiz do projeto:

squarecloud.app

MAIN=public/index.php
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My Laravel app
SUBDOMAIN=mylaravelapp
START=php artisan migrate --force && php artisan serve --host=0.0.0.0 --port=80

A cada inicialização, depois que a Square Cloud instala as suas dependências em vendor/, esse comando:

php artisan migrate --force aplica as migrações pendentes do banco de dados. O --force é obrigatório para rodar migrações em produção.
php artisan serve --host=0.0.0.0 --port=80 serve a sua aplicação a partir da pasta public/ pelo roteador do Laravel, na porta 80 e em todas as interfaces de rede.

O MAIN=public/index.php seleciona o runtime PHP. No upload pelo dashboard, defina o mesmo arquivo principal e o mesmo comando de inicialização.

Variáveis de ambiente

Defina estas variáveis de ambiente na sua aplicação, pelo dashboard ou com squarecloud app env set, em vez de enviar o seu arquivo .env local:

Variável	Valor
`APP_KEY`	A saída de `php artisan key:generate --show`
`APP_ENV`	`production`
`APP_DEBUG`	`false` (nunca `true` em produção)
`APP_URL`	O endereço do seu site, por exemplo `https://mylaravelapp.squareweb.app`
`DB_CONNECTION`, `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`	A conexão com o seu banco de dados. Projetos Laravel novos usam SQLite por padrão

Confiando no proxy da Square Cloud

A Square Cloud serve o seu site via HTTPS por meio de um proxy. Para que o Laravel gere links e URLs de assets com https://, confie no proxy em bootstrap/app.php:

bootstrap/app.php

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(at: '*');
})

Mais desempenho com Swoole

O php artisan serve atende uma requisição por vez. Para tráfego maior, o runtime PHP já inclui o Swoole: rode a sua aplicação nele com o Laravel Octane (composer require laravel/octane).

Swoole

Rode aplicações PHP sobre o Swoole na Square Cloud.

O que vai no ZIP

O projeto inteiro: app/, bootstrap/, config/, database/, public/ (com a public/build se você usa o Vite), resources/, routes/, storage/, artisan, composer.json e composer.lock.
squarecloud.app.

Deixe de fora a vendor/ e a node_modules/ (a Square Cloud instala a vendor/ no servidor) e o seu arquivo .env local.

Faça o deploy e verifique

Via dashboard

Acesse a página de upload

Acesse a página de upload e envie seu arquivo zip.

Configure seu ambiente

Após fazer o upload do seu arquivo zip, você precisará configurar o nome, o arquivo principal ou o ambiente de execução e outras configurações do seu projeto.
Se você estiver enviando um projeto web, certifique-se de selecionar “Publicação na Web” e definir um subdomínio para o seu projeto.

Faça o deploy do projeto

Por fim, clique no botão “Deploy” para hospedar seu projeto na Square Cloud. Após o deploy, você poderá monitorar o status e os registros do seu projeto no dashboard.

Confirme que seu app está no ar

Seu primeiro deploy geralmente leva menos de um minuto. No dashboard, aguarde o status da sua aplicação mudar para em execução e verifique os registros em busca de erros de inicialização.
Se você fez deploy de um site ou API, abra https://<seu-subdominio>.squareweb.app no navegador: você deve ver sua aplicação respondendo. Se você fez deploy de um bot, envie um comando para confirmar que ele está online.

Seu app não está iniciando? Veja o guia de solução de problemas para as causas e correções mais comuns.

Via CLI

Para usar esse método, seu projeto precisa de um arquivo de configuração chamado squarecloud.app na raiz. Ele informa à Square Cloud como executar a sua aplicação.

Guia do arquivo de configuração

Saiba como criar o arquivo de configuração squarecloud.app que define o ambiente da sua aplicação.

Instale a CLI

Instale a CLI da Square Cloud. Se você já a tem, execute o mesmo comando para atualizá-la:

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

Faça login

Execute o comando abaixo. Ele abre o seu navegador: aprove o login lá e a CLI está pronta. Não há nenhuma chave de API para copiar. Para scripts e CI, veja autenticação da CLI.

squarecloud auth login

Envie o seu projeto

Na pasta do seu projeto, execute o comando abaixo. A CLI compacta a pasta atual, deixando de fora o que o squarecloud.ignore lista, e faz o upload:

squarecloud upload

Para enviar um zip que você mesmo criou, passe-o com --file:

squarecloud upload --file <caminho/para/zip>

Confirme que seu app está no ar

Seu primeiro deploy geralmente leva menos de um minuto. Verifique o status e os registros da sua aplicação diretamente pelo terminal:

squarecloud app status
squarecloud app logs

Se você fez deploy de um site ou API, abra https://<seu-subdominio>.squareweb.app no navegador: você deve ver sua aplicação respondendo. Se você fez deploy de um bot, envie um comando para confirmar que ele está online.

Seu app não está iniciando? Veja o guia de solução de problemas para as causas e correções mais comuns.

Erros comuns

Domínio personalizado

Para usar um domínio personalizado (ex.: meusite.com) no lugar da URL padrão meusite.squareweb.app, você precisa do plano Standard ou superior. A URL padrão vem do campo SUBDOMAIN no arquivo de configuração. Para conectar o seu domínio, veja como configurar seu próprio domínio.

Requisitos mínimos de RAM

Mínimo: 512MB de RAM para sites e APIs, o suficiente para um build estático no runtime estático. Para aplicações que renderizam páginas no servidor (Next.js, Nuxt, Angular SSR e similares), recomendamos pelo menos 1GB de RAM. Para aplicações maiores, aloque mais RAM para evitar que a aplicação fique sem memória e trave.

Não foi possível encontrar esse site.

Verifique se o subdomínio/domínio corresponde ao configurado no campo SUBDOMAIN ou nas configurações de domínio personalizado. Se você acabou de enviar o site, aguarde até 60 segundos para a Square liberar o primeiro acesso.

Site demorou demais para responder…

O seu servidor precisa escutar na porta 80 e no host 0.0.0.0. A Square Cloud define as variáveis de ambiente PORT (80) e HOST (0.0.0.0) na sua aplicação: leia essas variáveis no código em vez de fixar outros valores. Um servidor que escuta apenas em localhost ou 127.0.0.1 nunca recebe requisições.

No application encryption key has been specified

A APP_KEY está faltando. Gere uma com php artisan key:generate --show, defina-a como variável de ambiente e reinicie a aplicação.

Próximos passos

Variáveis de ambiente

Mantenha segredos e configurações fora do código e leia-os em tempo de execução.

Domínio personalizado

Sirva a sua aplicação no seu próprio domínio, a partir do plano Standard.

Solução de problemas

Corrija uma aplicação que não inicia ou um site que não responde.

Para saber mais sobre o Laravel, consulte a documentação oficial do Laravel.

Contate-nos

Se você continuar enfrentando dificuldades técnicas, nossa equipe de suporte especializada está disponível para auxiliá-lo. Entre em contato conosco e teremos prazer em ajudá-lo a resolver qualquer questão: a qualidade do suporte é uma grande parte do motivo pelo qual desenvolvedores avaliam a Square Cloud com 4,9/5 em 402 avaliações no Google e Trustpilot.

Bots

Sites

APIs e backends

Bancos de dados

Aplicações self-hosted

Guias

Guias de migração

Hospedagem Laravel: deploy de uma aplicação Laravel

Introdução

Pré-requisitos

Crie o projeto

Faça o build para produção

Escolha um servidor de produção

Porta e host

Configure a Square Cloud

Variáveis de ambiente

Confiando no proxy da Square Cloud

Mais desempenho com Swoole

Swoole

O que vai no ZIP

Faça o deploy e verifique

Via dashboard

Via CLI

Guia do arquivo de configuração

Erros comuns

Domínio personalizado

Requisitos mínimos de RAM

Não foi possível encontrar esse site.

Site demorou demais para responder…

No application encryption key has been specified

Próximos passos

Variáveis de ambiente

Domínio personalizado

Solução de problemas

Contate-nos

​Introdução

​Pré-requisitos

​Crie o projeto

​Faça o build para produção

​Escolha um servidor de produção

​Porta e host

​Configure a Square Cloud

​Variáveis de ambiente

​Confiando no proxy da Square Cloud

​Mais desempenho com Swoole

Swoole

​O que vai no ZIP

​Faça o deploy e verifique

​Via dashboard

​Via CLI

Guia do arquivo de configuração

​Erros comuns

​Domínio personalizado

​Requisitos mínimos de RAM

​Não foi possível encontrar esse site.

​Site demorou demais para responder…

​No application encryption key has been specified

​Próximos passos

Variáveis de ambiente

Domínio personalizado

Solução de problemas

​Contate-nos

Introdução

Pré-requisitos

Crie o projeto

Faça o build para produção

Escolha um servidor de produção

Porta e host

Configure a Square Cloud

Variáveis de ambiente

Confiando no proxy da Square Cloud

Mais desempenho com Swoole

O que vai no ZIP

Faça o deploy e verifique

Via dashboard

Via CLI

Erros comuns

Domínio personalizado

Requisitos mínimos de RAM

Não foi possível encontrar esse site.

Site demorou demais para responder…

No application encryption key has been specified

Próximos passos

Contate-nos