DEV Community: David Rios

Localizing a real world Vue.js app [part 1]

David Rios — Tue, 13 Apr 2021 23:04:53 +0000

In this series I'll demonstrate one way of localizing a real world Vue.js app using these excellent Mozilla projects:

Fluent: "Fluent is a family of localization specifications, implementations and good practices developed by Mozilla. With Fluent, translators can create expressive translations that sound great in their language."
Pontoon: "Pontoon is a translation management system used and developed by the Mozilla localization community. It specializes in open source localization that is driven by the community and uses version-control systems for storing translations."

My aim is to establish a workflow that scales well with an application's growing size and number of locales and translators. This series will chronicle my journey to realize that goal.

For this first part I'll focus on adapting the app code. The second part will focus on using Pontoon to improve the collaboration process with the team of translators.

The idea is to have one or more catalogs based on your app structure. At a minimum we'll have a base catalog, we'll call it global, that has the basic text needed for the app to work initially, possibly being the only catalog if your app is small. You can then create other catalogs with varying levels of granularity. If your app is big and you use dynamic components to load only the part the user is in, you could for instance have a profile catalog that would be loaded for the profile or any other related page. At the finest granularity we can even have component-specific catalogs.

The catalog need to be loaded in the code at some point, and for that there are some options, like:

A wrapper component that handle the loading, possibly displaying some loading indication.
Manually using a functional API

I'll focus on using a functional API for the sake of simplicity.

I want the catalogs to be able to be treated as part of a whole, in which case the keys are global and each catalog adds its keys to the global pool. It would be nice if they could also be bound to a context, inheriting or not from the global pool, in which case overwritten keys would only affect components under that context.

The app

I want to demonstrate the process of localizing an existing app, and it would be nice to use a real world application as an example. For that we'll use the Vue RealWorld example app as a starting point.

Starting up

To make it easier for you to follow, I've set up a GitHub repository with all the code at https://github.com/davidrios/vue-realworld-example-app. I'll refer to specific commits so you can see the changes along the way.

This is the state of the code with minor changes made after forking:

https://github.com/davidrios/vue-realworld-example-app/tree/f621d819

We'll use the excellent fluent-vue project, that already implements fluent for Vue.js. First install the packages:

yarn add fluent-vue @fluent/bundle intl-pluralrules

We're using Vue 2 in this example so, per fluent-vue requirement, we need to also install:

yarn add @vue/composition-api

Loading the locale files

We'll start simple and use the raw-loader to easily load ftl files through webpack by adding this configuration:

https://github.com/davidrios/vue-realworld-example-app/commit/e5038262

Now we need to load the catalogs. It would be nice if we chose the catalog based on the user's language as detected by the browser. For that I added some code to detect the language, load catalogs and setup fluent-vue:

https://github.com/davidrios/vue-realworld-example-app/commit/cff8b43f

This code will be improved on later.

From 015c35dc to 307bf3ca I just extracted strings for translation:

https://github.com/davidrios/vue-realworld-example-app/compare/015c35dc...307bf3ca

Here I have improved the catalog loading and added the option for the user to change the locale at runtime:

https://github.com/davidrios/vue-realworld-example-app/commit/0585b5a1

Live reload of locale files

As I was making more translations, I started to dislike the fact that the whole page was reloaded every time I changed any catalog, which I think is unecessary. I know webpack has a way to reload only the parts that changed with the right configuration, so I searched around but could not find anything that suited my needs.

I ended up writing my own loader to help with that:

# https://www.npmjs.com/package/@davidrios/hot-reloader
yarn add -D @davidrios/hot-reloader

And then I refactored all the catalog loading code to be more generic and make use of webpack's HMR, so now changed catalogs update the page instantly without a reload:

https://github.com/davidrios/vue-realworld-example-app/commit/fbc238ee

Separating catalogs

Separating the app in more than one catalog will be quite easy thanks to the last update to the loading code:

https://github.com/davidrios/vue-realworld-example-app/commit/45c2ea72

Some localization examples

Using fluent's own date formatting:

https://github.com/davidrios/vue-realworld-example-app/commit/ccc4da77

Localizing content with tags

One very common problem of localizing web apps arise when you need HTML tags / components in the middle of some text. Consider the example:

<p><a href='x'>Sign up</a> or <a href='y'>sign in</a> to add comments on this article.</p>

Or even worse, using components:

<p>
  <router-link :to="{ name: 'login' }">Sign in</router-link>
  or
  <router-link :to="{ name: 'register' }">sign up</router-link>
  to add comments on this article.
</p>

Best practices of localization (actually the only sensible thing to do!), say that you should translate the sentence as a whole, so how do we do that without risking translators messing up the code or worse, introducing security issues? Luckly vue is powerful enough to provide the tools necessary to tackle that problem, and the fluent-vue project do a perfect job of realizing that with the help of fluent's powerful syntax.

The fluent code would look like this:

# The two parameters will be replaced with links and each link
# will use the .sign-*-label as its text
sign-in-up-to-add-comments =
  {$signInLink} or {$signUpLink} to add comments on this article.
  .sign-in-label = Sign in
  .sign-up-label = sign up

I personally think the result is great. We have comments explaining what is happening, it's very flexible to the translator, the pieces needed are in-context and there's no HTML in sight!

For the vue part, fluent-vue provides a nice component named i18n with everything we need. The vue code would look like this:

<i18n path="sign-in-up-to-add-comments" tag="p">
  <template #signInLink="{ signInLabel }">
    <router-link :to="{ name: 'login' }">{{ signInLabel }}</router-link>
  </template>

  <template #signUpLink="{ signUpLabel }">
    <router-link :to="{ name: 'register' }">{{ signUpLabel }}</router-link>
  </template>
