Manual de Instalação e Configuração

Documento: Manual de Instalação e Configuração Sistema: Módulo Empreendedorismo Versão: 1.0 Data: Janeiro/2025

---

1. Introdução

1.1. Objetivo

Este manual tem como objetivo fornecer instruções detalhadas para a instalação, configuração e implantação do sistema Módulo Empreendedorismo em ambientes de desenvolvimento, homologação e produção.

1.2. Escopo

Este documento abrange:

• Requisitos de hardware e software
• Procedimentos de instalação
• Configuração de todos os componentes do sistema
• Validação da instalação
• Procedimentos de atualização

1.3. Público-Alvo

• Administradores de sistemas
• Equipe de DevOps
• Desenvolvedores

1.4. Documentos Relacionados

Documento	Descrição
Manual de Configuração	Detalhamento de variáveis de ambiente
Plano de Contingência	Procedimentos de recuperação
Documentação Técnica	Arquitetura e especificações

---

2. Requisitos

2.1. Requisitos de Hardware

2.1.1. Ambiente de Desenvolvimento

Recurso	Mínimo	Recomendado
Processador	2 cores	4 cores
Memória RAM	4 GB	8 GB
Armazenamento	20 GB SSD	50 GB SSD
Rede	10 Mbps	100 Mbps

2.1.2. Ambiente de Homologação

Recurso	Mínimo	Recomendado
Processador	4 cores	8 cores
Memória RAM	8 GB	16 GB
Armazenamento	50 GB SSD	100 GB SSD
Rede	100 Mbps	1 Gbps

2.1.3. Ambiente de Produção

Recurso	Mínimo	Recomendado
Processador	8 cores	16 cores
Memória RAM	16 GB	32 GB
Armazenamento	100 GB SSD	500 GB SSD
Rede	1 Gbps	10 Gbps
Backup	Storage externo	Storage redundante

2.2. Requisitos de Software

2.2.1. Sistema Operacional

Sistema	Versão	Suporte
Ubuntu Server	22.04 LTS ou superior	Recomendado
Debian	12 ou superior	Suportado
Windows Server	2022	Suportado
macOS	13+	Apenas desenvolvimento

2.2.2. Software Obrigatório

Software	Versão	Finalidade
Docker	24.0+	Containerização
Docker Compose	2.0+	Orquestração de containers
Git	2.40+	Controle de versão

2.2.3. Software Opcional

Software	Versão	Finalidade
Node.js	20.0+	Desenvolvimento frontend/docs
Python	3.11+	Desenvolvimento backend local
Nginx	1.24+	Proxy reverso (produção)

2.3. Requisitos de Rede

2.3.1. Portas Utilizadas

Porta	Serviço	Protocolo	Exposição
80	HTTP (Nginx)	TCP	Externa
443	HTTPS (Nginx)	TCP	Externa
5432	PostgreSQL	TCP	Interna
6379	Redis	TCP	Interna
8000	Backend Django	TCP	Interna
9000	MinIO API	TCP	Interna
9001	MinIO Console	TCP	Interna/Admin
9501	Frontend	TCP	Interna

2.3.2. Conectividade Externa

Serviço	Destino	Porta	Finalidade
SMTP	Servidor de email	587/465	Envio de emails
DNS	Servidor DNS	53	Resolução de nomes
NTP	Servidor NTP	123	Sincronização de horário

---

3. Procedimento de Instalação

3.1. Preparação do Ambiente

3.1.1. Atualização do Sistema Operacional

# Ubuntu/Debian
sudo apt update && sudo apt upgrade -y

# Instalar dependências básicas
sudo apt install -y curl wget git apt-transport-https ca-certificates gnupg lsb-release

3.1.2. Instalação do Docker

# Adicionar repositório oficial do Docker
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Instalar Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Adicionar usuário ao grupo docker
sudo usermod -aG docker $USER

# Verificar instalação
docker --version
docker compose version

3.1.3. Configuração de Firewall

# UFW (Ubuntu)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

# Verificar status
sudo ufw status

3.2. Instalação do Sistema

3.2.1. Obtenção do Código-Fonte

# Criar diretório de aplicação
sudo mkdir -p /opt/modulo-empreendedorismo
sudo chown $USER:$USER /opt/modulo-empreendedorismo

# Clonar repositório
cd /opt
git clone https://github.com/Tav-Web/modulo-empreendedorismo.git
cd modulo-empreendedorismo

3.2.2. Configuração do Docker Compose

# Copiar arquivo de exemplo
cp docker-compose.example.yml docker-compose.yml

# Editar configurações
nano docker-compose.yml

3.2.3. Geração de Credenciais Seguras

