README.md

GP-Whiskey

Status:

Pre-requisitos

• Python 3.10.8 (Usamos o 3.10 porque para algumas packages ainda não existem updates)
• PostgreSQL 15
• Git (Useful to use VSC outside github desktop)

Instalação

ESTIMATED TIME FOR SETUP -> 1-2 hours

É estritamente necessário ter os pre-requisitos instalados nas versoes mencionadas. Se nao desejar instalar postgres, pode-se usar uma base de dados remota, disponibilizada por mim. Pff pedir detalhes da DB.

1. Abrir o terminal ou o github desktop.
2. Clonar o projeto.

Se usarem terminal:

git clone https://github.com/6135/GP-Whiskey

3. Entrar na pasta do projeto.
4. Abrir o terminal na pasta.
5. Criar o ambiente (virtual) do projeto.

Atenção: A versão de Python com a qual criar o ambiente do projeto deve ser igual para todos (v3.10.8). Para verificar a versao deve-se usar:

py -V

Para criar o ambiente: Atenção: Existe a possibilidade de que o comando para linux seja ligeiramente diferente.

py -m venv env

Isto deve criar uma pasta env na diretoria do projeto, esta pasta NAO DEVE ser seguida pelo github, é individual para cada maquina em que seja desenvolvido o projeto.

6. Ativar o ambiente no terminal.

Em linux:

source env/bin/activate

Em Windows:

env\Scripts\activate

A extensão padrão de Python do VSCode tem a opção de ativar automaticamente o ambiente em novos terminais. Para ativar a funcionalidade, há que abrir a Palete de Comandos (F1), Python: Selecionar Interpretador e escolher a opção cuja localização comece com ./env ou .\env.

7. Atualizar as dependencias iniciais do ambiente e do projeto

py -m pip install --upgrade pip
pip install --upgrade pip setuptools

seguido de:

pip install -r requirements.txt

8. Criar um ficheiro .env dentro da pasta do projeto, a mesma pasta que contem o ficheiro settings.py, este ficheiro contem informações sensiveis ao projeto, como credenciais de acesso. Nao deve ser partilhado no git.

Um exemplo do conteudo do ficheir env seria:

USE_REMOTE_DB=false

LOCAL_DATABASE_HOST=localhost
LOCAL_DATABASE_NAME=gp_whiskey
LOCAL_DATABASE_USER=postgres
LOCAL_DATABASE_PASSWORD=postgres

REMOTE_DATABASE_PROD_NAME=gp_whiskey_prod
REMOTE_DATABASE_NAME=gp_whiskey
REMOTE_DATABASE_HOST=server
REMOTE_DATABASE_PASSWORD=pwd
REMOTE_DATABASE_USER=postgres


DATABASE_PORT=5432

SECRET_KEY=q1^j3mv#y9-n&^*j)-rd3@lqqu@jv49p_99$mefzljeuz#fra3
[email protected]
EMAIL_HOST_PASSWORD=password

USE_REMOTE_DB=false usado para indicar se pretende usar a db remota ou a local.