</i18n>

Notes:

The path property takes the name of the translation key.
Each variable in the text, like $signInLink can be used either as a direct value by passing it as args to the i18n component, for instance :args="{ signInLink: 'The link' }", or like in the previous example as a named slot.
Each named slot receives the other translation attributes as slot props with their keys camelized. In the previous example they would receive the object: { signInLabel: 'Sign in', signUpLabel: 'sign up' }, so you can use object destructuring to make the code cleaner, like #signInLink="{ signInLabel }", which will receive the value of the translation attribute .sign-in-label.

The fluent syntax is very powerful, yet relatively simple, I highly recommend you take the time to read the full guide here.

Managing fluent catalogs

The idea is to manage the localization files using Pontoon but, since that will be discussed later in part 2 of this series, for the sake of completeness in this article I added a simple script that updates a catalog based on the base locale one:

https://github.com/davidrios/vue-realworld-example-app/commit/1a8f7767

Thanks to the good folks at the fluent project that provided an API for dealing with catalogs programatically with the subproject @fluent/syntax.

You can run the script executing:

yarn update-catalog LOCALE CATALOG_NAME [FROM_LOCALE]

FROM_LOCALE is an optional parameter that if not provided will default to 'en-US'. To update the pt-BR global catalog for instance you would execute:

yarn update-catalog pt-BR global

This will merge the contents of the FROM_LOCALE catalog with the chosen one, preserving comments from both and moving keys that doens't exit in the base catalog to the end of the file with a comment noting that. The resulting file will be saved with a new name if it already exists or with the final name if creating a new one.

I've used the script to merge the catalogs, translated the rest of the keys and published a build here:

https://davidrios.github.io/vue-realworld-example-app/

And that's all for now. With all this in place I hope you already have the basic framework to start localizing your apps the "right way", while being convenient for the developers and easy on the translators.

Thanks for reading!

Como configurar um ambiente de desenvolvimento com Docker + VS Code

David Rios — Wed, 07 Apr 2021 04:24:08 +0000

There's a version in english here:

How to configure a Docker + VS Code development environment

David Rios ・ Apr 7 ・ 13 min read

#vscode #docker #webdev

Já tem um tempo que venho trabalhando com Docker em alguns projetos, e fui fazendo várias configurações até que cheguei num modelo que funciona bem para mim e minha equipe, por isso decidi compartilhá-lo, caso seja útil pra mais pessoas.

Tenha em mente que é tudo baseado na minha experiência pessoal, podendo não usar as melhores práticas ou se aplicar ao seu caso. Mas aceito sugestões de melhorias mesmo assim!

Vou te mostrar como configurar um projeto inteiro do zero e rodar ele totalmente isolado dentro de contêineres, para que o ambiente seja reproduzível e funcione da mesma forma (eu espero), não importa o seu SO.

Eu uso Ubuntu no dia-a-dia, então este guia é dessa perspectiva, mas você deve conseguir adaptar para seu SO de preferência sem muita dificuldade. Provavelmente deve funcionar bem no Windows 10 com WSL 2, mas ainda não testei para ter certeza.

Tabela de Tópicos

O Projeto
Requisitos
Começando
A aplicação backend
A aplicação frontend
Um proxy nginx simples
VS Code para o alto e avante!
- Configurando para o backend
- Configurando para o frontend
Adendo
Conclusão

O Projeto

Para ilustrar todos os passos, e ficar o mais realista possível, vamos criar um aplicativo web básico usando a seguinte stack:

Backend: Python (Django)
Database: PostgreSQL
Frontend: VueJS (Quasar)

Ao final do guia você terá um ambiente de edição de código consistente com:

Code-completion
Linting
Debugging
Configurações bem definidas de edição de código para todos trabalhando no projeto.

O motivo de escolha dessa stack é por serem tecnologias que eu já estou familiarizado, mas a maioria dos conceitos deste guia devem se aplicar a qualquer outra que você escolher.

Requisitos

Vamos precisar de poucas coisas instaladas localmente:

Docker 19+ (uma versão recente)
docker-compose v1.27+
VS Code 1.5+

E estas extensões para o VS Code:

Começando

Para ficar mais fácil de você seguir, subi um repositório no GitHub com todo o código em https://github.com/davidrios/example-docker-project. Vou ligar cada passo ao commit relevante conforme formos prosseguindo, assim você poderá ver toda a estrutura conforme ela evolui.

Estamos começando o projeto do zero, então a primeiro coisa que precisamos organizar é sua estrutura. Esta é uma das que eu gosto de usar:

Raíz do projeto
- README e coisa do docker
- conf
  - projeto 1
  - projeto 2
  - misc
  - ...
- code
  - projeto 1
  - projeto 2
  - ...

A próxima coisa que precisamos é de alguns contêineres básicos rodando, para podermos inicializar os projetos. Pela descrição do projeto, já sabemos que precisamos de pelo menos três contêineres: backend, frontend e database. Para isso precisamos criar o arquivo docker-compose.yml base. Mas antes, uma das coisas mais úteis que podemos ter é um arquivo .env, para que possamos ter algum nível de personalização sobre os contêineres.

Criemos o arquivo .env.template inicial, que cada usuário fará uma cópia local própria para personalizar:

LOCAL_USER_ID=1000
POSTGRES_PASSWORD=password

A variável LOCAL_USER_ID é usada para lidar com um problema de permissões que pode ocorrer com o Docker no Linux (mais sobre isso mais tarde). Você define ela com o uid do seu usuário no seu computador local, que pode ser consultado executando id -u no terminal. Você pode ignorar esse passo se estiver no Mac.