# Gerar SECRET_KEY do Django
python3 -c "import secrets; print(secrets.token_urlsafe(50))"

# Gerar senha para PostgreSQL
openssl rand -base64 32

# Gerar senha para MinIO
openssl rand -base64 32

3.2.4. Configuração das Variáveis de Ambiente

Edite o arquivo docker-compose.yml e configure as seguintes variáveis:

Banco de Dados (PostgreSQL)

db:
  environment:
    POSTGRES_DB: empreendedorismo
    POSTGRES_USER: postgres
    POSTGRES_PASSWORD: <SENHA_GERADA>

Backend (Django)

backend:
  environment:
    SECRET_KEY: <SECRET_KEY_GERADA>
    DEBUG: "False"
    ALLOWED_HOSTS: "seu-dominio.com,localhost"
    DB_HOST: db
    DB_NAME: empreendedorismo
    DB_USER: postgres
    DB_PASSWORD: <MESMA_SENHA_DO_DB>

MinIO (Armazenamento)

minio:
  environment:
    MINIO_ROOT_USER: admin
    MINIO_ROOT_PASSWORD: <SENHA_MINIO>

Email (SMTP)

backend:
  environment:
    SMTP_HOST: smtp.seuservidor.com
    SMTP_PORT: "587"
    SMTP_USER: email@dominio.com
    SMTP_PASSWORD: <SENHA_EMAIL>
    DEFAULT_FROM_EMAIL: noreply@dominio.com

3.3. Inicialização do Sistema

3.3.1. Construção das Imagens

# Construir todas as imagens
docker compose build --no-cache

# Verificar imagens criadas
docker images | grep modulo

3.3.2. Inicialização dos Containers

# Iniciar todos os serviços
docker compose up -d

# Verificar status dos containers
docker compose ps

# Verificar logs de inicialização
docker compose logs -f

3.3.3. Execução das Migrations

# Aguardar banco de dados inicializar (30 segundos)
sleep 30

# Executar migrations
docker compose exec backend python manage.py migrate

# Verificar migrations aplicadas
docker compose exec backend python manage.py showmigrations

3.3.4. Configuração do MinIO

# Configurar buckets e políticas
docker compose exec backend python manage.py setup_minio

3.3.5. Criação do Superusuário

# Criar administrador do sistema
docker compose exec backend python manage.py createsuperuser

# Informar:
# - Email
# - Senha (mínimo 8 caracteres)

3.3.6. Coleta de Arquivos Estáticos

# Coletar arquivos estáticos
docker compose exec backend python manage.py collectstatic --noinput

---

4. Configuração de Produção

4.1. Configuração do Nginx

4.1.1. Instalação do Nginx

sudo apt install -y nginx
sudo systemctl enable nginx

4.1.2. Configuração do Virtual Host

Crie o arquivo /etc/nginx/sites-available/modulo-empreendedorismo:

upstream backend {
    server 127.0.0.1:8000;
}

upstream frontend {
    server 127.0.0.1:9501;
}

upstream minio {
    server 127.0.0.1:9000;
}

