Como executar o Django no ambiente padrão do App Engine

Os aplicativos do Django para execução no ambiente padrão do App Engine são escalonados dinamicamente de acordo com o tráfego.

Neste tutorial, presume-se que você esteja familiarizado com o desenvolvimento de Web com o Django. Se você é novo no desenvolvimento do Django, é recomendável escrever seu primeiro aplicativo Django antes de continuar.

Embora este tutorial demonstre especificamente o Django, é possível usar esse processo de implantação com outros frameworks baseados em Django, como Wagtail e Django CMS.

Neste tutorial, usamos o Django 3, que requer pelo menos o Python 3.7. O ambiente padrão do App Engine é compatível com o Python 3.7 e posterior.

Objetivos

Com este tutorial, você vai:

Criar e conectar um banco de dados do Cloud SQL
Crie e use valores de secret do Gerenciador de secrets.
Implante um aplicativo Django no ambiente padrão do App Engine.

Custos

Neste tutorial, usamos os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem ser qualificados para uma avaliação gratuita.

Antes de começar

Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

Acessar o seletor de projetos

Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como confirmar se o faturamento está ativado para o projeto.

Ative as APIs Cloud SQL Admin API, Secret Manager, and Cloud Build.
Ative as APIs

Instale e inicialize o SDK do Cloud..
Observação: execute a ferramenta gcloud no Console do Cloud sem instalar o SDK do Cloud. Para executar a ferramenta gcloud no Console do Cloud, use o Cloud Shell .

Se você ainda não tiver feito isso, inicialize o App Engine e selecione sua região preferida:
```
gcloud app create
```

Preparar o ambiente

Clonar um aplicativo de exemplo

O código do app de amostra do Django está no repositório GoogleCloudPlatform/python-docs-samples (em inglês) no GitHub.

É possível fazer o download da amostra como um arquivo ZIP e extraí-lo ou clonar o repositório na máquina local:
```
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
```

Acesse o diretório que contém o código de amostra:

Linux/MacOS

cd python-docs-samples/appengine/standard_python3/django

Windows

cd python-docs-samples\appengine\standard_python3\django

Confirmar a configuração do Python

Este tutorial depende do Python para executar o aplicativo de amostra na máquina. O código de amostra também requer a instalação de dependências

Para mais detalhes, consulte o guia do ambiente de desenvolvimento do Python.

Confirme se o Python tem pelo menos a versão 3.7.
```
 python -V
```
Você verá Python 3.7.3 ou mais.

Observação: se você vir um número de versão que começa com "2", talvez seja necessário executar python3 em vez de python. Se isso acontecer, faça referência à instalação escolhida do Python ao executar comandos do python.

Crie um ambiente virtual em Python e instale as dependências:

Linux/macOS

python -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Windows

python -m venv env
venv\scripts\activate
pip install --upgrade pip
pip install -r requirements.txt

Faça o download do proxy do Cloud SQL Auth para se conectar ao Cloud SQL da sua máquina local

Quando implantado, seu aplicativo usa o proxy do Cloud SQL Auth integrado ao ambiente padrão do App Engine para se comunicar com a instância do Cloud SQL. No entanto, para testar o aplicativo no local, é necessário instalar e usar uma cópia local do proxy no ambiente de desenvolvimento. Para mais detalhes, consulte o Guia de proxy de autenticação do Cloud SQL.

O Cloud SQL Auth Proxy usa a API do Cloud SQL para interagir com sua instância do SQL. Para isso, é necessária a autenticação do aplicativo por meio do gcloud.

Faça a autenticação e a aquisição de credenciais para a API:
```
gcloud auth application-default login
```
Faça o download e instale o proxy do Cloud SQL Auth na máquina local.
Linux de 64 bits
1. Faça o download do proxy do Cloud SQL Auth:
```
wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
```
2. Torne o proxy do Cloud SQL Auth executável:
```
chmod +x cloud_sql_proxy
```
Linux de 32 bits
1. Faça o download do proxy do Cloud SQL Auth:
```
wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
```
2. Torne o proxy do Cloud SQL Auth executável:
```
chmod +x cloud_sql_proxy
```
macOS de 64 bits
1. Faça o download do proxy do Cloud SQL Auth:
```
curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
```
2. Torne o proxy do Cloud SQL Auth executável:
```
chmod +x cloud_sql_proxy
```
macOS de 32 bits
1. Faça o download do proxy do Cloud SQL Auth:
```
curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
```
2. Torne o proxy do Cloud SQL Auth executável:
```
chmod +x cloud_sql_proxy
```
Windows de 64 bits
Clique com o botão direito do mouse em https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe e selecione Salvar link como para fazer o download do proxy do Cloud SQL Auth. Renomeie o arquivo para cloud_sql_proxy.exe.

