theindex

Thendex

O painel do front -end, o editor e a API do TheIndex.

Começando

A maneira mais fácil é começar é usando o Docker Compose. Você precisa copiar o arquivo docker-compose.yml e example.env do GitHub. Renomeie example.env para .env e ajuste as variáveis ​​de ambiente conforme necessário. com o seguinte comando:

docker-compose up -d

Você precisará alterar <host-port> para a sua porta de escolha. O servidor da Web não está protegido via SSL/TLS, é por sua responsabilidade colocar um proxy reverso na frente deste contêiner. Quando você executa a imagem pela primeira vez, não se esqueça de definir seu próprio Discord-Id no Env SETUP_WHITELIST_DISCORD_ID para poder fazer login e editar. Depois que seu contêiner estiver configurado uma vez, você poderá remover a variável Env da sua configuração.

Banco de dados

Usamos o MongoDB como nosso servidor de banco de dados. Você pode implantar sua própria configuração de mongon como serviço HA ou apenas um recipiente simples do Docker Single via por exemplo:

NOTA: O banco de dados começará vazio, você mesmo deve preencher os dados.

docker run -d 
    --name mongo 
    -v ./db:/data/db 
    mongo

Para fins de desenvolvimento ou teste, é altamente recomendável usar o Mongo-Express para acessar, visualizar e editar o estado atual do banco de dados. Se você o tornar acessível publicamente, não se esqueça de protegê -lo com credenciais de login .

Para simplesmente girar um recipiente do Docker Mongo-Express, execute:

docker run -d 
    --name mongo-express 
    -p 8081:8081 
    mongo-express

Você também pode dar uma olhada no nosso arquivo docker-compose fornecido sobre como configurá-lo.

Cache-db

Para aumentar o desempenho, usamos os resultados do Redis para armazenar em cache do MongoDB. O cache está sendo apopado automaticamente em acidentes de cache.

Você pode criar uma nova instância com o Docker executando:

docker run -d 
    --name redis 
    redis

O Redis DB já está incluído no exemplo do arquivo docker-compose

Atualizando a imagem do contêiner

AVISO: Esteja ciente de que não oferecemos nenhum tipo de apoio oficial e todas as atualizações podem ser com mudanças de quebra. Certifique -se de fazer backups antes de atualizar

Para obter a versão mais recente da imagem do contêiner, você precisará executar:

docker pull ghcr.io/snaacky/theindex:latest

Depois, você precisará parar e remover sua instância de corrida atual e iniciá -la novamente.

Parâmetros

Aqui está uma coleção das possíveis variáveis ​​de ambiente com seus valores padrão que você deve definir no seu arquivo .env :

Parâmetro	Função	Padrão
NEXT_PUBLIC_SITE_NAME	O nome do seu site	"The Index"
NEXT_PUBLIC_DOMAIN	Seu domínio ou IP, remova a barra traseira	"https://theindex.moe"
DATABASE_URL	Dê uma olhada nos documentos do MongoDB	"mongodb://mongo:27017/index"
CACHE_URL	String de conexão para o banco de dados Redis Cache	"redis://redis:6379"
CHROME_URL	WebSocket URL para uma instância em execução do Chrome	"ws://chrome:3300"
AUDIT_WEBHOOK	Webhook-url para log de auditoria, deixe vazio para desativar o suporte	""
AUTH_DISCORD_ID	Discord OAuth2 ID do cliente	"your_discord_oauth_client_id"
AUTH_DISCORD_SECRET	Discord Oauth2 Client Secret	"your_discord_oauth_client_secret"
DISCORD_BOT_TOKEN	Necessário para acessar recursos de bot	"your_discord_bot_token"
SETUP_WHITELIST_DISCORD_ID	Se precisar de ajuda para obter sua identidade, consulte este guia	"your_discord_id"

E as seguintes variáveis ​​ENV são necessárias apenas quando você está no modo dev e depurando o banco de dados

Parâmetro	Função	Padrão
ME_CONFIG_BASICAUTH_USERNAME	Nome de usuário de Mongo-Express	"Admin"
ME_CONFIG_BASICAUTH_PASSWORD	senha mongon-express	"Super_secret"

Se você deseja verificar como o arquivo Docker-Compose preenche o Envs, use docker-compose config

Introdução a codificar

Configurar o aplicativo da web

1. Introdução não é tão direto. Você precisará ter instalado a versão mais recente do Docker com o Docker-Comppose em sua máquina.

2. Comece clonando o repo por meio de um cliente Git gráfico (altamente recomendado) ou use a CLI via

git clone https://github.com/snaacky/theindex

3. Copie o arquivo example.env para .env .

Como preencher o .env

• Substitua NEXT_PUBLIC_DOMAIN e NEXTAUTH_URL com http://localhost:3000
• Gere uma forte sequência aleatória de pelo menos 32 caracteres e use -a para NEXTAUTH_SECRET . Você pode usar geradores, por exemplo, 1Password ou criá -lo você mesmo.
• Alterar DATABASE_URL , CACHE_URL e CHROME_URL para usar localhost em vez de mongo , redis e chrome por exemplo: mongodb://mongo:27017 -> se torna mongodb://localhost:27017
• Vá para https://discord.com/developers -> Crie um novo aplicativo -> Vá para Auth2 dentro do painel de aplicativos -> Copie o CLIENT ID e CLIENT SECRET no arquivo .env .
• Em Redirects em Auth2 copie e cole o URL a seguir necessário para verificar seu Login Discord http://localhost:3000/api/auth/callback/discord .
• Preencha SETUP_WHITELIST_DISCORD_ID com seu ID do Discord para ter uma conta de administrador ao fazer o login.
• Gere novamente outra sequência forte aleatória de pelo menos 32 caracteres e use -a para MEILI_MASTER_KEY . Você pode usar geradores, por exemplo, 1Password ou criá -lo você mesmo.
• Por fim, se você deseja alterar a senha do Mongo-Express, poderá fazê-lo com as duas últimas variáveis, geralmente embora nenhum de nós faça enquanto se desenvolve localmente.