server {
    listen 80;
    server_name seu-dominio.com www.seu-dominio.com;

    # Redirecionar para HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name seu-dominio.com www.seu-dominio.com;

    # Certificados SSL
    ssl_certificate /etc/letsencrypt/live/seu-dominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/seu-dominio.com/privkey.pem;

    # Configurações SSL
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # Headers de segurança
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # Logs
    access_log /var/log/nginx/modulo-empreendedorismo.access.log;
    error_log /var/log/nginx/modulo-empreendedorismo.error.log;

    # Tamanho máximo de upload
    client_max_body_size 100M;

    # Frontend
    location / {
        proxy_pass http://frontend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }

    # API Backend
    location /api {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
    }

    # Arquivos estáticos do Django
    location /static {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # MinIO - Arquivos
    location /files {
        proxy_pass http://minio;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Documentação da API
    location /api/docs {
        proxy_pass http://backend;
        proxy_set_header Host $host;
    }
}

4.1.3. Ativação do Site

# Criar link simbólico
sudo ln -s /etc/nginx/sites-available/modulo-empreendedorismo /etc/nginx/sites-enabled/

# Testar configuração
sudo nginx -t

# Reiniciar Nginx
sudo systemctl restart nginx

4.2. Configuração de SSL/TLS

4.2.1. Instalação do Certbot

sudo apt install -y certbot python3-certbot-nginx

4.2.2. Obtenção do Certificado

sudo certbot --nginx -d seu-dominio.com -d www.seu-dominio.com

4.2.3. Renovação Automática

# Testar renovação
sudo certbot renew --dry-run

# Adicionar ao crontab (já configurado automaticamente pelo certbot)
sudo systemctl status certbot.timer

4.3. Configuração de Serviço Systemd

Crie o arquivo /etc/systemd/system/modulo-empreendedorismo.service:

[Unit]
Description=Módulo Empreendedorismo
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/modulo-empreendedorismo
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

# Ativar serviço
sudo systemctl daemon-reload
sudo systemctl enable modulo-empreendedorismo

---

5. Validação da Instalação

5.1. Checklist de Verificação

Execute os seguintes comandos para validar a instalação:

# 1. Verificar containers
docker compose ps

# Saída esperada: todos os serviços com status "Up"

# 2. Testar conectividade do banco de dados
docker compose exec backend python -c "
import django
django.setup()
from django.db import connection
cursor = connection.cursor()
cursor.execute('SELECT version()')
print('PostgreSQL:', cursor.fetchone()[0])
"

# 3. Testar Redis
docker compose exec backend python -c "
import redis
r = redis.Redis(host='redis', port=6379)
print('Redis PING:', r.ping())
"

# 4. Testar MinIO
docker compose exec backend python manage.py setup_minio

# 5. Testar API
curl -I http://localhost:8000/api/docs/
# Esperado: HTTP 200 OK

# 6. Testar Frontend
curl -I http://localhost:9501/
# Esperado: HTTP 200 OK

5.2. Testes Funcionais

Teste	Procedimento	Resultado Esperado
Login Admin	Acessar /admin com superusuário	Acesso concedido
API Docs	Acessar /api/docs	Swagger UI carrega
Frontend	Acessar página inicial	Interface carrega
Upload	Enviar arquivo no sistema	Arquivo salvo no MinIO
Email	Cadastrar usuário	Email de confirmação enviado

---

6. Procedimentos de Atualização

6.1. Atualização Padrão

# 1. Backup do banco de dados
docker compose exec db pg_dump -U postgres empreendedorismo > backup_$(date +%Y%m%d_%H%M%S).sql

# 2. Parar containers
docker compose down

# 3. Atualizar código
git fetch origin
git pull origin main

# 4. Reconstruir imagens
docker compose build --no-cache

# 5. Iniciar containers
docker compose up -d

# 6. Executar migrations
docker compose exec backend python manage.py migrate

# 7. Coletar arquivos estáticos
docker compose exec backend python manage.py collectstatic --noinput

# 8. Verificar funcionamento
docker compose ps
curl -I http://localhost:8000/api/docs/

6.2. Rollback

Em caso de falha:

# 1. Parar containers
docker compose down

# 2. Reverter código
git checkout <commit_anterior>

# 3. Restaurar banco (se necessário)
cat backup_YYYYMMDD_HHMMSS.sql | docker compose exec -T db psql -U postgres empreendedorismo

# 4. Reconstruir e iniciar
docker compose build
docker compose up -d

---

7. Troubleshooting

7.1. Problemas Comuns

Container não inicia

# Verificar logs
docker compose logs <nome-do-container>

# Verificar recursos do sistema
docker system df
df -h
free -m

Erro de conexão com banco de dados

1. Verificar se container PostgreSQL está rodando
2. Verificar credenciais em docker-compose.yml
3. Verificar logs do PostgreSQL:

docker compose logs db

Erro de permissão no MinIO

docker compose exec backend python manage.py setup_minio

Emails não são enviados

1. Verificar configurações SMTP
2. Verificar logs do Celery:

docker compose logs celery-worker-emails

7.2. Logs de Diagnóstico

# Todos os logs
docker compose logs

# Logs específicos com timestamp
docker compose logs -t --since="1h" backend

# Logs em tempo real
docker compose logs -f backend celery-worker

---

8. Anexos

8.1. Estrutura de Diretórios

/opt/modulo-empreendedorismo/
├── backend/
│   ├── apps/
│   ├── core/
│   ├── templates/
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/
│   ├── package.json
│   └── Dockerfile
├── docs/
│   ├── docs/
│   └── docusaurus.config.ts
├── docker-compose.yml
├── docker-compose.example.yml
└── README.md

8.2. Comandos de Referência Rápida

Ação	Comando
Iniciar sistema	docker compose up -d
Parar sistema	docker compose down
Ver logs	docker compose logs -f
Reiniciar serviço	docker compose restart <serviço>
Executar migrations	docker compose exec backend python manage.py migrate
Criar superusuário	docker compose exec backend python manage.py createsuperuser
Backup banco	docker compose exec db pg_dump -U postgres empreendedorismo > backup.sql
Shell Django	docker compose exec backend python manage.py shell
Shell PostgreSQL	docker compose exec db psql -U postgres empreendedorismo

---

Fim do Documento