Windows de 32 bits
Clique com o botão direito do mouse em https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe e selecione Salvar link como para fazer o download do proxy do Cloud SQL Auth. Renomeie o arquivo para cloud_sql_proxy.exe.
Imagem do Docker do proxy do Cloud SQL Auth
Por conveniência, várias imagens de contêiner que contêm o proxy do Cloud SQL Auth estão disponíveis no GitHub no repositório do proxy do Cloud SQL Auth. É possível extrair a imagem mais recente na sua máquina local usando o Docker com o seguinte comando:
```
docker pull gcr.io/cloudsql-docker/gce-proxy:1.19.1
```
Outros SOs
Para outros sistemas operacionais não incluídos aqui, compile o proxy do Cloud SQL Auth na origem.
É possível mover o download para um lugar comum, como um local no PATH ou seu diretório principal. Se você fizer isso, quando iniciar o proxy de autenticação do Cloud SQL posteriormente no tutorial, lembre-se de consultar o local escolhido ao usar os comandos cloud_sql_proxy.

Criar serviços de apoio

Neste tutorial, usamos vários serviços do Google Cloud para fornecer o banco de dados, o armazenamento de mídia e o armazenamento de secret compatíveis com o projeto Django implantado. Esses serviços são implantados em uma região específica. Para melhorar a eficiência entre os serviços, é melhor que todos eles sejam implantados na mesma região. Para mais informações sobre a região mais próxima de você, consulte Produtos disponíveis por região.

Neste tutorial, optamos por usar os mecanismos integrados de hospedagem de recursos estáticos no ambiente padrão do App Engine.

Configurar uma instância do Cloud SQL para PostgreSQL

O Django tem suporte oficial para vários bancos de dados relacionais, mas oferece o maior suporte para PostgreSQL. O PostgreSQL é compatível com o Cloud SQL. Portanto, este tutorial escolhe usar esse tipo de banco de dados.

A seção a seguir descreve a criação de uma instância, banco de dados e usuário de banco de dados do PostgreSQL para o app.

Criar a instância do PostgreSQL
Console
1. No Console do Cloud, acesse a página Instâncias do Cloud SQL.
  
  Acessar a página "Instâncias" do Cloud SQL
2. Clique em Create Instance.
3. Clique em PostgreSQL.
4. No campo ID da instância, insira INSTANCE_NAME.
5. Insira uma senha para o usuário postgres.
6. Mantenha os valores padrão para os outros campos.
7. Clique em Criar.
Leva alguns minutos para criar a instância e ela deve estar pronta para uso.
gcloud
- Crie a instância do PostgreSQL:
```
gcloud sql instances create INSTANCE_NAME \
    --project PROJECT_ID \
    --database-version POSTGRES_13 \
    --tier db-f1-micro \
    --region REGION
```
Substitua:
- INSTANCE_NAME: o nome da instância do Cloud SQL.
- PROJECT_ID: o ID do projeto do Google Cloud
- REGION: a região do Google Cloud
Leva alguns minutos para criar a instância e ela deve estar pronta para uso.
Dentro da instância criada, crie um banco de dados:
Console
1. Na página da instância, acesse a guia Bancos de dados.
2. Clique em Create database.
3. Na caixa de diálogo Nome do banco de dados, insira DATABASE_NAME.
4. Clique em Criar.
gcloud
- Crie o banco de dados na instância recém-criada:
```
gcloud sql databases create DATABASE_NAME \
    --instance INSTANCE_NAME
```
  Substitua DATABASE_NAME por um nome para o banco de dados dentro da instância.
Criar um usuário do banco de dados

Observação: usuários criados dessa forma têm direitos adicionais no banco de dados. Consulte Limitar os privilégios de usuário do banco de dados para ver um método alternativo.
Console
1. Na página da instância, acesse a guia Usuários.
2. Clique em Adicionar conta de usuário.
3. Na caixa de diálogo Adicionar uma conta de usuário à instância em "Autenticação integrada":
4. Digite o nome de usuário DATABASE_USERNAME.
5. Digite a senha DATABASE_PASSWORD
6. Clique em Add.
gcloud
- Crie o usuário na instância criada recentemente:
```
gcloud sql users create DATABASE_USERNAME \
    --instance INSTANCE_NAME \
    --password DATABASE_PASSWORD
```
  Substitua PASSWORD por uma senha segura.

Armazenar valores do secret no Secret Manager

