-
Notifications
You must be signed in to change notification settings - Fork 1
Guia de Configuração e Implantação
Este guia é voltado para desenvolvedores e administradores de sistemas que têm interesse em hostear a aplicação do BDance e / ou contribuir com o seu desenvolvimento. Para a versão mais atual, visite a página deste guia na wiki do BDance.
O BDance é uma aplicação web de código aberto construída com o framework Rails para a linguagem de programação Ruby. É pré-requisito, portanto, a presença desses dois componentes no ambiente de desenvolvimento ou produção em que a aplicação será executada.
A configuração de um ambiente Ruby on Rails não deve ser uma atividade muito laboriosa e a utilização de ferramentas como o Ruby Version Manager e Bundler deve facilitar todo o processo. Documentação a respeito é prolífica e disponível livremente na web, bem como tutoriais sobre o tema (veja a seção de referências).
Uma vez que o ambiente estiver devidamente configurado, é necessário dispor do código da aplicação para a sua execução. O código pode ser obtido gratuitamente, já que se trata de uma aplicação de código aberto. O repositório central do BDance é mantido no Github e pode ser baixado através do git. Informações mais detalhadas sobre como fazer isso são dispostas no anexo A.
Com o código em mãos, deve-se, antes de rodar o servidor da aplicação, criar e configurar adequadamente um Sistema de Gerenciamento de Banco de Dados (SGBD) para a persistência das entidades do modelo (usuários, turmas, modalidades e tudo o mais). O framework Rails provê uma camada de abstração que permite a utilização de diversos SGBD’s. Para mais informações sobre como criar o banco e as tabelas que a aplicação utliza e configurar a aplicação para se conectar ao SGBD, consulte o anexo B.
Pronto. Uma vez que o banco está criado e a aplicação devidamente configurada para utilizá-lo, já é possível rodar o servidor e usufruir dos serviços oferecidos pelo BDance. No entanto, antes disso, há alguns detalhes para os quais se deve atentar com vistas a estabelecer o funcionamento pleno de funcionalidades que demandam configuração adicional, como a autenticação com Facebook. Para saber, detalhadamente, como criar uma aplicação no Facebook e configurar sua instância do BDance para utilizá-la, consulte o anexo C.
O framework Rails provê um servidor built-in para a execução rápida da aplicação web. Para iniciá-lo, basta executar, na linha de comando:
$ rails s
Esse comando instancia o servidor, que torna a aplicação acessível (localmente) através do endereço http://localhost:3000. A utilização desse servidor web, no entanto, não é aconselhada para ambientes de produção. Para mais informações sobre como implantar aplicações Ruby on Rails em ambiente de produção, aconselha-se visitar as páginas indicadas na seção de referências.
Como desenvolvedor, a primeira coisa interessante a se fazer (já com o ambiente de desenvolvimento configurado como mencionado acima) é rodar os testes. O BDance implementa, atualmente, testes de modelo, controladores, views, rotas e requisições através da ferramenta para testes automatizados RSpec.
Para execução bem sucedida dos testes, é necessário que as configurações para o banco de testes sejam feitas adequadamente (se tiver dúvidas quanto a isso, consulte o anexo B). Para implantar o banco de testes, execute o comando
$ rake db:test:prepare
e, depois, para executar os testes:
$ rspec
todos devem passar, idealmente.
Os testes garantem que seu ambiente de desenvolvimento está devidamente configurado e que, portanto, está pronto para dar suporte à implementação das suas incríveis contribuições! Depois que tiver implementado tudo, crie um pull request (veja o anexo D para consultar especificidades sobre como isso deve ser feito). Não esqueça de, antes de criar o pull request, executar todos os testes e ter certeza de que todos passam.
Ideias, sugestões e questões relacionadas ao código são mantidas através de issues do Github. Sinta-se livre para criar novos issues e, se você for criar algum a respeito de problemas no código, consulte o anexo E.
- Executando aplicações Ruby on Rails na nuvem com o Nitrous.io
- Configuração do ambiente e introdução ao desenvolvimento Ruby on Rails
- Deploy de aplicações Rails no Heroku
- Deploy de aplicações no Heroku usando o Git (tutorial em inglês)
- Guia completo, em inglês, para configuração e implantação de aplicações Ruby on Rails no Heroku
- Instalação e configuração manual do SGBD PostgreSQL no Linux
- Dicas sobre como utilizar issues no Github
- Pull requests dentro de um mesmo repositório, através de branches distintos
Clonar o repositório é fácil e o único requisito é ter o git instalado em sua máquina. Se você precisar de ajuda pra configurar o git, pode consultar este guia do Github.
Com o git configurado, basta executar o comando clone da ferramenta. Por exemplo, navegando no diretório /Code, eu posso simplesmente:
embs@duff ~/Code $ git clone https://github.com/embs/bdance
Isso irá clonar o repositório principal do BDance usando o protocolo HTTPS. Alternativamente, você pode clonar o repositório usando o protocolo SSH com uma sintaxe muito parecida:
embs@duff ~/Code $ git clone [email protected]:embs/bdance.git
O comando clone criará um diretório chamado bdance no diretório Code (para os exemplos citados). É possível criar um subdiretório com um nome arbitrário da seguinte maneira:
embs@duff ~/Code $ git clone [email protected]:embs/bdance.git nomeArbitrário
Este anexo não aborda como instalar e configurar um SGBD na sua máquina. Por isso, utiliza-se o SQLite, que é um engenho de banco de dados auto-contido que facilitará o processo de rápida execução dos passos descritos a seguir.
Alternativas populares (como o PostgreSQL e MySQL) poderiam ser utilizadas sem grandes alterações nos arquivos de configuração do Rails. No entanto, para utilizá-las, você deverá pesquisar como instalar e configurar o SGBD por conta própria.
Aplicações Rails utilizam o arquivo database.ym para saber como se conectar ao banco de dados disponível no ambiente (de produção, desenvolvimento ou testes). Uma configuração simples para o SQLite seria a seguinte:
development:
adapter: sqlite3
database: db/development.sqlite3
pool: 5
timeout: 5000
test:
adapter: sqlite3
database: db/test.sqlite3
pool: 5
timeout: 5000
Exemplos de configuração do database.yml para diversos SGBD’s podem ser facilmente encontrados na web.
Esse arquivo (com informações consistentes sobre o SGBD disponível na máquina -- e.g.: nome de usuário e senha para conexão, que são desnecessários no caso do SQLite mas necessários em outros casos) é tudo o que precisamos para criar o banco:
embs@duff ~/Code/bdance (master) $ rake db:create
O comando acima cria a base de dados especificada em development no database.yml. Para criar as tabelas (especificadas através das migrations do Rails), deve-se executar:
embs@duff ~/Code/bdance (master) $ rake db:migrate
Novamente, o comando acima criará as tabelas no banco de desenvolvimento. Para configurar o banco de testes, utiliza-se um comando adicional:
embs@duff ~/Code/bdance (master) $ rake db:test:prepare
Mais informações sobre a execução de comandos para manipulação da base de dados utilizando o Rake podem ser encontradas nesta seção do guia do Rails para migrações.
O código do BDance, atualmente, ainda não dá suporte à configuração da autenticação com o Facebook para diferentes ambientes (desenvolvimento / produção / testes). As opções de aplicação do Facebook estão no próprio código, no arquivo de configuração do Devise:
config.omniauth :facebook, '461039767351601', '6ab439211430afff27f79e1777d3a876', :strategy_class => OmniAuth::Strategies::Facebook
Essa não é, claramente, uma boa abordagem para a configuração da aplicação e irá mudar em breve para utilizar os arquivos que o Rails distingue para configuração de diferentes ambientes.
Para permitir que usuários se cadastrem / loguem na sua instância do BDance através do Facebook, você deve visitar a página de cadastro de aplicações do Facebook, https://developers.facebook.com/, e criar uma nova aplicação. Depois disso, utilize as informações de app_key e secret_key da nova aplicação para configuração do omniauth (como supracitado).
O primeiro passo para criar um pull request, assumindo que você já clonou o repositório principal do BDance, é fazer um fork do projeto. Criar um fork é fácil (consulte este guia do Github se precisar de ajuda) e o resultado é um repositório remoto no domínio do Github (ex.: http://github.com/seuLogin/bdance) igual ao repositório principal do BDance mas com uma diferença crucial: você pode mandar suas modificações pra ele.
Neste ponto, assume-se que você acabou de clonar o repositório principal do BDance e está, na linha de comando com acesso ao git, navegando no diretório raiz do projeto Rails. Sua linha de comando se parece, então, com o seguinte:
embs@duff ~/Code/bdance (master) $
e, se executar git remote -v para listar os locais remotos, deve visualizar
embs@duff ~/Code/bdance (master) $ git remote -v
origin https://github.com/embs/bdance.git (fetch)
origin https://github.com/embs/bdance.git (push)
Essas duas entradas origin são referentes ao repositório principal do BDance. Para adicionar o seu repositório remoto (que foi criado através do fork no Github), você deve fazer o seguinte:
embs@duff ~/Code/bdance (master) $ git remote add meuRemoto https://github.com/meuLogin/bdance
em que meuRemoto é um nome arbitrário, escolhido por você, para rotular o local remoto. Não se esqueça de substituir meuLogin com o seu login do Github. Agora, se você executar git remote -v novamente, deve visulizar algo assim:
embs@duff ~/Code/bdance (master) $ git remote -v
meuRemoto https://github.com/meuLogin/bdance (fetch)
meuRemoto https://github.com/meuLogin/bdance (push)
origin https://github.com/embs/bdance.git (fetch)
origin https://github.com/embs/bdance.git (push)
Isso indica que os locais remotos agora dispõem dos dois endereços (para o repositório principal do BDance e para o seu fork).
Depois de configurar devidamente o remote do seu fork, você deve criar uma branch para suas modificações -- o que é tão fácil quanto executar um comando na linha de comando:
embs@duff ~/Code/bdance (master) $ git checkout -b minha-feature
Switched to a new branch 'minha-feature'
embs@duff ~/Code/bdance (minha-feature) $
O comando git checkout -b minha-feature é um atalho para outros dois comandos do git: git branch minha-feature e git checkout minha-feature, em que o primeiro cria uma nova branch chamada minha-feature e o segundo muda o seu ambiente de trabalho para a branch recém-criada. Vale notar que, como o comando foi executado quando se estava no branch master, a nova branch é igual à branch master.
Hora de colocar a mão na massa! Modifique o código (lembre de testar tudo o que fizer com o RSpec!), crie commits e faça o push para o seu repositório no Github:
embs@duff ~/Code/bdance (minha-feature) $ git push meuRemoto minha-feature
Se tiver alguma dúvida sobre como utilizar efetivamente o git, consulte esta lista de referências do Github.
Uma vez que suas modificações estiverem no seu repositório remoto, um ícone para criação do pull request irá aparecer quando você visitar a página do seu reposiório no Github. Para criar o pull request basta, então, clicar no botão. O Github disponibiliza um passo-a-passo mais detalhado sobre esse processo.
A prática de criação de pull requests utilizada pelo BDance é comum a vários outros projetos de código aberto e devidamente documentada pelo Github no seu guia de colaboração.
Criar issues no Github é muito fácil e a interface web para realizar essa tarefa é bastante intuitiva. Este anexo tem o intuito de especificar alguns detalhes sobre a criação de issues para problemas referente ao código (issues criados por desenvolvedores).
Com base na abordagem TDD, você deve, ao criar um issue relacionado com um problema no código, criar um teste (do RSpec) que falhe devido ao problema. No corpo do issue, então, você pode referenciar o código do teste (copiando e colando ou linkando com código do seu fork do BDance).