9. Gerar uma nova SECRET_KEY aleatória (https://djecrety.ir/) e substituí-la no .env
10. Gerar uma nova BD vazia com o nome igual ao definido no ficheiro .env (Este passo pode ser ignorado caso se use a DB remota)
11. Navegar para a pasta GP-WHISKEY\gp_whiskey\ e gerar as migrações

Este comando gera as alterações efetuadas aos modelos (Classes do ORM do django) e aplica-as na base de dados. Por exemplo, se criarmos a classe User, o django cria a tabela users caso ela nao exista, se existir nao o faz. No caso de adicionarmos uma propriedade a classe, ele adiciona uma coluna a tabela. Ver a documentação

(manage.py encontra-se na pasta referida no ponto 11)

py manage.py makemigrations

12. Gerar a base de dados

py manage.py migrate

13. Testar se a setup funcionou

py manage.py runserver

Comandos fundamentais

Desativar o ambiente virtual no terminal

deactivate

Iniciar o servidor localmente

Perminte desenvolver sem necessitar deployment.

python manage.py runserver

Gerar migrações automaticamente através dos modelos

python manage.py makemigrations

Aplicar as migrações à base de dados

python manage.py migrate

A base de dados deve ter as seguintes tabelas apos as migrações iniciais:

Instalar nova dependência

pip install nome_da_dependência && pip freeze > requirements.txt

Instalar lista de dependências necessárias

pip install -r requirements.txt

Criar nova app (cada "componente" vai ser uma "app", neste caso ja existe uma, discutir com equipa caso seja necessaria outra)

python manage.py startapp nome_da_app

Gerar automaticamente modelos através de tabelas da base de dados

Nao utilizar por favor...

python manage.py inspectdb tabela1 tabela2 > nome_da_app/models.py

Dependências

---

TODO

TroubleShooting

Windows 10/11

Em windows, podem existir problemas de segurança ao executar o ambiente, para isso devem desativar a verificação da seguinte forma:

Set-ExecutionPolicy Unrestricted -Force
env\Scripts\activate.PS1

Em windows, podem ocorrer erros a quando da instalação das packages.

Encountered error while trying to install package.
╰─> psycopg2

Se este erro for emitido, instala as build tools do c++

Em caso de duvida, a arvore de diretorias deve ser semelhante a esta:

E:\GP-WHISKEY
│   .gitattributes
│   .gitignore
│   gp_tree.txt
│   README.md
│   requirements.txt
├───env
└───gp_whiskey
    │   manage.py
    │   
    ├───etar
    │   │   admin.py
    │   │   apps.py
    │   │   models.py
    │   │   tests.py
    │   │   views.py
    │   │   __init__.py
    │   │   
    │   └───migrations
    │           __init__.py
    │         
    └───gp_whiskey
        │   .env
        │   .env-example
        │   asgi.py
        │   settings.py
        │   urls.py
        │   wsgi.py
        │   __init__.py
        │   
        └───__pycache__
                settings.cpython-310.pyc
                settings.cpython-311.pyc
                urls.cpython-310.pyc
                urls.cpython-311.pyc
                wsgi.cpython-310.pyc
                __init__.cpython-310.pyc
                __init__.cpython-311.pyc
              

Ubuntu 22.04

1. Ao criar o ambiente virtual de python com o comando python -m venv env é possível obter o seguinte erro:

   

   Para corrigir este erro, temos de instalar o package python3.10-venv com o package manager:

   $ sudo apt install python3.10-venv

2. Durante a instalação das dependências para o ambiente virtual e para o projeto, com o comando pip install -r requirements.txt, pode não ser possível instalar o package psycopg2:

   

   Para o solucionar temos de instalar o package libpq-dev:

   $ sudo apt-get install libpq-dev

   E voltar a correr o comando necessário para instalar a lista de dependências do projeto:

   $ pip install -r requirements.txt

3. Se não for possível instalar a package libpq-dev:

   

   Temos de instalar a versão indicada na mensagem de erro, 14.5-0ubuntu0.22.04.1, do package libpq5:

   $ sudo apt install libpq5=14.5-0ubuntu0.22.04.1

   Por fim, instalamos o package libpq-dev e voltamos a instalar a lista de dependências do projeto:

   $ sudo apt-get install libpq-dev
   $ pip install -r requirements.txt

4. Ao gerar as migrações automaticamente através do comando python manage.py makemigrations, podemos obter a seguinte mensagem de erro:

   

   Este erro surge porque a password do utilizador postgres não corresponde à password definida no campo LOCAL_DATABASE_PASSWORD do ficheiro .env.

   Para alterarmos a password do superuser postgres através da CLI, temos de fazer login com o utilizador postgres:

   $ sudo -u postgres psql

   E alterar a sua password com o comando ALTER USER:

   postgres=# ALTER USER postgres WITH PASSWORD 'postgres';

5. Comandos para criar a base de dados através da CLI:

   • Login como superuser postgres:

     $ sudo -u postgres psql

   • Criar base de dados:

     postgres=# CREATE DATABASE gp_whiskey;

   • Listar bases de dados, para verificar se a base de dados foi criada

     postgres=# \l

   • Logout:

     postgres=# \q
     

Reference Guide

1. Django Installation Guide - Official
2. Microsoft C++ Build Tools
3. PostegreSQL with django
4. Django how to use env vars or here

ps: took me 3h.20m to set up.