Agora que os serviços de backup estão configurados, o Django precisa de informações sobre esses serviços. Em vez de colocar esses valores diretamente no código-fonte do Django, este tutorial usa o Secret Manager para armazenar essas informações com segurança.

O padrão do App Engine interage com os secrets usando a conta de serviço.

Criar o arquivo de ambiente Django como um secret do Secret Manager

Você armazena as configurações necessárias para iniciar o Django em um arquivo env protegido. O aplicativo de amostra usa a API Secret Manager para recuperar o valor do secret e o pacote django-environ para carregar os valores no ambiente do Django. A chave secreta é configurada para ser acessível pelo padrão do App Engine.

Crie um arquivo chamado .env, definindo a string de conexão do banco de dados, o nome do bucket de mídia e um novo valor SECRET_KEY:

echo DATABASE_URL=postgres://DATABASE_USERNAME:DATABASE_PASSWORD@//cloudsql/PROJECT_ID:REGION:INSTANCE_NAME/DATABASE_NAME > .env
echo GS_BUCKET_NAME=PROJECT_ID_MEDIA_BUCKET >> .env
echo SECRET_KEY=$(cat /dev/urandom | LC_ALL=C tr -dc '[:alpha:]'| fold -w 50 | head -n1) >> .env

Armazene o secret no Secret Manager:
Console
1. No Console do Cloud, acesse a página Secret Manager.
  
  Acessar a página "Gerenciador de secrets"
2. Clique em Criar secret.
3. No campo Nome, use django_settings.
4. Na caixa de diálogo Valor do secret, cole o conteúdo do arquivo .env.
5. Clique em Criar secret.
6. Exclua o arquivo local para evitar modificações da configuração local.
gcloud
1. Crie um novo secret, django_settings, com o valor do arquivo .env:
```
gcloud secrets create django_settings --data-file .env
```
2. Para confirmar a criação do secret, verifique-o:
```
gcloud secrets describe django_settings

gcloud secrets versions access latest --secret django_settings
```
3. Exclua o arquivo local para impedir modificações da configuração local:
```
rm .env
```
Configure o acesso ao secret:
Console
1. Clique na guia Permissões.
2. Clique em Add.
3. No campo Novos membros, digite PROJECT_ID@appspot.gserviceaccount.com e pressione Enter.
4. No menu suspenso Papel, selecione Assessor de secret do Gerenciador de secrets.
5. Clique em Save.
gcloud
1. Conceda acesso ao secret à conta de serviço padrão do App Engine:
```
gcloud secrets add-iam-policy-binding django_settings \
    --member serviceAccount:PROJECT_ID@appspot.gserviceaccount.com \
    --role roles/secretmanager.secretAccessor
```

Executar o app no computador local

Com os serviços de apoio configurados, agora você pode executar o app no seu computador. Essa configuração permite o desenvolvimento local, a criação de um superusuário e a aplicação de migrações de banco de dados.

Em um terminal separado, inicie o proxy do Cloud SQL Auth:
Linux/macOS
```
./cloud_sql_proxy -instances="PROJECT_ID:REGION:INSTANCE_NAME"=tcp:5432
```
Windows
```
cloud_sql_proxy.exe -instances="PROJECT_ID:REGION:INSTANCE_NAME"=tcp:5432
```
Esta etapa estabelece uma conexão do computador local com a instância do Cloud SQL para fins de testes locais. Mantenha o proxy do Cloud SQL Auth em execução durante todo o teste local do aplicativo. A execução desse processo em um terminal separado permite que você continue trabalhando enquanto ele é executado. Certifique-se de que as próximas etapas sejam concluídas em um terminal separado.

Em um novo terminal, defina o ID do projeto localmente :

Linux/macOS

  export GOOGLE_CLOUD_PROJECT=PROJECT_ID

Windows

  set GOOGLE_CLOUD_PROJECT=PROJECT_ID

Defina uma variável de ambiente para indicar que você está usando o Cloud SQL Auth Proxy (este valor é reconhecido no código):
Linux/macOS
```
  export USE_CLOUD_SQL_AUTH_PROXY=true
```
Windows
```
  set USE_CLOUD_SQL_AUTH_PROXY=true
```

Execute as migrações do Django para configurar seus modelos e recursos:

python manage.py makemigrations
python manage.py makemigrations polls
python manage.py migrate
python manage.py collectstatic

Inicie o servidor da Web Django:
```
python manage.py runserver
```
No navegador, acesse http://localhost:8000/.

A página exibe o seguinte texto: "Hello, world. Você está no índice de pesquisas". O servidor da Web do Django em execução no seu computador exibe as páginas do aplicativo de amostra.
Pressione Control+C para interromper o servidor da Web local.

Como usar o console de administração do Django

