> ## Documentation Index
> Fetch the complete documentation index at: https://joey727-phisherman.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment

> Deploy Phisherman using Docker or run it directly with Node.js.

## Docker deployment

**1. Build the image**

From the project root, build the Docker image:

```bash theme={null}
docker build -t phisherman .
```

**2. Run the container**

Start the container and pass your environment variables:

```bash theme={null}
docker run -p 4000:4000 \
  -e UPSTASH_REDIS_REST_URL=https://your-upstash-endpoint.upstash.io \
  -e UPSTASH_REDIS_REST_TOKEN=your_upstash_token \
  -e GOOGLE_SAFE_API_KEY=your_google_safe_browsing_key \
  phisherman
```

The API is now available at `http://localhost:4000`.

### Docker environment variables

Pass these variables to the container using `-e` flags or a `.env` file with `--env-file`:

| Variable | Required | Description |
| - | - | - |
| `UPSTASH_REDIS_REST_URL` | Yes | REST URL for your Upstash Redis database |
| `UPSTASH_REDIS_REST_TOKEN` | Yes | Authentication token for your Upstash Redis database |
| `GOOGLE_SAFE_API_KEY` | No | Google Safe Browsing API key. If omitted, the GSB checker returns score `0` without making any API call. |
| `PORT` | No | Port the server listens on (default: `4000`) |
| `SCAN_CACHE_SAFE_RESULTS` | No | Set to `true` to cache safe scan results in Redis (default: `false`) |
| `WEBRISK_API_KEY` | No | Google Web Risk API key. Only needed if you enable the `WebRiskChecker` (disabled by default). |

> [!WARNING]
>
> Never commit `GOOGLE_SAFE_API_KEY` or any other secrets to source control. Pass them as environment variables at runtime or use a secrets manager.

### Dockerfile

```dockerfile theme={null}
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./

RUN npm install --production

COPY . .

RUN npm run build

EXPOSE 4000

# Start server
CMD ["npm", "start"]
```

## Node.js deployment

To run Phisherman directly without Docker:

```bash theme={null}
npm run build && npm start
```

This compiles the TypeScript source with `tsc` and then runs `node dist/index.js`.

For long-running production deployments, use a process manager such as [PM2](https://pm2.keymetrics.io) to handle automatic restarts and logging:

```bash theme={null}
npm install -g pm2
pm2 start dist/index.js --name phisherman
pm2 save
pm2 startup
```

## Production considerations

> [!TIP]
>
> Phisherman is designed with production use in mind:
>
> * **Reverse proxy support**: `trust proxy` is already set to `1` in Express, so real client IPs are correctly read from the `X-Forwarded-For` header when you place Phisherman behind Nginx, Caddy, or a cloud load balancer.
> * **Persistent rate limiting**: Rate limit counters are stored in Redis, so they survive application restarts and work correctly across multiple instances.
> * **Persistent feed cache**: Threat feed data (URLHaus, OpenPhish, PhishTank, PhishStats) is cached in Redis and persists across restarts, which means feeds are available immediately on startup after the first run.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.