Carol App usando um template disponível na Carol
Esta seção descreve como criar o Carol App usando o modelo disponível na Carol. Atualmente, você pode criar três tipos de aplicativos Carol:
- Online Carol App
- Batch Carol App
- Web Carol App
As seções a seguir explicam detalhes sobre como criar esses aplicativos na Carol através do assistente fornecido pela Carol.
Primeiro passo para criar um aplicativo Carol
Esta seção demonstrará como iniciar o assistente para criar um dos três possíveis aplicativos Carol, conforme já descrito na seção anterior.
Por favor, execute o seguinte comando:
bash -c "$(curl -fsSL https://raw.github.com/totvslabs/carolapp/master/install.sh)"
Como resultado, a seguinte informação é mostrada ao usuário:
____ _ _
/ ___|__ _ _ __ ___ | | / \ _ __ _ __
| | / _` | '__/ _ \| | / _ \ | '_ \| '_ \
| |__| (_| | | | (_) | |/ ___ \| |_) | |_) |
\____\__,_|_| \___/|_/_/ \_\ .__/| .__/
|_| |_|
This script will help you create your new Carol App.
Just select which type of Carol App you want to create and answer the questions the script will ask about your new app.
? Which Carol App do you want to create? (Use arrow keys)
❯ Online App
Batch App
Web App
O principal objetivo do usuário é escolher o tipo de aplicativo Carol que ele deseja, seguindo a explicação no capítulo Introdução.
Dependendo da seleção do usuário, o processo orientará o usuário a criar um dos três aplicativos Carol disponíveis. Você precisa usar as setas para alterar sua seleção.
Dependendo do tipo de aplicativo Carol, você precisa seguir a documentação específica.
Repositórios de Exemplos
Estamos mantendo um repositório com alguns Carol App como exemplo. A estrutura segue exatamente a mesma apresentada nesta documentação.
https://github.com/totvslabs/carolapp-samples
Online App
Esta seção descreve como criar um Online Carol App a partir do modelo da Carol.
Para iniciar o processo de criação de um Carol App, você precisa executar o seguinte comando:
bash -c "$(curl -fsSL https://raw.github.com/totvslabs/carolapp/master/install.sh)"
Depois de optar por criar um Online Carol App, a seguinte pergunta pode aparecer caso essa não seja a primeira vez que você executa esse processo:
Você pode pressionar enter, enviando yes, para que esse processo faça o download dos arquivos novamente para garantir que você esteja executando os modelos mais atualizados.
Depois disso, todo o processo fará as seguintes perguntas:
full_name [Totvs Labs]: Robson Poffo
email [info@totvslabs.com]: robson.poffo@totvs.com
github_username [totvslabs]:
project_name [Carol App Boilerplate]: First Online App
project_slug [first_online_app]:
project_short_description [Carol App Boilerplate contains all the boilerplate you need to create a Carol App.]: This is the description related to my project. Used inside the manifest file.
version [0.1.0]:
sonarqube [True]:
carol_app_organization [my_organization]: poffo
carol_app_tenant [my_tenant]: poffo
algorithm_name [alg_first_online_app]: server
algorithm_description_en_US [Algorithm Description]: Process responsible to make available all services for my first online carol app.
algorithm_description_pt_BR [Descrição do Algoritmo]: Processo responsavel em tornar disponivel todos os serviços relacionados ao meu primeiro online carol app.
carol_app_docker_image [carol/first_online_app:0.1.0]:
pycarol_version [latest]:
Select carol_app_machine_types:
1 - c1.nano
2 - c1.micro
3 - c1.small
4 - c1.medium
5 - c1.large
6 - c1.xlarge
7 - c1.2xlarge
8 - g1.v100.large
9 - g1.v100.xlarge
Choose from 1, 2, 3, 4, 5, 6, 7, 8, 9 (1, 2, 3, 4, 5, 6, 7, 8, 9) [1]: 1
First Online App created successfully.
✔ Your new Carol App was successfull created. Check Carol App documentation to learn more.
Esta é uma breve descrição para cada parâmetro solicitado:
| Parâmetro | Descrição |
|---|---|
| full_name | O usuário que está criando este aplicativo. Esta informação é usada para fins internos. |
| O usuário que está criando este aplicativo. Esta informação é usada para fins internos. | |
| github_username | O usuário que está criando este aplicativo. Esta informação é usada para fins internos. |
| project_name | O nome do projeto é usado para identificar o projeto e atualizar o arquivo Readme.md. |
| project_slug | O projeto Slug é usado para criar a pasta do seu projeto. |
| project_short_description | É usado para atualizar o arquivo Readme.md. |
| version | É usado para referência interna para este aplicativo e para atualizar o arquivo Readme.md. |
| sonarqube | Caso você o habilite, o processo preparará o projeto para executar o sonarqube |
| carol_app_organization | A organização da Carol onde este projeto será implantado. |
| carol_app_tenant | Carol's tenant where this project will be deployed. |
| algorithm_name | O nome do algoritmo é o algoritmo usado no arquivo de manifesto. Para referência relacionada ao arquivo de manifesto, consulte o capítulo Manifest file nesta documentação para obter mais detalhes. |
| algorithm_description_en_US | A descrição do algoritmo (US) é usada para compartilhar informações com o usuário na interface da Carol. Esta informação será atualizada no arquivo de manifesto. Consulte a seção Manifest file para mais informações sobre este arquivo. |
| algorithm_description_pt_BR | A descrição do algoritmo (PT) é usada para compartilhar informações com o usuário na interface da Carol. Esta informação será atualizada no arquivo de manifesto. Consulte a seção Manifest file para mais informações sobre este arquivo. |
| carol_app_docker_image | A imagem do docker fornecida neste momento atualizará o Dockerfile para criar a imagem do Docker com o nome especificado e atualizar o arquivo de manifesto. Quando você executa esse aplicativo, ele procura o nome do Docker especificado aqui. |
| pycarol_version | Versão PyCarol refere-se à versão pyCarol que este aplicativo tem dependência. O arquivo requirements.txt será atualizado com essas informações. |
| carol_app_machine_types | Este é o tipo de instância para executar este aplicativo. Para verificar todos os tipos de instância possíveis, verifique a seção Tipos de instância de aplicativo Carol. |
Depois de concluir o processo, você verá a seguinte mensagem de sucesso:
Esta mensagem significa que está tudo bem. Você pode inserir a nova pasta criada (slug) e podemos começar a explorar as opções make disponíveis.
Os seguintes comandos estão disponíveis quando executamos o comando make.
$ make
first_online_app Makefile help.
all_tests Runs all test related tasks
build_ci Build CI Docker Image
clean Cleans all temporary and preprocessed files
code_scan Execute a Code Qualiry scan and send the data to SonarQube server
coverage Create XML and HTML Test coverare report.
dev Install all development packages dependencies
dist Create the dist file to deploy on Carol
docker_image Build first_online_app-server Carol app docker image
docker_run Runs first_online_app-server Carol app docker image
docker_run_dev Runs first_online_app-server Carol app docker image in Development mode using local code
docs Compile all package documentation in HTML format
help Show this help message
htmlcov Opens the current test coverage report on the default browser
init Install all package dependencies
lint Lint all code for best practicies
run Runs the online app locally on http://localhost:5000
test Runs all project test suite, recording all test converage data
venv Create the virtualenv for this Carol App
A imagem do docker fornecida por make cria a imagem localmente. Na seção Criando a imagem do Docker na Carol, explicaremos como criar a imagem do docker na plataforma, disponibilizando a imagem do docker para qualquer aplicativo Carol executado no topo da plataforma Carol.
Construindo a imagem do Docker
Se você quiser testar sua imagem local em seu próprio registro do docker, poderá criar a imagem usando o comando make, marcar sua imagem para prepará-la para o envio e, depois, precisará enviá-la para seu registro. Estes são os comandos para executá-lo:
Primeiro, criamos a imagem (certifique-se de ter o docker instalado em sua máquina):
$ make docker_image
Este comando retornará algo semelhante:
.....
Successfully built e0102c0e1526
Successfully tagged first_online_app:latest
Em seguida, marcamos a imagem para prepará-la para envio ao registro do Docker (certifique-se de usar a tag certa):
docker tag first_online_app:0.1.0 robsonpoffo/first_online_app:0.1.0
A última etapa é enviá-lo para o seu próprio Docker Registry. Se você não possui, verifique as etapas aqui: https://docs.docker.com/registry/
docker push robsonpoffo/first_online_app:0.1.0
Este comando retornará algo semelhante:
The push refers to repository [docker.io/robsonpoffo/first_online_app-server]
3dee5a222cd4: Pushed
84430b4585a1: Pushed
95e360319baa: Pushed
348c3d784eca: Pushed
e5cf317c6146: Pushed
7d1b621fef71: Pushed
93a8b7ed8c52: Pushed
3f975a33acbf: Pushed
69168fb9b7b0: Pushed
31f78d833a92: Pushed
2ea751c0f96c: Pushed
7a435d49206f: Pushed
9674e3075904: Pushed
831b66a484dc: Pushed
latest: digest: sha256:2b6d8b6cd660d783544d4710a4532a965fcf1d52f92004618d9a11b4ec421d59 size: 3261
Atualizando a imagem do Docker no arquivo Manifest
Depois disso, você pode atualizar seu arquivo de manifesto e testar a Imagem do Docker dentro da Carol:
{
"online": {
"processes": [{
"algorithmDescription": {
"en-US": "Online Description",
"pt-BR": "Descrição do Online app"
},
"algorithmName": "online_app",
"algorithmTitle": {
"en-US": "Online Description",
"pt-BR": "Descrição do Online app"
},
"instanceProperties": {
"profile": "",
"properties": {
"instanceType": "c1.micro",
"dockerImage": "online_app",
"autoscale": {
"enabled": true,
"minReplicas": 1,
"maxReplicas": 4
},
"healthcheck": {
"path": "/healthy"
},
"port": 8080,
"preemptible": true
}
},
"name": "online_carolapp"
}]
},
}
Caso você queira obter mais informações sobre os parâmetros acima → Veja a seção compreendendo o arquivo de manifesto.
O Online Carol App suporta apenas um item em "processos". Caso você queira obter mais informações, → Veja a seção manifesto de carol app.
O dockerImage foi alterado para obter a imagem de um registro do docker externo. Para obter a imagem do docker do registro da Carol, você precisa criar a imagem do docker na Carol.
O parâmetro healthcheck se faz necessário no manifesto, para que a aplicação possar ser monitorada.
Implantando o Online Carol App na Carol
Depois disso, na Carol:
- Faça o upload do arquivo de manifesto:
- Execute a tarefa:
- Veja a nova URL disponível:
Batch App
Esta seção descreve como criar um aplicativo de Lote na Carol a partir do modelo da Carol.
Para iniciar o processo de criação de um Carol App, você precisa executar o seguinte comando:
bash -c "$(curl -fsSL https://raw.github.com/totvslabs/carolapp/master/install.sh)"
Depois de optar por criar um aplicativo Batch Carol, a seguinte pergunta pode aparecer caso essa não seja a primeira vez que você executa esse processo:
Você pode pressionar enter, enviando yes, para que esse processo faça o download dos arquivos novamente para garantir que você esteja executando os modelos mais atualizados.
Depois disso, todo o processo fará as seguintes perguntas:
full_name [Totvs Labs]: Robson Poffo
email [info@totvslabs.com]: robson.poffo@totvs.com
github_username [totvslabs]:
project_name [Carol App Batch Boilerplate]: First Batch App
project_slug [first_batch_app]:
project_short_description [Carol App Batch Boilerplate contains all the boilerplate you need to create a Carol App.]: This is the description related to my project. Used inside the manifest file.
version [0.1.0]:
sonarqube [True]:
carol_app_organization [my_organization]: poffo
carol_app_tenant [my_tenant]: poffo
algorithm_name [first_batch_app_algorithm]: process_data
algorithm_description_en_US [Batch task Description]: Process responsible to read data from Carol, run the processing it is responsible for and send the final result back to Carol.
algorithm_description_pt_BR [Descrição do Tarefa Batch]: Processo responsavel por ler os dados da Carol, executar os procedimentos no qual ele se propos a fazer e enviar o resultado final para Carol.
luigi_workers [4]:
carol_app_docker_image [carol/first_batch_app:0.1.0]:
pycarol_version [latest]:
Select carol_app_machine_types:
1 - c1.nano
2 - c1.micro
3 - c1.small
4 - c1.medium
5 - c1.large
6 - c1.xlarge
7 - c1.2xlarge
8 - g1.v100.large
9 - g1.v100.xlarge
Choose from 1, 2, 3, 4, 5, 6, 7, 8, 9 (1, 2, 3, 4, 5, 6, 7, 8, 9) [1]: 1
First Batch App created successfully.
✔ Your new Carol App was successfull created. Check Carol App documentation to learn more.
Esta é uma breve descrição para cada parâmetro solicitado:
| Parâmetro | Descrição |
|---|---|
| full_name | O usuário que está criando este aplicativo. Esta informação é usada para fins internos. |
| O usuário que está criando este aplicativo. Esta informação é usada para fins internos. | |
| github_username | O usuário que está criando este aplicativo. Esta informação é usada para fins internos. |
| project_name | O nome do projeto é usado para identificar o projeto e atualizar o arquivo Readme.md. |
| project_slug | O projeto Slug é usado para criar a pasta do seu projeto. |
| project_short_description | É usado para atualizar o arquivo Readme.md. |
| version | É usado para referência interna para este aplicativo e para atualizar o arquivo Readme.md. |
| sonarqube | Caso você o habilite, o processo preparará o projeto para executar o sonarqube |
| carol_app_organization | A organização da Carol onde este projeto será implantado. |
| carol_app_tenant | Carol's tenant where this project will be deployed. |
| algorithm_name | O nome do algoritmo é o algoritmo usado no arquivo de manifesto. Para referência relacionada ao arquivo de manifesto, consulte o capítulo Manifest file nesta documentação para obter mais detalhes. |
| algorithm_description_en_US | A descrição do algoritmo (US) é usada para compartilhar informações com o usuário na interface da Carol. Esta informação será atualizada no arquivo de manifesto. |
| Consulte a seção Manifest file para mais informações sobre este arquivo. | |
| algorithm_description_pt_BR | A descrição do algoritmo (PT) é usada para compartilhar informações com o usuário na interface da Carol. Esta informação será atualizada no arquivo de manifesto. |
| Consulte a seção Manifest file para mais informações sobre este arquivo. | |
| carol_app_docker_image | A imagem do docker fornecida neste momento atualizará o Dockerfile para criar a imagem do docker com o nome especificado e atualizar o arquivo de manifesto. Quando você executa esse aplicativo, ele procura o nome do docker especificado aqui. |
| pycarol_version | Versão PyCarol refere-se à versão pyCarol que este aplicativo tem dependência. O arquivo requirements.txt será atualizado com essas informações. |
| carol_app_machine_types | Este é o tipo de instância para executar este aplicativo. Para verificar todos os tipos de instância possíveis, verifique a seção Tipos de instância de aplicativo Carol. |
Depois de concluir o processo, você verá a seguinte mensagem de sucesso:
Esta mensagem significa que está tudo bem. Você pode inserir a nova pasta criada (slug) e podemos começar a explorar as opções "make" disponíveis.
Os seguintes comandos estão disponíveis quando executamos o comando "make".
$ make
first_batch_app Makefile help.
all_tests Runs all test related tasks
build_ci Build CI Docker Image
clean Cleans all temporary and preprocessed files
code_scan Execute a Code Qualiry scan and send the data to SonarQube server
coverage Create XML and HTML Test coverare report.
dev Install all development packages dependencies
dist Create the dist file to deploy on Carol
docker_image Build the Carol App docker image
docs Compile all package documentation in HTML format
help Show this help message
htmlcov Opens the current test coverage report on the default browser
init Install all package dependencies
lint Lint all code for best practicies
run Runs the Batch process locally
test Runs all project test suite, recording all test converage data
venv Create the virtualenv for this Carol App
Batch Carol App pode ter vários processos. Durante o fluxo de criação, ele pede apenas um, mas a qualquer momento você pode acessar o arquivo manifest e adicionar mais processos, conforme necessário. A imagem do docker fornecida por make cria a imagem localmente. Na seção "Criando a imagem do Docker na Carol", explicaremos como criar a imagem do docker na plataforma, disponibilizando a imagem do docker para qualquer aplicativo Carol executado no topo da plataforma Carol.
Construindo a imagem do Docker
Se você quiser testar sua imagem local em seu próprio registro do docker, poderá criar a imagem usando o comando make, marcar sua imagem para prepará-la para o envio e, depois, precisará enviá-la para seu registro. Estes são os comandos para executá-lo:
Primeiro, construímos a imagem:
make docker_image
.....
Successfully built b0bf90002a7d
Successfully tagged first_batch_app-process_data:0.1.0
docker tag first_batch_app-process_data:0.1.0 robsonpoffo/first_batch_app-process_data:0.1.0
A última etapa é enviá-lo para o seu próprio Docker Registry. Se você não possui, verifique as etapas aqui: https://docs.docker.com/registry/
docker push robsonpoffo/first_batch_app-process_data:0.1.0
Este comando retornará algo semelhante:
The push refers to repository [docker.io/robsonpoffo/first_batch_app-process_data]
ddb9ffc5b1b9: Pushed
bbe6a88aa3cf: Pushed
f8be782735d6: Mounted from robsonpoffo/first_batch_app
165b81c874a8: Mounted from robsonpoffo/first_batch_app
e5cf317c6146: Mounted from robsonpoffo/first_online_app
7d1b621fef71: Mounted from robsonpoffo/first_online_app
93a8b7ed8c52: Mounted from robsonpoffo/first_online_app
3f975a33acbf: Mounted from robsonpoffo/first_online_app
69168fb9b7b0: Mounted from robsonpoffo/first_online_app
31f78d833a92: Mounted from robsonpoffo/first_online_app
2ea751c0f96c: Mounted from robsonpoffo/first_online_app
7a435d49206f: Mounted from robsonpoffo/first_online_app
9674e3075904: Mounted from robsonpoffo/first_online_app
831b66a484dc: Mounted from robsonpoffo/first_online_app
0.1.0: digest: sha256:e9b9d1d347ecb4c53b664595b1472c3005c43ce36855e90ce28db3382028fd32 size: 3261
Atualizando a imagem do Docker no arquivo Manifest
Depois disso, você pode atualizar seu arquivo de manifesto e testar a Imagem do Docker dentro da Carol:
{
"batch": {
"processes": [
{
"algorithmDescription": {
"en-US": "Process responsible to read data from Carol, run the processing it is responsible for and send the final result back to Carol.",
"pt-BR": "Processo responsavel por ler os dados da Carol, executar os procedimentos no qual ele se propos a fazer e enviar o resultado final para Carol.",
"pt-br": "Processo responsavel por ler os dados da Carol, executar os procedimentos no qual ele se propos a fazer e enviar o resultado final para Carol."
},
"algorithmName": "process_data",
"algorithmTitle": {
"en-US": "Process responsible to read data from Carol, run the processing it is responsible for and send the final result back to Carol.",
"pt-BR": "Processo responsavel por ler os dados da Carol, executar os procedimentos no qual ele se propos a fazer e enviar o resultado final para Carol."
},
"instanceProperties": {
"tenants": {
"EXAMPLE_ENV_1": "value_1",
"EXAMPLE_ENV_2": "value_2"
},
"keepInstance": "false",
"luigi": {
"workers": "4"
},
"profile": "",
"properties": {
"dockername": "first_batch_app-process_data"
}
},
"name": "first_batch_app"
}
]
}
}
Batch Carol App suporta quantos processos em "processos" que você precisa. Caso você queira obter mais informações, verifique a seção Manifest file.
O "dockerImage" foi alterado para obter a imagem de um registro do docker externo. Para obter a imagem do docker do registro da Carol, você precisa criar a imagem do docker na Carol.
Implantando o Batch Carol App na Carol
Depois disso, na Carol:
- Faça o upload do arquivo de manifesto:
- Execute a tarefa:
- Veja que a tarefa foi executada com sucesso:
Web App
Esta seção descreve como criar um aplicativo Web Carol a partir do modelo da Carol.
Para iniciar o processo de criação de um Carol App, você precisa executar o seguinte comando:
bash -c "$(curl -fsSL https://raw.github.com/totvslabs/carolapp/master/install.sh)"
Após optar por criar um aplicativo Web Carol, a seguinte pergunta pode aparecer caso essa não seja a primeira vez que você executa esse processo:
Você pode pressionar enter, enviando yes, para que esse processo faça o download dos arquivos novamente para garantir que você esteja executando o modelo mais atualizado.
Depois disso, o processo fará as seguintes perguntas:
user_full_name [TotvsLabs User]: Robson Poffo
user_email [info@totvslabs.com]: robson.poffo@totvs.com
github_username [totvslabs]:
project_name [Carol App Boilerplate]: First Web App
project_slug [first_web_app]:
project_short_description [Carol App Web Boilerplate contains all the boilerplate you need to create a Carol App.]: This is the description related to my project. Used inside the manifest file.
carol_app_organization [my_organization]: poffo
carol_app_tenant [my_tenant]: poffo
version [0.1.0]:
First Web App created successfully.
✔ Your new Carol App was successfull created. Check Carol App documentation to learn more.
Esta é uma breve descrição para cada parâmetro solicitado:
| Parâmetro | Descrição |
|---|---|
| user_full_name | O usuário que está criando este aplicativo. Esta informação é usada para fins internos. |
| user_email | O usuário que está criando este aplicativo. Esta informação é usada para fins internos. |
| github_username | O usuário que está criando este aplicativo. Esta informação é usada para fins internos. |
| project_name | O nome do projeto é usado para identificar o projeto e atualizar o arquivo Readme.md. |
| project_slug | O projeto Slug é usado para criar a pasta do seu projeto. |
| project_short_description | É usado para atualizar o arquivo Readme.md. |
| carol_app_organization | A organização da Carol onde este projeto será implantado. |
| carol_app_tenant | Carol's tenant where this project will be deployed. |
| version | É usado para referência interna para este aplicativo e para atualizar o arquivo Readme.md. |
Depois de concluir o processo, você verá a seguinte mensagem de sucesso:
Esta mensagem significa que está tudo bem. Você pode inserir a nova pasta criada (slug) e podemos começar a explorar as opções make disponíveis.
Os seguintes comandos estão disponíveis quando executamos o comando make.
make
first_web_app Makefile help.
build Build Carol Web App
clean Clean this project
datamodels Updates all data models from your Carol Tenant (requires Carol User and Password)
help Show this help message
install Install all project dependencies
lint Check the project source code for good practicies
run Starts a dev webserver at http://localhost:3000/
test Test current project. Runs all unit and end to end tests
Construindo o Angular dist
O comando make install instala a CLI Angular e todas as dependências descritas em package.json.
Depois disso, você pode executar o comando make build, este comando executa o ng build --prod para gerar o dist.
Implantar o aplicativo Web Carol Na Carol
Depois disso, na Carol:
- Faça o upload do arquivo zip da Web:
IMAGE
- Acesse o URL.
IMAGE
Storage
Ao desenvolver um Carol App que gera um arquivo ao final do processo, é importante evitar adicionar espaços em branco ao nomear o arquivo, pois a URL é codificada traduzindo o caracter branco para %20, fazendo com que se refira a um arquivo que não existe. Portanto, recomenda-se utilizar um caracter válido em substituição ao espaço em branco, como um traço alto - ou baixo _.