Para fazer login no Admin Console do Django, crie um superusuário. Como você tem uma conexão acessível localmente com o banco de dados, é possível executar comandos de gerenciamento:

Crie um superusuário. Você precisará digitar um nome de usuário, e-mail e senha.
```
python manage.py createsuperuser
```
Inicie um servidor da Web local:
```
python manage.py runserver
```
No navegador, acesse http://localhost:8000/admin.
Faça login no site de administração usando o nome de usuário e a senha que você usou ao executar createsuperuser.

Como implantar o aplicativo no ambiente padrão do App Engine

Com todos os serviços de backup configurados e os aplicativos testados localmente, é possível implantar o aplicativo no ambiente padrão do App Engine:

Faça upload do aplicativo executando o seguinte comando, que implanta o aplicativo conforme descrito em app.yaml e define a versão recém-implantada como padrão, fazendo com que ela veicule todo o tráfego novo:
```
gcloud app deploy
```
Confirme as configurações digitando "yes" (sim) quando solicitado.
Aguarde a notificação sobre a conclusão da atualização.

Como executar o aplicativo implantado

O aplicativo foi implantado e agora pode ser acessado:

Abra o site implantado:
```
gcloud app browse
```

Como alternativa, exiba o URL e abra manualmente:

gcloud app describe --format "value(defaultHostname)"

A solicitação é exibida por um servidor da Web em execução no ambiente padrão do App Engine.

Como atualizar o aplicativo

Para atualizar seu aplicativo, faça alterações no código e execute o comando gcloud app deploy novamente.

A implantação cria uma nova versão do aplicativo e a promove à versão padrão. As versões anteriores do seu app são mantidas. Todas essas versões do app são recursos faturáveis. Para reduzir custos, exclua as versões não padrão do seu app.

Como configurar para produção

Agora você tem uma implantação funcional do Django, mas há outras etapas que podem ser seguidas para garantir que seu aplicativo esteja pronto para produção.

Verificar se a depuração está desativada

Confirme se a variável DEBUG em mysite/settings.py está definida como False. Isso impedirá que páginas de erro detalhadas sejam exibidas para o usuário, o que pode vazar informações sobre as configurações.

Limitar os privilégios de usuário do banco de dados

Todos os usuários criados com o Cloud SQL têm os privilégios associados ao papel cloudsqlsuperuser: CREATEROLE, CREATEDB e LOGIN.

Para impedir que o usuário do banco de dados Django tenha essas permissões, crie-o manualmente no PostgreSQL. É preciso ter o terminal interativo psql instalado ou usar o Cloud Shell pré-instalado.

Console

No Console do Cloud, ative o Cloud Shell.

Ativar o Cloud Shell
No Cloud Shell, use o terminal integrado para se conectar à instância INSTANCE_NAME:
```
gcloud sql connect INSTANCE_NAME --user postgres
```
Insira a senha do usuário do postgres.

Agora você está usando o psql. Você verá o prompt postgres=>.
Crie um usuário:
```
CREATE USER DATABASE_USERNAME WITH PASSWORD 'DATABASE_PASSWORD';
```
Substitua PASSWORD por uma senha aleatória e exclusiva.

Conceda direitos totais sobre o novo banco de dados para o novo usuário:

GRANT ALL PRIVILEGES ON DATABASE DATABASE_NAME TO DATABASE_USERNAME;

Saia de psql:
```
\q
```

gcloud

Inicie uma conexão com a instância do SQL:
```
gcloud sql connect INSTANCE_NAME --user postgres
```
Substitua INSTANCE_NAME pela instância criada do Cloud SQL.
Insira a senha do usuário do postgres.

Agora você está usando o psql. Você verá o prompt postgres=>.

Crie um usuário:

CREATE USER DATABASE_USERNAME WITH PASSWORD 'DATABASE_PASSWORD';

Conceda direitos totais sobre o novo banco de dados para o novo usuário:

GRANT ALL PRIVILEGES ON DATABASE DATABASE_NAME TO DATABASE_USERNAME;

Saia de psql:
```
\q
```

Entenda o código

Exemplo de aplicativo

O app de exemplo do Django foi criado com ferramentas padrão do Django. Os seguintes comandos criam o projeto e o app de pesquisa:

django-admin startproject mysite
python manage.py startapp polls

As visualizações básicas, os modelos e as configurações de rota foram copiados de Como criar seu primeiro aplicativo Django (Parte 1 e Parte 2).

Secrets do Secret Manager

O arquivo settings.py contém o código que usa a API Secret Manager Python para recuperar a versão mais recente do secret nomeado e extraí-la para o ambiente (usando django-environ):

