MongoDB Compass direto no navegador.
Uma versão web do MongoDB Compass, containerizada e pronta para deploy, permitindo gerenciar seus bancos de dados MongoDB de qualquer lugar.
- 📸 Sobre o Projeto
- 🛠️ Tecnologias Utilizadas
- 💻 Pré-requisitos
- 🚀 Como Rodar o Projeto Localmente
- 🐳 Rodando com Docker (Método Recomendado)
- 🚀 Deploy em Produção
- ❓ FAQ & Solução de Problemas
- 📂 Estrutura do Projeto
- 🤝 Como Contribuir
- ⚖️ Licença
- 🤙 Créditos
O Compass Web é uma implementação containerizada do MongoDB Compass para acesso via navegador. Baseado no projeto compass-web de haohanyang, esta versão adiciona um wrapper Node.js personalizado e Dockerfile otimizado para facilitar o deploy em ambientes de produção.
- 🌐 Acesso via Navegador: Gerencie seus bancos MongoDB sem instalar nada localmente.
- 🔒 Autenticação Integrada: Sistema de login opcional para proteger o acesso.
- 🔍 Interface Completa: Todas as funcionalidades do MongoDB Compass original.
- 📊 Visualização de Dados: Explore coleções, documentos e índices com interface intuitiva.
- ⚡ Query Builder: Execute queries complexas com suporte a agregações.
- 🐳 Containerizado: Deploy simplificado com Docker.
- 🔐 Conexões Seguras: Suporte completo a SSL/TLS e autenticação MongoDB.
Este projeto foi desenvolvido utilizando as seguintes tecnologias:
- Base: compass-web by haohanyang
- Runtime: Node.js 20
- Wrapper: Script Node.js personalizado para gerenciamento de variáveis de ambiente
- Containerização: Docker
- Frontend: React (MongoDB Compass UI)
Antes de começar, certifique-se de ter instalado em sua máquina:
git clone https://github.com/seu-usuario/compass-web.git
cd compass-webCrie um arquivo .env na raiz do projeto com as seguintes variáveis:
# URI de Conexão com MongoDB (OBRIGATÓRIO)
CW_MONGO_URI=mongodb://usuario:senha@host:27017/database
# Autenticação de Acesso ao Compass Web (OPCIONAL, mas recomendado)
CW_BASIC_AUTH_USERNAME=admin
CW_BASIC_AUTH_PASSWORD=senha_segura_aquiCaution
O arquivo .env contém dados sensíveis como credenciais do MongoDB e senhas de acesso.
NUNCA faça commit ou exponha este arquivo publicamente. O .env já está listado no .gitignore para prevenir isso, mas sempre verifique antes de enviar suas alterações para o repositório.
docker build -t compass-web .docker run -d -p 8080:8080 --env-file .env --name compass-web compass-webAbra seu navegador e acesse: http://localhost:8080
Se você configurou autenticação, será solicitado usuário e senha definidos em CW_BASIC_AUTH_USERNAME e CW_BASIC_AUTH_PASSWORD.
O Compass Web está pré-configurado para ser implantado na Discloud.
Para hospedar na Discloud, você precisa criar um arquivo discloud.config na raiz do projeto:
- Acesse o Gerador de discloud.config da Discloud.
- Preencha os seguintes parâmetros:
- ID: Seu subdominio cadastrado na Discloud
- Type: Site
- Main: Dockerfile
- Name: Nome do seu app
- RAM: 512 (mínimo recomendado)
- VLAN: true (se conectar a banco MongoDB na Discloud)
- APT: tools
- Baixe o arquivo gerado e adicione à raiz do projeto.
Exemplo de discloud.config:
ID=compassweb
TYPE=site
MAIN=Dockerfile
NAME=Kallum Compass
RAM=512
VLAN=true
APT=toolsNo painel da Discloud, adicione as seguintes variáveis de ambiente:
| Variável | Descrição | Exemplo |
|---|---|---|
CW_MONGO_URI |
URI de conexão do MongoDB | mongodb://user:pass@mongo.vlan:27017/db |
CW_BASIC_AUTH_USERNAME |
Usuário de acesso ao Compass Web | admin |
CW_BASIC_AUTH_PASSWORD |
Senha de acesso ao Compass Web | SenhaSegura123! |
Important
Se você estiver usando uma instância MongoDB também hospedada na Discloud:
- Certifique-se de que VLAN está ativada em ambas as aplicações (MongoDB e Compass Web)
- Use
mongodbcomo hostname na URI de conexão - Exemplo:
mongodb://user:pass@mongodb:27017/database
Com o discloud.config criado e as variáveis configuradas:
- Acesse o painel da Discloud
- Faça upload do projeto compactado (ZIP)
- Aguarde o build e deploy automático
O Compass Web pode ser hospedado em qualquer plataforma que suporte Docker:
- Railway: Conecte o repositório GitHub e configure as variáveis de ambiente
- Render: Deploy automático via Dockerfile
- DigitalOcean App Platform: Suporte nativo a Docker
- AWS ECS/Fargate: Para ambientes corporativos
Este é um erro crítico que impede a aplicação de iniciar.
- Causa: A variável de ambiente
CW_MONGO_URInão foi configurada. - Solução: Verifique se o arquivo
.envexiste e contém a linhaCW_MONGO_URI=mongodb://...
Se o navegador não pedir usuário e senha:
- Solução: Certifique-se de que AMBAS as variáveis estão definidas:
CW_BASIC_AUTH_USERNAMECW_BASIC_AUTH_PASSWORD
- Se apenas uma estiver definida, o modo seguro não será ativado.
- Verifique a URI de conexão: O formato correto é
mongodb://usuario:senha@host:porta/database - Firewall: Certifique-se de que o MongoDB aceita conexões remotas
- VLAN (Discloud): Se ambos estiverem na Discloud, use
mongodbcomo hostname - Credenciais: Confirme que o usuário tem permissões no banco de dados
Execute docker logs compass-web para ver os erros. Os mais comuns são:
- Falta da variável
CW_MONGO_URI - Erro de sintaxe no arquivo
.env - Porta 8080 já em uso (altere a variável
PORT)
Isso significa que a aplicação está acessível sem autenticação.
- Para desenvolvimento local: Isso é aceitável
- Para produção: SEMPRE configure
CW_BASIC_AUTH_USERNAMEeCW_BASIC_AUTH_PASSWORD
- Verifique se já não foi reportado nas Issues
- Abra uma nova Issue com:
- Descrição detalhada do problema
- Logs do container (
docker logs compass-web) - Versão do Docker
- Sistema operacional
compass-web/
├── Dockerfile # Configuração da imagem Docker
├── start.js # Script wrapper para inicialização
├── .env # Variáveis de ambiente (NÃO COMITAR!)
├── .gitignore # Arquivos ignorados pelo Git
├── discloud.config # Configuração para deploy na Discloud
└── README.md # Este arquivo
Dockerfile: Define a imagem Docker baseada em Node.js 20, instala ocompass-webglobalmente e configura o ambiente.start.js: Script inteligente que:- Lê o arquivo
.envcom suporte a senhas complexas - Valida variáveis obrigatórias
- Inicia o
compass-webcom os parâmetros corretos - Gerencia logs e códigos de saída
- Lê o arquivo
Contribuições são sempre bem-vindas! Se você tem uma ideia de melhoria:
- Faça um Fork do projeto
- Crie uma Branch para sua feature (
git checkout -b feature/NovaFeature) - Faça o Commit das suas mudanças (
git commit -m 'Adiciona NovaFeature') - Faça o Push para a branch (
git push origin feature/NovaFeature) - Abra um Pull Request
Este projeto está licenciado sob a Apache License 2.0.
- ✅ Você pode: Usar comercialmente, modificar, distribuir e sublicenciar.
- ❌ Você NÃO pode: Usar o nome do autor ou marcas registradas para endossar produtos derivados sem permissão explícita.
- 🏷️ Obrigatório: Incluir uma cópia da licença e os avisos de copyright originais em qualquer redistribuição.
- 🛡️ Garantia: O software é fornecido "como está", sem garantias, e inclui uma cláusula de proteção de patentes para os usuários.
Note
O compass-web original possui sua própria licença, que deve ser respeitada ao usar a ferramenta base. Esta licença Apache 2.0 aplica-se especificamente ao Dockerfile e ao script start.js desenvolvidos para containerização.
Para ler a licença completa, consulte o arquivo LICENSE neste repositório.
Este projeto é uma implementação containerizada baseada no excelente trabalho de:
- haohanyang/compass-web - Implementação original do MongoDB Compass para web
- MongoDB Inc. - Desenvolvedores do MongoDB Compass original
O Dockerfile e script start.js foram desenvolvidos para facilitar o deploy em ambientes de produção com suporte a autenticação e configuração robusta via variáveis de ambiente.
Feito com 🧡 por Kallum
⭐ Se este projeto te ajudou, considere dar uma estrela!