Depois de criar nossa cópia local do .env, é hora de definir o arquivo docker-compose.yml básico:

https://github.com/davidrios/example-docker-project/blob/2aac6eb151104b205461d025ca07647c44bc5d36/docker-compose.yml

Pontos de atenção:

Eu importo o arquivo .env nas linhas 3 a 5, e passo todas as variáveis definidas nele como variáveis de ambiente para todos os outros contêineres. Você pode ver como isso é feito nas linhas 10 e 11, 19 e 20, etc.
Estou usando imagens Alpine com versões major e minor especifícadas, como mandam as boas práticas. Você pode querer ou ser obrigado a usar uma imagem baseada em Ubuntu/Debian/etc, mas deve sempre escolher versões major/minor específicas.
Foi definido um volume para os dados do PostgreSQL, para que sejam preservados entre cada execução/reconstrução.
Sempre que possível prefiro rodar todos os projetos usando um usuário comum (não administrador) dentro dos contêineres, e por gosto de criar volumes para a home desse usuário para cada contêiner que eu espero logar e executar códigos com frequência, assim posso ter algumas coisas bacanas como o histórico do shell e outras coisas preservadas entre os rebuilds. Isso é uma preferência pessoal e completamente opcional, você pode simplesmente remover os volumes. No entanto, apesar disso ser bem conveniente, tenha em mente que pode ter consequências sutis na reproducibilidade geral do ambiente.
Para o backend e o frontend, como eles ainda não têm uma aplicação configurada, mas preciso deles rodando de qualquer forma para poder inicializar as aplicações, inicialmente eu coloco eles para rodar somente um longo sleep.

Neste momento podemos navegar para a raíz do projeto e executar:

$ docker-compose up --build

Você deve ver algumas mensagens do PostgreSQL sobre a inicialização do banco de dados e os três contêineres devem estar rodando.

A aplicação backend

Eu gosto de executar a aplicação com um usuário comum, e para prevenir problemas de permissão no Linux, esse usuário precisa ter o mesmo uid que meu usuário local do computador. Esta é a razão para a variável LOCAL_USER_ID no arquivo .env. Para poder seguir com este plano, vamos precisar de alguns scripts auxiliares, que serão usados dentro dos contêineres:

base.sh
run.sh
enter.sh

Vamos adicionálos a um diretório chamado conf/backend/scripts, como convencionado anteriormente. Esses scripts serão executados somente no ambiente de desenvolvimento, então não farão parte da imagem Docker.

Também vamos criar um arquivo Dockerfile para o contêiner com algumas personalizações iniciais. O arquivo do docker-compose será atualizado com a nova imagem e pontos de montagem para o código e os scripts. Um diretório chamado code também será criado, e por fim o docker-compose será executado novamente:

Veja como o projeto mudou:

https://github.com/davidrios/example-docker-project/commit/04ae1e95ca8dfe752e76a67fce5b9882847f2f8e

## *** paramos o docker-compose ***
$ mkdir code
$ docker-compose up --build

Agora temos o contêiner rodando e pronto para criar o projeto Django. Usamos o script enter.sh para entrar no contêiner com o venv já ativado e logado com o usuário correto. Agora vamos criar o projeto:

## Em outro terminal, na raíz do projeto:

## Cria o banco de dados:
$ docker-compose exec -u postgres postgres-db createdb -T template0 -E utf8 backend

## Entra no contêiner do *backend*:
$ docker-compose exec backend /scripts/enter.sh

## Agora dentro do contêiner:
$ cd /code
$ pip install --no-binary psycopg2 django psycopg2
$ django-admin startproject backend
$ cd backend

## Salvamos o *requirements*:
$ pip freeze > requirements.txt

## *** Editamos o arquivo backend/settings.py para conectar à instância do PostgreSQL pegando a senha do ambiente e os dados de conexão já definidos ***

$ python manage.py migrate
$ python manage.py createsuperuser
## *** escolhe os dados do usuário para login no admin ***

## Testa que a aplicação roda:
$ python manage.py runserver

## *** Parece tudo certo, paramos o servidor e saímos do contêiner ***

Dê uma olhada nos arquivos adicionados, com atenção especial à configuração do banco de dados:

https://github.com/davidrios/example-docker-project/commit/8f47c701e6a3984a32021da360ae0c49a2d68a95#diff-192a1d9e9543969133c5449ace7b1169de815b39d539bc55fc1d168f32eedb7bR76-R85

Agora precisamos mandar a aplicação executar automaticamente junto com o contêiner e expor a porta para que possamos acessar em nosso navegador local. A instalação dos pacotes necessários também será adicionada na imagem.

Para podermos executar localmente em qualquer porta de nossa escolha e não entrar em conflito com nenhuma outra coisa rodando, vamos adicionar esta opção como uma nova linha no arquivo .env.template e a mesma na nossa cópia .env:

APP_PORT=8000

além de fazer as alterações relacionadas ao docker. Veja as mudanças:

https://github.com/davidrios/example-docker-project/commit/c9276155e56f1f8c0168bb81902e5e0f22ed0dad

Agora paramos o docker-compose e executamos novamente, sempre com o parâmetro --buid. A aplicação deve estar rodando e acessível no endereço http://localhost:8000 (ou outra porta caso você tenha modificado)

É isso por enquanto para o backend. A configuração do VS Code vem mais abaixo no guia.

A aplicação frontend

Este é bem similar ao backend. Vamos criar os mesmos três scripts auxiliares, com algumas mudanças específicas para este ambiente, e personalizar a imagem um pouco.