appengine/standard_python3/django/mysite/settings.py

Ver no GitHub

env = environ.Env(DEBUG=(bool, False))
env_file = os.path.join(BASE_DIR, ".env")

if os.path.isfile(env_file):
    # Use a local secret file, if provided

    env.read_env(env_file)
# ...
elif os.environ.get("GOOGLE_CLOUD_PROJECT", None):
    # Pull secrets from Secret Manager
    project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")

    client = secretmanager.SecretManagerServiceClient()
    settings_name = os.environ.get("SETTINGS_NAME", "django_settings")
    name = f"projects/{project_id}/secrets/{settings_name}/versions/latest"
    payload = client.access_secret_version(name=name).payload.data.decode("UTF-8")

    env.read_env(io.StringIO(payload))
else:
    raise Exception("No local .env or GOOGLE_CLOUD_PROJECT detected. No secrets found.")

O secret é usado para armazenar vários valores de secret para reduzir o número de diferentes secrets que precisam ser configurados.

Modificações de secrets locais

Se um arquivo .env for encontrado no sistema de arquivos local, ele será usado no lugar do valor do Secret Manager. Criar um arquivo .env localmente pode ajudar no teste local (por exemplo, no desenvolvimento local em um banco de dados SQLite ou em outras configurações locais).

Conexão com o banco de dados

O arquivo settings.py contém a configuração do banco de dados SQL. Se você definir o USE_CLOUD_SQL_AUTH_PROXY, a configuração DATABASES será alterada para inferir o uso do proxy de autenticação do Cloud SQL.

appengine/standard_python3/django/mysite/settings.py

Ver no GitHub

# Use django-environ to parse the connection string
DATABASES = {"default": env.db()}

# If the flag as been set, configure to use proxy
if os.getenv("USE_CLOUD_SQL_AUTH_PROXY", None):
    DATABASES["default"]["HOST"] = "127.0.0.1"
    DATABASES["default"]["PORT"] = 5432

Conteúdo estático hospedado

O arquivo app.yaml contém informações de configuração para implantação no App Engine. Este arquivo app.yaml especifica que o App Engine exibe arquivos estáticos do diretório static/:

appengine/standard_python3/django/app.yaml

Ver no GitHub

runtime: python39

handlers:
# This configures Google App Engine to serve the files in the app's static
# directory.
- url: /static
  static_dir: static/

# This handler routes all requests not caught above to your main app. It is
# required when static routes are defined, but can be omitted (along with
# the entire handlers section) when there are no static files defined.
- url: /.*
  script: auto

Ao executar o app localmente com DEBUG ativado, esses arquivos são exibidos localmente pelo Django:

appengine/standard_python3/django/mysite/urls.py

Ver no GitHub

from django.conf import settings
from django.conf.urls.static import static
from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("", include("polls.urls")),
    path("admin/", admin.site.urls),
] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

Limpeza

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Exclua o projeto

No Console do Cloud, acesse a página Gerenciar recursos:
Acessar "Gerenciar recursos"
Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

A seguir

Saiba como configurar o PostgreSQL para produção
Saiba mais sobre Django no Google Cloud

Como executar o Django no ambiente padrão do App Engine

Objetivos

Custos

Antes de começar

Preparar o ambiente

Clonar um aplicativo de exemplo

Linux/MacOS

Windows

Confirmar a configuração do Python

Linux/macOS

Windows

Faça o download do proxy do Cloud SQL Auth para se conectar ao Cloud SQL da sua máquina local

Linux de 64 bits

Linux de 32 bits

macOS de 64 bits

macOS de 32 bits

Windows de 64 bits

Windows de 32 bits

Imagem do Docker do proxy do Cloud SQL Auth

Outros SOs

Criar serviços de apoio

Configurar uma instância do Cloud SQL para PostgreSQL

Console

gcloud

Console

gcloud

Console

gcloud

Armazenar valores do secret no Secret Manager

Criar o arquivo de ambiente Django como um secret do Secret Manager

Console

gcloud

Console

gcloud

Executar o app no computador local

Linux/macOS

Windows

Linux/macOS

Windows

Linux/macOS

Windows

Como usar o console de administração do Django

Como implantar o aplicativo no ambiente padrão do App Engine

Como executar o aplicativo implantado

Como atualizar o aplicativo

Como configurar para produção

Verificar se a depuração está desativada

Limitar os privilégios de usuário do banco de dados

Console

gcloud

Entenda o código

Exemplo de aplicativo

Secrets do Secret Manager

Modificações de secrets locais

Conexão com o banco de dados

Conteúdo estático hospedado

Limpeza

Exclua o projeto

A seguir