Configuração do ambiente de desenvolvimento

Este guia orientará você na configuração de um ambiente de desenvolvimento local para omegaUp usando Docker.

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte instalado:

• Docker Engine: Instalar Docker
• Docker Compose 2: Instalar Docker Compose
• Git: Para clonar o repositório

Configuração específica do Linux

Se você estiver executando o Linux, após instalar o Docker, adicione seu usuário ao grupo docker:

sudo usermod -a -G docker $USER

Etapa 1: bifurcar e clonar o repositório

1. Fork do repositório: Visite github.com/omegaup/omegaup e clique no botão "Fork"

2. Clone seu garfo:

   git clone --recurse-submodules https://github.com/YOURUSERNAME/omegaup
   cd omegaup
   

3. Inicializar submódulos (se necessário):

   git submodule update --init --recursive
   

Etapa 2: iniciar contêineres Docker

Configuração pela primeira vez

Na primeira execução, extraia as imagens do Docker e inicie os contêineres:

docker-compose pull
docker-compose up --no-build

frontend_1     | Child frontend:
frontend_1     |        1550 modules
frontend_1     |     Child HtmlWebpackCompiler:
frontend_1     |            1 module
...

Execuções subsequentes

Após a primeira execução, você pode iniciar contêineres mais rapidamente com:

docker compose up --no-build

Etapa 3: acesse sua instância local

Assim que os contêineres estiverem em execução, acesse sua instância local do omegaUp em:

http://localhost:8001

Etapa 4: acessar o console do contêiner

Para executar comandos dentro do contêiner:

docker exec -it omegaup-frontend-1 /bin/bash

Contas de Desenvolvimento

Sua instalação local inclui contas pré-configuradas:

Conta de administrador

• Nome de usuário: omegaup
• Senha: omegaup
• Função: Administrador (privilégios de administrador de sistema)

Conta de usuário normal

• Nome de usuário: user
• Senha: user
• Função: usuário regular

Contas de teste

Para fins de teste, você pode usar estas contas de teste:

Executando testes localmente

Se você deseja executar testes JavaScript/TypeScript fora do Docker:

Pré-requisitos

1. Node.js: versão 16 ou superior
2. Yarn: Gerenciador de pacotes

Etapas de configuração

1. Inicializar submódulos Git:

   git submodule update --init --recursive
   

   Isso baixa as dependências necessárias:
2. pagedown - Editor de redução
3. iso-3166-2.js - Códigos de país/região
4. csv.js - análise CSV

5. mathjax - Renderização matemática

6. Instalar dependências:

   yarn install
   

7. Executar testes:

   yarn test
   

Início rápido (novo clone)

Para um novo clone, use este único comando:

git clone --recurse-submodules https://github.com/YOURUSERNAME/omegaup
cd omegaup
yarn install
yarn test

Estrutura da base de código

A base de código omegaUp é organizada da seguinte forma:

omegaup/
├── frontend/
│   ├── server/
│   │   └── src/
│   │       ├── Controllers/    # Business logic & API endpoints
│   │       ├── DAO/            # Data Access Objects
│   │       └── libs/           # Libraries & utilities
│   ├── www/                    # Frontend assets (TypeScript, Vue.js)
│   ├── templates/              # Smarty templates & i18n files
│   ├── database/               # Database migrations
│   └── tests/                  # Test files

O fluxo de contribuição (branches, PRs, remotos) está em Contribuindo.

Visual Studio Code com Docker

Você pode editar no host com Visual Studio Code enquanto o Docker executa o stack.

Extensões recomendadas

• Dev Containers ou Docker para anexar a um contêiner em execução
• Extensões PHP, Vue e ESLint conforme necessário

Anexar ao contêiner frontend

1. Inicie o ambiente: docker compose up --no-build (ou docker compose up na primeira vez).
2. No VS Code, use Attach to Running Container e escolha o contêiner do frontend (muitas vezes omegaup-frontend-1; veja docker compose ps).
3. Na janela anexada, abra a pasta /opt/omegaup.

Você também pode editar o clone no host: o mesmo diretório é montado em /opt/omegaup.

GitHub OAuth (login local com GitHub)

1. Criar o OAuth App no GitHub

1. Abra GitHub Developer Settings.
2. OAuth Apps → New OAuth App.
3. Defina Homepage URL http://localhost:8001/ e Authorization callback URL http://localhost:8001/login?third_party_login=github.
4. Registre e copie Client ID e Client Secret.

2. Configurar o omegaUp

Crie ou edite frontend/server/config.php:

<?php
define('OMEGAUP_GITHUB_CLIENT_ID', 'your_real_client_id_here');
define('OMEGAUP_GITHUB_CLIENT_SECRET', 'your_real_client_secret_here');

Consulte também Segurança → OAuth.

Problemas comuns

O aplicativo da web não está mostrando minhas alterações

Certifique-se de que o Docker esteja em execução:

docker compose up --no-build

Navegador redireciona HTTP para HTTPS

Se o seu navegador continuar mudando http para https para localhost, você poderá desabilitar as políticas de segurança para localhost. Veja este guia.

Erro MySQL não encontrado

Se você encontrar esse erro ao enviar para o GitHub:

FileNotFoundError: [Errno 2] No such file or directory: '/usr/bin/mysql'

sudo apt-get install mysql-client mysql-server

cat > ~/.mysql.docker.cnf <<EOF
[client]
port=13306
host=127.0.0.1
protocol=tcp
user=root
password=omegaup
EOF
ln -sf ~/.mysql.docker.cnf .my.cnf

Erro de conexão MySQL

Se o MySQL estiver instalado, mas aparecer erro de socket, os hooks em git push esperam cliente TCP na porta 13306. Use ~/.mysql.docker.cnf e o link .my.cnf como em Contribuindo.

Submódulos Git

git submodule update --init --recursive

Reconstruir imagem frontend

docker compose build frontend
docker compose up

Permissões: phpminiadmin, venv ou loop de reinício

Causa: clone ou docker compose como root.

Solução: clone de novo como usuário normal, grupo docker, sem sudo em git clone nem em docker compose.

policy-tool / mysql ao fazer push

Instale o cliente MySQL no host e configure TCP como acima. Ambiente de deploy: omegaup/deploy/issues.

Próximas etapas

• Aprenda como contribuir - Crie ramificações e envie solicitações pull
• Revise as diretrizes de codificação - Entenda nossos padrões de codificação
• Explore a arquitetura - Entenda como o omegaUp funciona

Obtendo ajuda

Se você encontrar problemas não abordados aqui:

1. Verifique o Guia de ajuda
2. Pesquise issues existentes no GitHub
3. Pergunte em nosso servidor Discord

Pronto para começar a codificar? Acesse o Guia de contribuição para saber como enviar sua primeira solicitação pull!