Vamos aproveitar este momento e adicionar o arquivo .dockerignore, para que o Docker não tenha que copiar um monte de arquivos desnecessários na hora que for fazer o build de qualquer imagem. Isso vai agilizar o processo consideravelmente, a depender do tamanho do seu projeto.

Veja as mudanças:

https://github.com/davidrios/example-docker-project/commit/bbb2c6180437c8e1ae5b3b0ca2121e78dc1250af

## *** Paramos o docker-compose e iniciamos novamente ***
$ docker-compose up --build

Vamos inicializar o projeto Quasar da mesma forma:

$ docker-compose exec frontend /scripts/enter.sh
$ yarn global add @quasar/cli
$ cd /code
$ ~/.yarn/bin/quasar create frontend
## *** escolhendo opções do quasar ***
## Escolha pelo menos o ESLint, pois será usado depois.
## Também vou escolher o TypeScript, só para demonstrar o suporte do VS Code
## E finalmente escolha um *preset* ESLint que você vai usar no seu projeto. Agora vou ficar com o "standard"
## Deixe o Quasar instalar os pacotes com o yarn e saia do contêiner

Agora vamos configurar o contêiner do frontend para iniciar o Quasar em modo de desenvolvimento automaticamente e exportar a porta para que possamos acessá-lo.

Eis o resultado das mudanças:

https://github.com/davidrios/example-docker-project/commit/73e3b55df164ea2e1477cb51a8d591299c5f4643

Note que só movemos a porta exportada do contêiner do backend para o do frontend, mas já vamos consertar isso.

## *** Paramos o docker-compose e iniciamos novamente ***
$ docker-compose up --build

Agora o aplicativo Quasar deve estar rodando e acessível no endereço http://localhost:8000 (ou a porta que você definiu).

Um proxy nginx simples

Para facilitar nossa vida, vamos criar um proxy simples mas flexível com o nginx na frente de tudo. Vamos precisar usar um arquivo personalizado, e para uma maior flexibilidade vamos processar esse arquivo e misturar ele com as variáveis de ambiente antes de iniciar o serviço.

Estas são as mudanças feitas:

https://github.com/davidrios/example-docker-project/commit/b07c83199fd8d4b1cd4dfce1e830a19e76b64543

Agora podemos acessar a aplicação frontend no endereço http://localhost:8000, o admin Django em http://localhost:8000/admin, além do nginx redirecionar tudo vindo de /api* para a aplicação backend.

VS Code para o alto e avante!

Agora que temos todo nosso projeto organizadinho e rodando isolado do nosso ambiente local, precisamos começar a codar. Não seria ótimo se pudéssemos ter a mesma experiência agradável e consistente dos contêineres no nosso editor de texto também? É aí que entra o VS Code!

Vamos usar a extensão "Remote - Containers" para executar o VS Code diretamente dentro dos contêineres das aplicações, então ele vai ter acesso ao ambiente exatamente como ele roda, e também podemos instalar extensões sem afetar nossa instalação local.

Vamos usar um diretório chamado code/vscode para colocar as coisas relacionadas, para que também já estejam disponíveis dentro dos contêineres graças ao ponto de montagem /code. Você poderia colocar em outra pasta, mas aí também teria que configurar um outro ponto de montagem para cada contêiner.

Configurando para o backend

Primeiro criamos o diretório code/vscode/backend e adicionamos os seguintes arquivos:

backend.code-workspace: Substitua "backend" pelo nome real do seu projeto, assim fica mais fácil navegar entre as janelas abertas do Code.
flake8.ini: Onde colocamos nossas configurações de linter para o Python. Vamos usar flake8 ao invés do pylint, porque ele é muito mais rápido e também porque eu gosto mais :)
.devcontainer.json: Diz ao Code como configurar sua instância no contêiner

Também será necessário editar o script base.sh do contêiner, assim ele instala os pacotes necessário mesmo entre os rebuilds, além de iniciar a aplicação Python em modo de depuração. Como um agradinho também vamos configurar o servidor para recarregar automaticamente cada vez que algum arquivo é mudado, para isso utilizando a ótima biblioteca Watchdog. Isso também é necessário pois a extensão de depuração do Code não suporta o recarregamento automático nativo do Django. De brinde o watchdog ainda usa bem menos CPU para monitorar as mudanças em arquivos que o sistema nativo do Django.

Dá uma olhada como ficou (já adicionei também uma API de teste):

https://github.com/davidrios/example-docker-project/commit/33cb5d775b88d8b953ba690c17e1359dd5fa34a5

Agora tudo que precisamos fazer é parar o compose e rodar novamente, então tudo estará rodando e pronto. Para trabalhar com o código nós abrimos uma nova janela do Code (Ctrl+Shift+N), vamos no menu File > Open Folder e abrimos a pasta <PROJECT>/code/vscode/backend. No mesmo momento já deve aparecer uma notificação, então é só clicar no botão Reopen in Container. Também é possível utilizar a paleta de comandos (Ctrl+Shift+P), começar a digitar reopen in container e escolher a opção Remote-Containers: Reopen in container. Logo mais ele vai abrir, mostrar uma notificação de que está instalando o Code server e extensões, aí após alguns instantes o código deve ser aberto. No final terá uma indicação na barra de status de que você entá dentro de um contêiner, desta forma:

Então você terá todas as funcionalidades do editor, assim:

E para depurar, é só clicar na margem ao lado do número da linha no editor para configurar um ponto de pausa, ou pressionar a tecla F9 com a linha desejada selecionada, assim:

Então clique no menu lateral para ir à janela Run e clique no botão verde com o símbolo de play. A barra de status deve mudar para a cor laranja, indicando que o depurador está conectado. Se você tiver um ponto de pausa, como eu tinha, e navegar para a API no navegador, você será contemplado com esta maravilha:

Cada vez que um arquivo mudar, o servidor fará o recarregamento automático, desta forma:

E se você precisar executar algum comando administrativo do Django, pode facilmente com o terminal integrado. É só abrir o menu Terminal > New Terminal (Ctrl+Shift+<BACKTICK>), desse jeito:

Se por acaso o terminal não já estiver com o "venv" ativado, é só clicar no botão de lixeira para matar o terminal e abrí-lo novamente.

Configurando para o frontend

Aqui a configuração é bem similar à feita acima. Primeiro criamos o diretório code/vscode/frontend e adicionamos o arquivo .devcontainer.json. Aqui não vou configurar um arquivo de projeto pois não tem mais nenhuma pasta além da principal do projeto, e também para aproveitar os arquivos de configuração que o Quasar já cria na inicialização do projeto. Caso desejasse, você poderia mover tudo para um arquivo de projeto também, como fizemos no caso do backend.

Aqui está o resultado das mudanças:

https://github.com/davidrios/example-docker-project/commit/644b7547322d903f7e4b33454b787e5d1d4c6f49

Desta vez nem precisa parar e rodar o docker-compose, só abrir uma nova janela do Code, abrir o diretório code/vscode/frontend e clicar no botão Reload in Container. Depois de abrir o projeto, clique no botão ESLint na barra de status e escolha a opção allow para permitir a execução dele. Agora você tem um editor configurado, desta maneira:

Você tem até sugestões de completação para coisas como os componentes do Quasar!

Se quiser usar o CLI do Quasar para ações como criar um componente por exemplo, é só abrir o terminal embutido clicando no menu em Terminal > New Terminal (Ctrl+Shift+<BACKTICK>), assim:

Agora é hora de depurar!

Para isso, vamos criar um arquivo launch.json com as tarefas de depuração do Code. Isto não é tão trivial por algumas razões:

O VS Code tem dois depuradores que funcionam com o Chrome. Um novo que já vem pré instalado e o antigo que você pode baixar do marketplace. O problema é o que o novo é melhor, mas por alguma razão, suspeito eu que tenha a ver com o fato de rodar remotamente, ele não consegue lançar instâncias do Chrome. O antigo consegue, mas ele não é tão bom. Para resolver esse problema usaremos ambos!
Como temos uma porta personalizável através do nosso arquivo .env, precisamos de algum jeito de passá-la para a tarefa de depuração. Infelizmente as extensões de depuração executam no editor local, não no remoto, então elas não têm acesso às variáveis de ambiente. Para resolver esse problema, adicionei uma caixa de diálogo que solicita a porta que a aplicação está rodando, com o mesmo valor padrão do arquivo template do .env.

O arquivo de tarefas de depuração:

https://github.com/davidrios/example-docker-project/blob/6e5195fd13d2aea79b1a31c265ddf60808d9a77e/code/frontend/.vscode/launch.json

Temos três tarefas que usaremos dependendo do nosso navegador:

Attach to Chrome: Esta tarefa utiliza o novo depurador para se apegar à uma instância do Chrome já em execução, desde que tenha depuração remota habilitada, e você não precisa instalar mais nada. Veja aqui como executar o Chrome com a opção de depuração remota habilitada
Launch Chrome: Esta lança uma instância do Chrome com a depuração remota já habilitada, e também utilizando um perfil novo, para que não afete o seu pessoal. Para usá-la você precisa instalar a extensão Debugger for Chrome.
Launch Firefox: E por fim está lança uma instância (ou se apega à uma que já está em execução) do Firefox com a depuração remota habilitada, e também com um perfil novo para não afetar sua instância pessoal. Para utilizar esta tarefa você precisa instalar a extensão Debugger for Firefox.

Tem mais uma coisa que podemos fazer para deixar nossa vida mais agradável enquanto depuramos o código. A configuração padrão do Webpack não gera sourcemaps detalhados, o que acaba deixando o trabalho desnecessariamente mais difícil, além de deixar basicamente impossível de configurar pontos de pausa em arquivos que têm um processamento prévio. Nós corrigimos isso adicionando a opção devtool: 'eval-source-map' nas configurações.

Mesmo assim, para alguns arquivos processados como os do VueJS, ele gera várias variantes do mesmo arquivo com nomes diferentes para cada resultado intermediário do processamento. Isso é meio irritante, então acabamos com esse problema personalizando a função output.devtoolModuleFilenameTemplate do Webpack.

Já que este projeto é em Quasar, vamos fazer do modo correto, como instruído na documentação dele, editando o arquivo quasar.conf.js.

No fim das contas ele fica assim:

https://github.com/davidrios/example-docker-project/commit/1208e30bd280179df0780add22430af3a54c6c30

Agora você pode executar o depurador indo na tela de Run, selecionando a tarefa e clicando no botão de "play":

Tente adicionar alguns console.logs e/ou configurar algum ponto de pausa, rodar no modo de depuração e usar a aplicação. Eventualmente você deve ver algo parecido com isto:

Adendo

Não sou muito fã de fazer muita coisa dentro do editor de texto, especialmente coias que já podem ser feitas de forma muito mais flexível pelo terminal, por isso que eu não uso a extensão Docker do Code para gerenciar ou executar o docker-compose. Também acho que funciona melhor assim, nesses casos em que você tem um projeto com vários contêineres com aplicações distintas, como no caso deste guia.

Como estamos gerenciando o fluxo manualmente, algumas vezes o VS Code vai exibir uma notificação destas:

