Code Sphere

O problema e as restrições

Uma sala de aula de até 60 alunos precisava da mesma coisa que cada um deles um dia vai querer num emprego de verdade: um VS Code de verdade, rodando Python de verdade, com um terminal de verdade, em vez de uma sandbox de ensino simplificada que precisaria ser desaprendida depois. O hardware disponível para rodar tudo isso era um único servidor dimensionado para mais ou menos metade dessa quantidade de pessoas ao mesmo tempo, porque na prática uma escola roda duas turmas de uns 30 alunos por vez, bem longe dos sessenta martelando a mesma máquina no mesmo instante.

Esse único fato (trinta de verdade, trinta em teoria) virou a restrição que moldou quase tudo o resto. Um container de code-server não é de graça nem parado: processo de extensão em background, observador de arquivo, servidor de linguagem custam de 400 a 700 MB de memória só existindo. Multiplique isso por sessenta e um servidor de 16 GB estoura o orçamento em três a quatro vezes antes de qualquer aluno escrever uma linha de código. A plataforma não podia assumir que os sessenta estavam ativos; precisava arranjar ativamente para que a maioria não estivesse, na maior parte do tempo, sem exigir que um professor gerenciasse isso na mão para cada aula.

A segunda restrição era a rede atrás da qual os alunos de fato estão. Wi-Fi escolar e Chromebook fornecido pela escola são notórios por bloquear qualquer coisa que não seja tráfego web padrão, porta não convencional principalmente. Fosse o que saísse do navegador de um aluno, tinha que parecer tráfego HTTPS comum na porta 443, indistinguível de qualquer outro site, sem número de porta para lembrar ou digitar.

A terceira restrição era quem opera isso no dia a dia: um professor só, sem departamento de TI por trás. A configuração inteira (gerar configuração, construir imagem, subir a stack) precisava colapsar num punhado pequeno de scripts que um não especialista conseguisse rodar uma vez, mais um botão de “pré-aquecer uma turma” para a única esquisitice operacional (30 a 45 segundos de partida fria) que containers sob demanda introduzem. Não existe plantão por trás dessa plataforma; o que quebrar, quebra na frente de uma sala de aula, em tempo real.

A quarta restrição chegou depois que a plataforma já existia e já funcionava para programação em texto simples: o pedido de também ensinar Pygame Zero, jogo visual e interativo de verdade. Isso é um formato de recurso completamente diferente: um jogo rodando precisa de uma tela para desenhar e, eventualmente, som para tocar, dentro do mesmo teto de memória e CPU por aluno que já era apertado antes de qualquer coisa desenhar um quadro ou misturar um buffer de áudio. Todo byte gasto tornando um jogo visível ou audível era um byte que deixava de estar disponível para a própria coisa que a plataforma existe para ensinar.

A última restrição era uma realidade específica e nada glamorosa de onde isso de fato roda: alguns dos ambientes rodando ou desenvolvendo contra essa plataforma são máquinas Windows usando WSL2, que tem esquisitices reais e documentadas em como compartilha arquivo e diretório com container Linux, esquisitices que não aparecem num ambiente de CI Linux limpo, mas aparecem sem dúvida na frente de uma turma de verdade.

Arquitetura

O navegador de um aluno fala com exatamente uma coisa na rede: o Traefik, escutando numa porta única. Toda rota que o Traefik conhece (o portal de login, e uma vaga por aluno, de /code/aluno01/ a /code/aluno60/) é escrita num único arquivo de configuração antes de qualquer container sequer iniciar, gerado uma vez na configuração em vez de descoberto em tempo de execução. Essa abordagem estática existe porque a alternativa mais “moderna” (deixar cada container anunciar a própria rota ao Traefik conforme inicia) parou de funcionar em silêncio: a integração do Traefik com o Docker fala com a API numa versão fixa e desatualizada, e o Docker Engine atual recusa conexões abaixo da versão mínima suportada. Pré-declarar toda rota contorna a incompatibilidade por completo e nem exige que o Traefik toque no socket do Docker.

Atrás desse proxy fica um portal pequeno em Flask, que é a única coisa com autoridade para iniciar ou parar o container de um aluno. Quando um aluno faz login, o portal confere a senha contra um hash Argon2id, inicia o container específico dele se ainda não estiver rodando, e espera (checando repetidamente a própria porta HTTP do container, em vez de simplesmente dormir um número fixo de segundos) até o code-server lá dentro estar de fato pronto para responder. Uma thread em background no mesmo portal percorre a lista de containers rodando de tempos em tempos e para qualquer um que tenha ficado quieto, devolvendo a memória para o próximo aluno que fizer login. Todo container que o portal cria começa completamente do zero em vez de retomar um parado: reiniciar do zero toda vez é o que garante que um token de acesso novo nunca colida com um token de uma sessão anterior.

Depois que o ambiente de um aluno está rodando, ele oferece mais que um terminal. Uma tela de monitor, construída sobre noVNC, mostra o que quer que o jogo em Pygame Zero do aluno esteja de fato desenhando: necessário no momento em que “programar” passa a significar “programar algo que se pode ver mexer na tela”. O áudio veio depois e teve que brigar pelo mesmo orçamento de recurso minúsculo que o caminho de vídeo já estava gastando: o PulseAudio dentro do container publica um sink virtual, um segundo processo websockify (a mesma ferramenta que já fazia a ponte do vídeo, então nenhuma dependência nova) carrega esse áudio bruto até o navegador pelo próprio WebSocket, e um script pequeno decodifica com a Web Audio API. Os dois canais, vídeo e áudio, rodam lado a lado pelo mesmo proxy, no mesmo limite de cgroup por aluno, dividindo um orçamento que já estava contabilizado antes de qualquer um dos dois precisar fazer barulho.