4. Adicione as seguintes portas às imagens no arquivo docker-compose :

serviço	mapeamento de porta
mongo	27017:27017
redis	6379:6379
meili	7700:7700
chrome	3300:3000

Como exemplo, a configuração para mongo deve parecer semelhante a isso:

 mongo :
  image : mongo
  container_name : index-db
  restart : unless-stopped
  ports :
    - ' 27017:27017 '
  volumes :
    - ./db:/data/db

5. Agora execute o comando para iniciar todos os processos de back -end necessários

docker-compose up -d mongo redis meili chrome mongo-express

Como alternativa, você também pode apenas comentar ou remover o serviço de índice e executar o comando

docker-compose up -d

Serviço da Web

Para começar a codificar no front -end, você precisará ter certeza de que você terá a versão mais recente do Node.js instalada corretamente. Para instalar todas as dependências necessárias executadas uma vez:

bun install

Nota: Decidimos manter o NPM em vez de fios para gerenciar dependências.

Agora você deve ter uma pasta chamada node_modules , que contém todas as dependências de que precisamos. Usamos o Next.js como estrutura para o nosso serviço Web React. Para testar o serviço da web, você precisará executar um servidor DB em segundo plano e iniciar o front -end:

bun run dev

Após a compilação, você pode abrir http: // localhost: 3000 no seu navegador de escolha e ver o aplicativo Web em execução.

À medida que usamos o Next.js, o front -end suporta recarregamento a quente, para que você possa deixar a página aberta, enquanto modifica o código e vê as alterações na mosca no seu navegador.

Imagem do Docker

Para criar uma imagem pronta para o Docker, basta executar:

docker build . -t index

Agora você tem uma imagem local com index de tags que contém uma versão distribuível do código que agora pode ser executada.

Formato automático

Usamos mais bonito para garantir um estilo de código consistente em todos os participantes. Você pode simplesmente formatar automaticamente tudo com por exemplo, executando o comando

bunx prettier --write . 

Design do aplicativo da web

ISR/SSR

Sempre que possível, usamos o ISR para gerar todas as páginas acessíveis ao público para armazenamento em cache por CDNs ou proxies enquanto valia e buscam novos dados com a SWR solicitando nossa própria API.

API

Servimos todas as solicitações da API sobre o terminal /api , o código correspondente pode ser visualizado nas páginas /API.

• /api/auth é reservado para Nextauth.js.
• /api/edit/... requer um usuário logado e geralmente (pelo menos) os direitos do editor e é para modificar ou criar um novo conteúdo. A palavra -chave _id _new é reservada para criar um novo conteúdo.
• /api/delete/... requer um usuário logado e geralmente (pelo menos) os direitos do editor e é para excluir o conteúdo.
• /api/[content]s são pontos de extremidade públicos para buscar uma lista de todos os itens de um determinado conteúdo.
• /api/[content]/... são pontos de extremidade públicos para obter informações sobre um conteúdo específico.

Restrições de página

Cada solicitação de página primeiro deve passar pelo _App.ts, onde um layout básico está sendo aplicado e, se uma página tiver uma propriedade auth , também valida se o usuário pode acessar a página fornecida. Os atributos de autenticação válidos são:

• auth é null ou typeof auth === "undefined" , sem restrições. Esta parece ser uma página pública.
• requireLogin , não é realmente necessário, mas defina -o por razões lógicas. O usuário deve ser logado.
• requireAdmin , apenas um usuário com direitos de administrador pode acessar esta página.
• requireEditor , apenas editores podem visualizar esta página.

Contribuição

As solicitações de tração são sempre bem-vindas, mas podem nem sempre ser mescladas, pois deve estar alinhado com a nossa idéia do índice. Se você deseja um determinado recurso ou tiver uma ideia, sempre pode abrir uma solicitação de recurso em problemas ou relatá -lo em nossa discórdia no #index a ser discutida. Se não for ruim, alinhado às nossas idéias, e encontramos algum tempo, certamente implementaremos seu recurso solicitado (algum dia ...).

Coisas que usamos

• Next.js como servidor da web
• Reaja como estrutura JS
• Estilos do bootstrap
• Ícones da font incrível
• Nós assamos tudo em uma imagem do Docker
• Executando no nó js
• Autenticação de usuário via NextAuth.js
• MongoDB como back -end de banco de dados
• Redis como cache
• marionetista para criar capturas de tela de sites
• Navegador/Chrome para executar nossa instância do Chrome
• react-in-viewport para verificar se os componentes forem visíveis ou não
• React-draggable para arrastar componentes pelo usuário final
• reagir-te-testificar para lidar com notificações
• ISO-639-3 para os idiomas

E o mais importante:

A ajuda de nossa incrível comunidade: 3

Dívidas técnicas

• Usamos JS em vez de TS (atualmente em migração)
• Editor unificado -Views
• Unificar inserção de banco de dados e atualizações para o formato de func(_id, dataObject) e atualizar apenas conforme necessário, o GraphQL seria bom ...
• Mova para add , remove a API em vez de ter que enviar matrizes inteiras para atualizar listas -> grafql?