Recomendo apenas clicar em Ignore. Se você precisar fazer o build novamente, é só parar o compose executando no terminal e rodar um docker-compose up --build de novo.

Conclusão

Têm vários pontos que podem ser melhorados e várias escolhar diferente que você pode fazer. Estas são as que eu fiz e que funcionam bem para mim, não necessariamente são as "certas".

Note que esta configuração toda é bem mais adequada a times pequenos ou indivíduos, já que times maiores têm outros requisitos, por vezes mutualmente exclusivos com algumas das decisões aqui tomadas.

Além disso, todo este guia é bem voltado ao desenvolvedor no trabalho diário, então não existem imagens reais que poderiam ser geradas para colocar a aplicação em produção, mas isso pode ser resolvido com um pouco mais de trabalho.

Obrigado por ler!

How to configure a Docker + VS Code development environment

David Rios — Wed, 07 Apr 2021 04:04:41 +0000

Há uma versão em português brasileiro aqui:

Como configurar um ambiente de desenvolvimento com Docker + VS Code

David Rios ・ Apr 7 '21

#vscode #docker #webdev #braziliandevs

After working with Docker for a while on some projects, I arrived at a configuration that works well for me and my colleagues, so I decided to share it in case it's useful to more people.

Keep in mind it's based on my personal experience, it might not use the best practices or apply to your case. Suggestions on improvements are welcome though!

I'll show you how to setup a full project from scratch and run it completely isolated within containers, so the environment will (hopefully) be reproducible and run the same, no matter your host OS.

I use Ubuntu as my daily driver, so this guide will be from that perspective, but you should be able to adapt it to your OS of choice without much trouble. It'll probably work well in Windows using WSL 2.

The project
Requirements
Starting out
The backend app
The frontend app
A simple nginx proxy
VS Code for the win
- Configuring for the backend
- Configuring for the frontend
Addendum
Conclusion

The project

To illustrate all steps, and be as realistic as possible, we'll create a basic web application using the following stack:

Backend: Python (Django)
Database: PostgreSQL
Frontend: VueJS (Quasar)

At the end we'll have a consistent environment for code editing with:

Code-completion
Linting
Debugging
Well defined editor settings for everyone working on the project

The stack choice is based on what I have more familiarity, but all the concepts in this guide should apply to any stack you choose.

Requirements

We need very few things installed locally:

Docker 19+ (a recent version)
docker-compose v1.27+
VS Code 1.5+

And these Code extensions:

Starting out

To make it easier for you to follow, I've set up a GitHub repository with all the code at https://github.com/davidrios/example-docker-project. I'll refer to specific commits so you can see the structure along the way.

We are starting the project from scratch, so the first thing we need is to sort out its structure. This is the one I like to use:

Project root
- some docker stuff and README
- conf
  - project 1
  - project 2
  - misc
  - ...
- code
  - project 1
  - project 2
  - ...

The next thing we need is to have some basic containers running to bootstrap the projects. We already know we need at least 3 containers from the project description: backend, frontend and database, so we need to create a base docker-compose.yml. But before that, one of the most useful things is to have a .env file, so you can have some amount of customization over the containers.

Let's create the initial .env.template file, that each user will make a local copy to customize:

LOCAL_USER_ID=1000
POSTGRES_PASSWORD=password

The LOCAL_USER_ID is used to work around Docker permission issues on Linux (more on that later). You set it with the uid of your local computer user as returned by the command id -u. You can just ignore it if you are on Mac.

After creating my local .env copy, it's time to define the basic docker-compose.yml:
https://github.com/davidrios/example-docker-project/blob/2aac6eb151104b205461d025ca07647c44bc5d36/docker-compose.yml

Things of note:

I import the .env file at lines 3-5, and pass all defined variables as environment vars to all the other containers. You can see that at lines 10-11, 19-20, etc.
I'm using Alpine images with major and minor versions specified, as per best practices. You may want or need to use an Ubuntu/Debian/etc based image, but you should aways choose specific major/minor versions.
There is a volume defined for the PostgreSQL data, so that is preserved between runs.
I run all projects I can as a standard (non root) user in the containers, and I like to create volumes for the home of that user on every container that I expect to log in and execute commands, that way I can have the shell history and other stuff preserved between rebuilds. That is an optional and personal preference, you can just remove those volumes. Be aware that, while using those volumes is convenient, they may have subtle effects on the overall reproducibility of the environment.
For the backend and frontend, since they don't have any application configured yet, but I need them running anyway to be able to bootstrap the apps, I just tell them to run a very long sleep.

At this time we can navigate to the main project repository and just run:

$ docker-compose up --build

You should see some messages from PostgreSQL about the initialization of the database and the three containers should keep running.

The backend app

I like to execute the app as a regular user, and to avoid issues of permissions on Linux, that user need to have the same uid as my local computer user, that's the reason for the LOCAL_USER_ID in the .env file. To do that we'll add some helper scripts to be used inside the container:

base.sh
run.sh
enter.sh

We'll add them to a directory conf/backend/scripts, as decided earlier. These scripts will only be executed on the dev environment, so they'll not be a part of the image.

We'll also create a Dockerfile for the container with some needed initial customizations. The compose file will be updated with the new image and mounts for the code and scripts. And the code directory will also be created and docker-compose will be executed again:

Check how the project has changed:

https://github.com/davidrios/example-docker-project/commit/04ae1e95ca8dfe752e76a67fce5b9882847f2f8e

## *** stop docker-compose ***
$ mkdir code
$ docker-compose up --build

Now we have the container running and ready to create the Django project. We use the enter.sh script to enter the container with the venv already activated and logged with the correct user. Now let's create the project:

