> For the complete documentation index, see [llms.txt](https://docs.ipcheck.ing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipcheck.ing/developer/pt-br/getting-started/deploy-with-nodejs.md).

# Implantar com Node.js

Compile e execute o MyIP diretamente com Node.js e pnpm, com gerenciamento de processos pm2 opcional.

Executar a partir do código-fonte é a escolha certa quando você quer personalizar a build — alterar a marca, adicionar uma ferramenta ou definir qualquer `VITE_*` variável, o que a imagem pré-compilada do Docker não consegue fazer.

## Pré-requisitos

| Requisito      | Observações                                                                                                                 |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Node.js 24** | A imagem oficial do Docker é baseada em `node:24-alpine`. Versões principais mais antigas não foram testadas.               |
| **pnpm**       | O repositório fixa a versão do pnpm em `package.json` (`packageManager`). Use o Corepack para obter exatamente essa versão. |
| **git**        | Para clonar e fazer pull de atualizações.                                                                                   |

{% tabs %}
{% tab title="Corepack (recomendado)" %}
O Corepack vem com o Node.js e provisiona automaticamente a versão fixa do pnpm:

```bash
corepack enable
```

Sem instalação global, sem divergência de versão.
{% endtab %}

{% tab title="npm" %}

```bash
npm install -g pnpm
```

Funciona em qualquer lugar, mas você é responsável por manter o pnpm próximo da versão fixada.
{% endtab %}
{% endtabs %}

## Instalar e compilar

{% stepper %}
{% step %}

#### Clonar

```bash
git clone https://github.com/jason5ng32/MyIP.git
cd MyIP
```

{% endstep %}

{% step %}

#### Configurar o ambiente

```bash
cp .env.example .env
```

Abra `.env` e preencha pelo menos as credenciais da MaxMind:

{% code title=".env" %}

```bash
BACKEND_PORT="11966"
FRONTEND_PORT="18966"
MAXMIND_ACCOUNT_ID="your-account-id"
MAXMIND_LICENSE_KEY="your-license-key"
MAXMIND_AUTO_UPDATE="true"
ALLOWED_DOMAINS="myip.example.com"
```

{% endcode %}

Todas as outras variáveis são opcionais — veja [Variáveis de ambiente](/developer/pt-br/reference/environment-variables.md).

{% hint style="warning" %}
Defina suas `VITE_*` variáveis **antes de** você compilar. O Vite as lê no momento da compilação e as incorpora ao bundle; alterá-las depois exige outra `pnpm run build`.
{% endhint %}
{% endstep %}

{% step %}

#### Instalar dependências

```bash
pnpm install
```

{% endstep %}

{% step %}

#### Compilar o frontend

```bash
pnpm run build
```

Isso produz `dist/`, o bundle estático servido pelo servidor do frontend.
{% endstep %}

{% step %}

#### Iniciar

```bash
pnpm start
```

Abra <http://localhost:18966>.
{% endstep %}
{% endstepper %}

## Os dois processos

`pnpm start` executa as duas metades do app em um único terminal (via `concurrently`):

| Processo | Script               | Porta padrão              | Função                                                                                                                  |
| -------- | -------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Frontend | `frontend-server.js` | `18966` (`FRONTEND_PORT`) | Serve `dist/` com cabeçalhos de cache ajustados, trata o fallback de histórico de SPA e faz proxy `/api` para o backend |
| Backend  | `backend-server.js`  | `11966` (`BACKEND_PORT`)  | A API Express, além dos atualizadores dos conjuntos de dados MaxMind e CAIDA                                            |

Os usuários só se comunicam com a porta do frontend. O backend não precisa estar acessível de fora do host — o frontend faz proxy `/api` para `http://localhost:<BACKEND_PORT>` para eles.

Você também pode executá-los separadamente:

```bash
pnpm run start-frontend
pnpm run start-backend
```

{% hint style="info" %}
`start-backend` inicia o Node com `--import ./sentry-instrument.js`. Essa flag deve vir antes de o Express carregar para que a instrumentação ESM do Sentry seja anexada. Sem `SENTRY_DSN_BACKEND` ela, isso não faz nada, então é seguro mantê-la em todas as implantações.
{% endhint %}

## Executando sob pm2

`pnpm start` morre com o seu shell. Para uma implantação real, use a configuração do pm2 que acompanha o repositório — ela já traz os flags corretos do Node.

{% stepper %}
{% step %}

#### Instalar o pm2

```bash
npm install -g pm2
```

{% endstep %}

{% step %}

#### Iniciar os dois aplicativos

```bash
pm2 start ecosystem.config.cjs
```

Isso registra dois processos: `myip-backend` e `myip-frontend`.
{% endstep %}

{% step %}

#### Sobreviver a reinicializações

```bash
pm2 save
pm2 startup
```

Depois execute o comando que o pm2 exibir.
{% endstep %}
{% endstepper %}

Comandos úteis:

```bash
pm2 status
pm2 logs myip-backend
pm2 restart ecosystem.config.cjs
pm2 stop myip-frontend
```

{% hint style="info" %}
O atualizador da MaxMind obtém um bloqueio de arquivo antes de baixar, então executar o backend sob várias instâncias do pm2 não produzirá dois downloads simultâneos nem um banco de dados parcialmente gravado.
{% endhint %}

## Atualização

```bash
git pull
pnpm install
pnpm run build
pm2 restart ecosystem.config.cjs
```

Não pule `pnpm run build` — o aplicativo em execução serve o que estiver em `dist/`, e não o seu código-fonte atualizado.

## Onde os dados ficam

Os conjuntos de dados são baixados para a árvore de trabalho e são excluídos do git:

* `common/maxmind-db/` — `GeoLite2-City.mmdb`, `GeoLite2-ASN.mmdb`, além do estado do atualizador e dos arquivos de bloqueio
* `common/as-org-db/`, `common/as-rel-db/` — os conjuntos de dados da CAIDA usados para os nomes de organização do ASN e o grafo de conectividade do ASN

Eles sobrevivem a `git pull`, portanto as atualizações não baixam nada novamente.

## Próximos passos

* [Configuração da MaxMind](/developer/pt-br/getting-started/maxmind-setup.md) — incluindo a opção manual `.mmdb` opção, que só funciona neste caminho de implantação
* [Proxy reverso e domínios](/developer/pt-br/getting-started/reverse-proxy-and-domains.md) — TLS e `ALLOWED_DOMAINS`
* [Ambiente de Desenvolvimento](/developer/pt-br/development/dev-environment.md) — `pnpm dev` com hot reload, se você pretende alterar o código
* [Variáveis de ambiente](/developer/pt-br/reference/environment-variables.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ipcheck.ing/developer/pt-br/getting-started/deploy-with-nodejs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.