Skip to main content

Introdução

Para desenvolver e hospedar uma aplicação Django 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 Python. Testado com Django 6 no Python 3.13 em setembro de 2026.

Crie o projeto

Você precisa do Python e do pip na sua máquina. Se ainda não os tiver, baixe o Python no site oficial do Python.

Instalando as bibliotecas

Instale o Django, o servidor de produção Gunicorn e o WhiteNoise, que serve os seus arquivos estáticos:

Desenvolvendo o projeto

Crie um novo projeto Django e entre na pasta dele:
Isso cria o manage.py e um pacote mysite/ com settings.py, urls.py e wsgi.py. Para adicionar uma rota básica, edite o mysite/urls.py:
mysite/urls.py

Configurando o settings para produção

Nunca deixe segredos fixos no código. No mysite/settings.py, leia a chave secreta e as flags de produção de variáveis de ambiente, confie na origem HTTPS do seu site e ative o WhiteNoise. Mantenha o restante das configurações geradas como está:
mysite/settings.py
Substitua mysite.squareweb.app pelo seu subdomínio ou domínio personalizado. Depois, defina estas variáveis de ambiente na sua aplicação, pelo dashboard ou com squarecloud app env set:
Para rodar o projeto localmente, defina DJANGO_SECRET_KEY (qualquer valor) e DJANGO_DEBUG=True no seu terminal e execute python manage.py runserver.
Depois, liste as suas dependências em um arquivo requirements.txt ao lado do manage.py. A Square Cloud as instala com o pip antes de iniciar a aplicação. Ele deve listar pelo menos:
requirements.txt

Escolha um servidor de produção

O servidor de desenvolvimento integrado do Django (runserver) não é adequado para uso em produção. Use o Gunicorn, um servidor WSGI pronto para produção, iniciado pelo comando START abaixo. Para configurações de workers e outras opções, veja o guia do Gunicorn:

Gunicorn

Gunicorn é um servidor HTTP WSGI em Python para UNIX. Ele utiliza um modelo de worker pré-fork, o que significa que cria múltiplos processos worker para lidar com as requisições. Isso o torna uma ótima opção para executar aplicações web Python em produção.

Porta e host

O comando START abaixo faz o bind do Gunicorn em 0.0.0.0:80: todas as interfaces de rede, na porta para a qual a Square Cloud encaminha a sua aplicação. O Django em si não tem nenhuma configuração de porta para mudar.

Configure a Square Cloud

Crie um arquivo squarecloud.app ao lado do manage.py:
squarecloud.app
A cada inicialização, esse comando:
  • collectstatic copia os seus arquivos estáticos para o STATIC_ROOT, de onde o WhiteNoise os serve.
  • migrate aplica as migrações pendentes do banco de dados. Ele não faz nada quando o banco de dados já está atualizado.
  • python -m gunicorn mysite.wsgi --bind 0.0.0.0:80 serve a aplicação WSGI do projeto mysite na porta 80 e em todas as interfaces de rede.
O MAIN=manage.py seleciona o runtime Python. No upload pelo dashboard, defina o mesmo arquivo principal e o mesmo comando de inicialização.

O que vai no ZIP

  • O manage.py e o pacote mysite/, com as suas apps e templates.
  • requirements.txt.
  • squarecloud.app.
O manage.py, o requirements.txt e o squarecloud.app precisam estar na raiz do ZIP. Deixe de fora a .venv, a __pycache__, a staticfiles/ (recriada pelo collectstatic a cada inicialização) e o seu db.sqlite3 local.

Faça o deploy e verifique

Via dashboard

1

Acesse a página de upload

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

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.
3

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.
Enviando aplicação para a Square Cloud
4

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.
1

Instale a CLI

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

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.
3

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:
Para enviar um zip que você mesmo criou, passe-o com --file:
4

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:
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.

KeyError: ‘DJANGO_SECRET_KEY’

A variável de ambiente está faltando. Defina a DJANGO_SECRET_KEY como mostrado em Configurando o settings para produção e reinicie a aplicação.

Bad Request (400)

O endereço que você abriu não está na DJANGO_ALLOWED_HOSTS. Adicione o seu subdomínio ou domínio personalizado a ela 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 Django, consulte a documentação oficial do Django e a lista de verificação de deploy.

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.