## in another terminal at the root of the project folder:

## Create the database:
$ docker-compose exec -u postgres postgres-db createdb -T template0 -E utf8 backend

## Enter the backend container:
$ docker-compose exec backend /scripts/enter.sh

## Now inside the container:
$ cd /code
$ pip install --no-binary psycopg2 django psycopg2
$ django-admin startproject backend
$ cd backend

## Save the requirements:
$ pip freeze > requirements.txt

## *** Edit backend/settings.py to connect to the PostgreSQL db using the password from the environment and the host/dbname/user we already defined ***

$ python manage.py migrate
$ python manage.py createsuperuser
## *** insert desired login information ***

## Test the application runs:
$ python manage.py runserver

## *** Everything seems ok, stop the server and exit the container ***

Check the files added, with special attention to the database configuration:

https://github.com/davidrios/example-docker-project/commit/8f47c701e6a3984a32021da360ae0c49a2d68a95#diff-192a1d9e9543969133c5449ace7b1169de815b39d539bc55fc1d168f32eedb7bR76-R85

Now we need to set the application to run automatically with the container and to expose the port so we can access with our local browser. The installation of app packages will also be added to the image.

To be able to run locally on any port we choose and not conflict with other running stuff, we'll add that option to the .env.template file and the same line to our .env:

APP_PORT=8000

and update the docker stuff. Check the diff:

https://github.com/davidrios/example-docker-project/commit/c9276155e56f1f8c0168bb81902e5e0f22ed0dad

Now stop docker-compose and run it again, always with --build. The application should now be running and accessible at http://localhost:8000 (or other port if you changed it).

This is it for now for the backend. VS Code configuration instructions will follow later in the guide.

The frontend app

This one is pretty similar to the backend. We'll create the same three helper scripts, with specific changes for the new environment, and customize the image a bit.

At this time we'll also add a .dockerignore file, so that Docker doesn't have to copy useless stuff everytime it has to build an image. That'll speed up the process a lot if you already have a big project.

Take a look at the changes:

https://github.com/davidrios/example-docker-project/commit/bbb2c6180437c8e1ae5b3b0ca2121e78dc1250af

## *** We stop docker-compose and start it again ***
$ docker-compose up --build

We bootstrap the Quasar project the same way:

$ docker-compose exec frontend /scripts/enter.sh
$ yarn global add @quasar/cli
$ cd /code
$ ~/.yarn/bin/quasar create frontend
## *** choose quasar options ***
## Pick at least ESLint because it's used later.
## I'll also pick TypeScript to demonstrate the great VS Code support later
## And finally choose an ESLint preset you wanna use on your project. I'll stick with standard here
## Let Quasar install the packages with yarn and get out of the container

Now we'll configure the frontend container to start Quasar in dev mode automatically and export the port so that we can access it.

Here's the resulting changes:

https://github.com/davidrios/example-docker-project/commit/73e3b55df164ea2e1477cb51a8d591299c5f4643

Note that we just moved the export port from the backend to the frontend container, we'll fix that in a bit.

## *** We stop docker-compose and start it again ***
$ docker-compose up --build

The Quasar app should now be running and accessible at http://localhost:8000 (or other port if you changed it).

A simple nginx proxy

To make our lives easier, we'll create a simple but flexible nginx proxy in front of everything. We need to use a custom config file, and for maximum flexibility we'll process the config and interpolate with the env vars before starting the server.

These are the resulting changes:

https://github.com/davidrios/example-docker-project/commit/b07c83199fd8d4b1cd4dfce1e830a19e76b64543

We can now access the frontend app at http://localhost:8000, the Django admin at http://localhost:8000/admin and nginx will also proxy all requests to /api* to the backend app.

VS Code for the win

Now that we have our whole project well organized and running isolated from our local machine, we need to start coding it. Wouldn't it be awesome if we could have the same consistent and pleasant experience while coding as well? That's when VS Code comes to the rescue!

We'll use the remote containers extension to run VS Code directly inside the app containers, so it'll have access to the environment exactly as it runs and we can install extensions without affecting our local installation.

We will be using a directory named code/vscode to put related stuff, just so it is already available inside the containers because of the /code mount. You could put it in another directory, but then you would have to setup another mount for each container.

Configuring for the backend

First create the directory code/vscode/backend and add the following files:

backend.code-workspace: Replace backend with the real nome of your project, so it's easier to pick the Code windows apart when navigating.
flake8.ini: Where we put the linter settings for Python. We'll be using flake8 instead of pylint, since it is much faster and I like it better :).
.devcontainer.json: Tells Code how to setup the container instance

It's also necessary to edit the container base.sh script, so it installs necessary packages after any rebuild and also to start Python in debug mode. As a nice touch we'll also configure the server to autoreload when any file changes using Watchdog, since the Code debugger extension for Python doesn't suport Django's autoreload. As a bonus, watchdog uses much less CPU than Django's default autoreloader.

I've gone ahead and added our first test API.

Check it out:

https://github.com/davidrios/example-docker-project/commit/33cb5d775b88d8b953ba690c17e1359dd5fa34a5

Now all we have to do is stop compose and run it again, all should be running and ready. To start working with the code we open a new Code window (Ctrl+Shift+N) and go to File > Open Folder and open the <PROJECT>/code/vscode/backend directory. Right away a notification should appear, you just click the Reopen in Container button. You can also open the command palette (Ctrl+Shift+P) and type reopen in container and pick Remote-Containers: Reopen in container. Then, it'll show a notification that it's installing the Code server and after a few moments it should open the project, and there will be an indication at the status bar that you are inside the container, like this:

Then you will have all editor goodies, like this:

And to debug, you just click the gutter to add a breakpoint, or press F9 at the desired line, like this:

Then go to the Run view clicking at the side, and click the little green "play" button. The status bar should turn to orange to indicate the debugger is connected. If you have a breakpoint, like I did here, and navigate to the new API in the browser, you will be greeted with glorious debugging goodness, like this:

Each time you change some file the app will also reload, like this:

And if you need to run any Django administration commands, you can do so easily with the integrated terminal. Just open the menu Terminal > New Terminal (Ctrl+Shift+<BACKTICK>), like this:

If you find that the terminal did not have the venv activated, just click the trash icon to kill it and open it up again.

Configuring for the frontend

The configuration here is similar to the above. First create the directory code/vscode/frontend and add the file .devcontainer.json. I'm not configuring a project file here because there's no other folder besides the frontend project and to also use the settings files Quasar already creates when initializing the project. You could very well move everything to a project file just like we did with the backend.

Here're the results:

https://github.com/davidrios/example-docker-project/commit/644b7547322d903f7e4b33454b787e5d1d4c6f49

You don't even need to rerun docker-compose, just open a new Code window, open the directory code/vscode/frontend and click the Reload in Container button. After opening the project, click the ESLint button at the status bar and click to allow when the dialog appears. No you will have a fully configured editor, like so:

You get even autocomplete for things like Quasar components!

If you wand to use the quasar-cli to do things like create a component, you just open the inbuilt terminal clicking on menu Terminal > New Terminal (Ctrl+Shift+<BACKTICK>), like this:

Now its time to debug!

To do that, we create a launch.json with debug tasks for VS Code. This is not so trivial for some reasons:

VS Code has two Chrome debuggers, one newer that ships with it and the old one you can install from the marketplace. The problem is the newer is better, but for some reason, and I suspect it has to do with the remote container, it can't launch Chrome instances. The old one can launch instances, but is not so good. So to solve our problems we can use both!
Since we have a custom port defined in our .env file, we need some way to pass that to the debug task. Unfortunately the debug extensions runs at the local editor, not the remote one, so they don't have access to env vars. To solve that I added a little prompt when running the task that asks which port the app is running at, with the default from the env template for convenience.

The added tasks file:

https://github.com/davidrios/example-docker-project/blob/6e5195fd13d2aea79b1a31c265ddf60808d9a77e/code/frontend/.vscode/launch.json

We have three tasks which you will use depending on your browser:

Attach to Chrome: This task uses the newer debugger to attach to a running Chrome instance with remote debugging enabled, and you don't need to install anything else. Check here how to run Chrome with remote debugging enabled
Launch Chrome: This one launches an instance of Chrome with remote debugging already enabled and using a new profile, so it doesn't affect your personal one. To use this task you need to have the Debugger for Chrome extension installed.
Launch Firefox: And this launches an instance (or attaches to one if running) of Firefox with remote debugging enabled and also using a new profile. To use this task you need to have the Debugger for Firefox extension installed.

There's one more thing we can do to make our lives better while debugging. The default webpack config doesn't generate detailed sourcemaps, which makes debugging a pain and pretty much impossible to set breakpoints in transpiled files. We fix that by adding devtool: 'eval-source-map' to its settings.

Even then, for transpiled files like .vue files, it generates a lot of variants of the same file with different hash names for each of the intermediate results, which is kind of annoying, so we fix that too by customizing the output.devtoolModuleFilenameTemplate function.

Since this project is in Quasar, we do that the way its supposed to, by editing quasar.conf.js.

It ends up looking like this:

https://github.com/davidrios/example-docker-project/commit/1208e30bd280179df0780add22430af3a54c6c30

Now you can run the debugger by going to the Run view, selecting a task and clicking "play":

Try adding some console.logs and/or setting a breakpoint, running debug mode and using the app, then you should see something like this:

Addendum

I'm not a huge fan of doing too much inside the code editor, especially things which are much more flexible to do in the terminal, that's why I don't use the Code Docker extension to manage/run docker-compose for example. I also think it works better that way when you have a project with several containers with different apps, like in this guide.

Since we are managing the compose flow manually, sometimes VS Code can show you this notification:

I recommend you to just click Ignore. If you need to rebuild things, just stop the compose running at the terminal and execute docker-compose up --build again.

Conclusion

There are a lot of things to improve and different choices you could make for the various pieces, these are the ones I made and that worked the best for me.

Do note that this whole configuration is better suited to individuals and small teams, there are other, often mutually-exclusive, requirements for larger teams.

This is all very development focused, so the container images are not real ones that you can use to deploy, but that is doable with a little more work.

Thanks for reading!

DEV Community: David Rios

Localizing a real world Vue.js app [part 1]

The app

Starting up

Loading the locale files

Live reload of locale files

Separating catalogs

Some localization examples

Localizing content with tags

Managing fluent catalogs

Como configurar um ambiente de desenvolvimento com Docker + VS Code

How to configure a Docker + VS Code development environment

David Rios ・ Apr 7 ・ 13 min read

Tabela de Tópicos

O Projeto

Requisitos

Começando

A aplicação backend

A aplicação frontend

Um proxy nginx simples

VS Code para o alto e avante!

Configurando para o backend

Configurando para o frontend

Adendo

Conclusão

How to configure a Docker + VS Code development environment

Como configurar um ambiente de desenvolvimento com Docker + VS Code

David Rios ・ Apr 7 '21

Table of Contents

The project

Requirements

Starting out

The backend app

The frontend app

A simple nginx proxy

VS Code for the win

Configuring for the backend

Configuring for the frontend

Addendum

Conclusion