Installation

Technologies

Eve Wormhole Mapper is written in C# using ASP.NET Core Blazor Server, EF Core, SignalR, and utilizes several third-party components, particularly:

• Blazor.DIAGRAMS
• MudBlazor

Requirements

Domain

We recommend using a domain name (your.domain.com) with public DNS for easy and consistent access.

Register your app with CCP

Eve-whmapper requires CCP's SSO authentication API to use the ESI API. Register your app at developers.eveonline.com:

1. Click the "MANAGE APPLICATIONS" button.
2. Click the "CREATE NEW APPLICATION" button.
3. Choose a name for your installation (e.g., prod eve-whmapper).
4. Enter a description for this installation (e.g., Eve Wormhole Mapper on production).
5. Change "CONNECTION TYPE" to "Authentication & API Access".
6. Add the minimum required "PERMISSIONS" (scopes):
   • esi-location.read_location.v1
   • esi-location.read_ship_type.v1
   • esi-ui.open_window.v1
   • esi-ui.write_waypoint.v1
   • esi-search.search_structures.v1
7. Set your "CALLBACK URL" (e.g., https://your.domain.com/sso/callback).
8. Click the "CREATE APPLICATION" button.
9. Copy the Client ID, Secret Key, and Callback URL for use in the next configuration step.

Installation

EVE WHMapper can be installed using Docker, Kubernetes, or directly on Linux/Windows using the pre-built binaries. Choose the installation method that best suits your environment.

Docker

Deploy with Docker & Compose

Deploying the Eve Wormhole Mapper using Docker and Compose is straightforward, especially if you follow these steps for your server and Docker setup.

Server

We recommend using a Linux server with the Debian OS for optimal performance and support. If you prefer to use a different operating system, you will need to write your own init script or manually configure the necessary files (see the list below).

Docker

Before proceeding, ensure Docker is installed on your system. Follow the appropriate instructions for your operating system:

• Linux
• Windows
• OS X

Get Docker-Compose Template

1. Navigate to your desired installation location.
2. Clone the Eve-Whmapper repository. It is recommended to install in /opt/ for Linux or a suitable directory for Windows.

Linux

sudo git clone https://github.com/pfh59/eve-whmapper.git
cd eve-whmapper/deploy/docker

Windows

git clone https://github.com/pfh59/eve-whmapper.git
cd eve-whmapper/deploy/docker

Configuration

Configuring Eve-Whmapper is simplified through the initialization script. Run the following script as a sudo or root user on Linux, or as an Administrator on Windows, and follow the on-screen instructions:

Linux

sudo ./init.sh

Windows

./init.ps1

This script automatically:

• Updates all the configurations (docker-compose.yml, haproxy.cfg, nginx.conf) from your response,
• Initializes all Docker containers,
• Creates, adds, and uses a strong certificate to use HTTPS with your domain.

Start and Stop

To manage the Docker containers, use the provided scripts:

Linux

• To Start all containers: Use the start.sh script as a sudo or root user.

sudo ./start.sh

• To Stop all containers: Use the stop.sh script as a sudo or root user.

sudo ./stop.sh

Windows

• To Start all containers: Use the start.ps1 script as an Administrator.

./start.ps1

• To Stop all containers: Use the stop.ps1 script as an Administrator.

./stop.ps1

Kubernetes

Deploy on Kubernetes

This section details the deployment process of the application on a Kubernetes cluster. The configuration described here was tested on a Raspberry Pi cluster.

Kubernetes Setup

Install k3s

To install k3s, run the following commands:

apt update
curl -sfL https://get.k3s.io | sh -

Retrieve Node Token

To get the node token, execute:

cat /var/lib/rancher/k3s/server/node-token

Install Ingress

Apply the Ingress controller:

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.9.5/deploy/static/provider/cloud/deploy.yaml

Install Cert Manager

Deploy the Cert Manager:

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.3/cert-manager.yaml

• Troubleshooting Certificates:

  • List all certificates:

  sudo kubectl get ClusterIssuers,Certificates,CertificateRequests,Orders,Challenges --all-namespaces

  • Check details of a specific certificate request (e.g., eve-mapper):

  sudo kubectl describe certificaterequest tls-evemapper-1 -n evemapper

Install Portainer (optional)

To install Portainer, execute:

kubectl apply -n portainer -f https://raw.githubusercontent.com/portainer/k8s/master/deploy/manifests/portainer/portainer.yaml
kubectl apply -f https://downloads.portainer.io/ce2-19/portainer-agent-k8s-lb.yaml

Configuration

The configuration is divided across multiple files.

Configure Environment Variables

All services use the same ConfigMap defined in deploys/envs.yaml [ConfigMap]:

• DOMAIN: your domain (ex: map.mycorp.com)
• POSTGRES_DB: your db name
• POSTGRESQL_USERNAME: your db user
• POSTGRESQL_PASSWORD: your db password
• POSTGRESQL_DATABASE: same as POSTGRES_DB
• EveSSO__ClientId: your client ID given from CCP
• EveSSO__Secret: your secret key given from CCP
• ConnectionStrings__DatabaseConnection: server=<cluster-local-ip>;port=31252;database=<same as POSTGRES_DB>;User Id=<same as POSTGRESQL_USERNAME>;Password=<same as POSTGRESQL_PASSWORD>
• ConnectionStrings__RedisConnection: <cluster-local-ip>:31253

Remarks:

• cluster-local-ip refers to the local IP of the master node in your network. Typically, this is not an internet-facing IP. For instance, it could be 192.168.1.50 (master node).
• Sensitive values are stored as Secrets and must be base64 encoded.

Configure Certificates

Environment values aren't directly usable in deployment files. Modify these manually in relevant configuration files.

In deploys/base.yaml [Certificate-issuer]:

• email: Provide a valid email to receive notifications regarding certificate expiry.

In deploys/base.yaml [Certificate]:

• commonName: Set it to your subdomain (should match DOMAIN in environment variables).

    ex:
        commonName: map.mycorp.com

• dnsNames: List all DNS names you'll use, including commonName.

  ex:
    - map.mycorp.com
    - mapper.mycorp.com

Configure Ingress

In deploys/ingress.yaml [evemapper-ingress]: replace [your SUB/DOMAIN] with your actual subdomain.

Deployment

Deploy all configurations located in the deploys directory simultaneously:

kubectl apply -f deploys

Note: You might need to run the deployment twice, as some services require the namespace to be created before initialization.

• First run result:

namespace/evemapper created
issuer.cert-manager.io/letsencrypt-evemapper created
certificate.cert-manager.io/tls-evemapper created
configmap/evemapper-config-map created
secret/evemapper-secrets created
deployment.apps/evemapper-app created
service/evemapper-app-service created
ingress.networking.k8s.io/evemapper-ingress created
Error from server (NotFound): namespaces "evemapper" not found

• Second run result:

deployment.apps/postgres created
service/postgres-cluster-ip-service created
deployment.apps/redis created
service/redis-cluster-ip-service created
namespace/evemapper unchanged
issuer.cert-manager.io/letsencrypt-evemapper unchanged
certificate.cert-manager.io/tls-evemapper unchanged
configmap/evemapper-config-map unchanged
secret/evemapper-secrets unchanged
deployment.apps/evemapper-app unchanged
service/evemapper-app-service unchanged
ingress.networking.k8s.io/evemapper-ingress unchanged

Update Application & Restart

To redeploy the application, use:

kubectl rollout restart deployment evemapper-app -n evemapper

Self-Hosted (Binary) ⚠️ Beta

Self-Hosted Installation (Binary)

This guide covers installing Eve Wormhole Mapper directly on Linux Debian or Windows without Docker, using the pre-built binaries published on GitHub Releases.

Beta — feedback welcome

This self-hosted (binary) installation method is new and has had limited real-world testing compared to the Docker/Kubernetes methods. Steps may be incomplete or unclear for some environments (distributions, Windows versions, reverse proxy setups, etc.).

If you run into an issue, a step that doesn't work, or anything unclear, please open an issue on the docs repository — your feedback directly helps fix and clarify this guide.

Requirements

Component	Minimum version
.NET ASP.NET Core Runtime	10.0
PostgreSQL	17
Redis	8

Architecture

The published binaries are framework-dependent (not self-contained). The .NET 10 ASP.NET Core Runtime must be installed on the host — the .NET SDK is not required.

Installation

Linux (x64 / ARM)

1. Install .NET 10 ASP.NET Core Runtime

Follow the official Microsoft instructions for your distribution: https://learn.microsoft.com/dotnet/core/install/linux

Debian example:

# Add Microsoft package repository
wget https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

# Install the runtime (not the full SDK)
sudo apt-get update
sudo apt-get install -y aspnetcore-runtime-10.0

Verify:

dotnet --info

2. Install PostgreSQL 17

sudo apt-get install -y postgresql-17
sudo systemctl enable --now postgresql

3. Install Redis 8

sudo apt-get install -y redis-server
sudo systemctl enable --now redis-server

4. Create a system user

sudo useradd --system --no-create-home --shell /usr/sbin/nologin whmapper

5. Download and extract the binary

Download the latest release from GitHub Releases.

# Create installation directory
sudo mkdir -p /opt/whmapper
sudo mkdir -p /opt/whmapper/Logs

# Download the binary (replace vX.Y.Z with the actual version)
wget https://github.com/pfh59/eve-whmapper/releases/download/vX.Y.Z/WHMapper.linux-x64.zip -O /tmp/WHMapper.linux-x64.zip

# For ARM systems, use:
# wget https://github.com/pfh59/eve-whmapper/releases/download/vX.Y.Z/WHMapper.linux-arm.zip -O /tmp/WHMapper.linux-arm.zip

sudo unzip /tmp/WHMapper.linux-x64.zip -d /opt/whmapper
sudo chown -R whmapper:whmapper /opt/whmapper
sudo chmod +x /opt/whmapper/WHMapper

6. Configure PostgreSQL

sudo -u postgres psql <<EOF
CREATE USER whmapper WITH PASSWORD 'your_strong_password';
CREATE DATABASE whmapper OWNER whmapper;
GRANT ALL PRIVILEGES ON DATABASE whmapper TO whmapper;
EOF

7. Configure the application

Create an environment file with your settings:

sudo nano /etc/whmapper.env

/etc/whmapper.env

EveSSO__ClientId=your_ccp_client_id
EveSSO__Secret=your_ccp_secret
ConnectionStrings__DatabaseConnection=server=localhost;port=5432;database=whmapper;User Id=whmapper;Password=your_strong_password
ConnectionStrings__RedisConnection=localhost:6379
Serilog__MinimumLevel__Default=Warning

sudo chmod 600 /etc/whmapper.env
sudo chown whmapper:whmapper /etc/whmapper.env

8. Create a systemd service

sudo nano /etc/systemd/system/whmapper.service

/etc/systemd/system/whmapper.service

[Unit]
Description=EVE Wormhole Mapper
After=network.target postgresql.service redis-server.service
Requires=postgresql.service redis-server.service

[Service]
Type=simple
User=whmapper
WorkingDirectory=/opt/whmapper
ExecStart=/opt/whmapper/WHMapper
EnvironmentFile=/etc/whmapper.env
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now whmapper
sudo systemctl status whmapper

The application will start on port 5000 (HTTP) by default when run without a reverse proxy.

9. (Optional) Configure nginx as a reverse proxy with HTTPS

sudo apt-get install -y nginx certbot python3-certbot-nginx

/etc/nginx/sites-available/whmapper

server {
    listen 80;
    server_name your.domain.com;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

sudo ln -s /etc/nginx/sites-available/whmapper /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# Obtain a Let's Encrypt certificate
sudo certbot --nginx -d your.domain.com

Add these variables to /etc/whmapper.env to enforce HTTPS:

ASPNETCORE_URLS=http://127.0.0.1:5000

Restart the service:

sudo systemctl restart whmapper

Windows (x64)

1. Install .NET 10 ASP.NET Core Runtime

Download and install the ASP.NET Core Runtime 10.0 from the official page: https://dotnet.microsoft.com/download/dotnet/10.0

Select "ASP.NET Core Runtime" (not the SDK).

Verify in PowerShell:

dotnet --info

2. Install PostgreSQL 17

Download the Windows installer from www.enterprisedb.com/downloads/postgres-postgresql-downloads.

During setup:

• Note the port (default: 5432)
• Set a strong password for the postgres superuser

Alternatively, with Chocolatey:

choco install postgresql17 --params '/Password:your_strong_password'

3. Install Redis

Redis does not have an official Windows binary. Use Memurai (Redis-compatible for Windows):

Download and install from www.memurai.com. It runs as a Windows service on port 6379 by default.

Alternatively, use Redis on Windows via WSL2.

4. Download and extract the binary

Download the latest release from GitHub Releases.

# Create installation directory
New-Item -ItemType Directory -Path "C:\whmapper" -Force
New-Item -ItemType Directory -Path "C:\whmapper\Logs" -Force

# Download (replace vX.Y.Z with the actual version)
Invoke-WebRequest -Uri "https://github.com/pfh59/eve-whmapper/releases/download/vX.Y.Z/WHMapper.win-x64.zip" `
    -OutFile "$env:TEMP\WHMapper.win-x64.zip"

Expand-Archive -Path "$env:TEMP\WHMapper.win-x64.zip" -DestinationPath "C:\whmapper" -Force

5. Configure PostgreSQL

Open pgAdmin or psql and run:

CREATE USER whmapper WITH PASSWORD 'your_strong_password';
CREATE DATABASE whmapper OWNER whmapper;
GRANT ALL PRIVILEGES ON DATABASE whmapper TO whmapper;

Or via psql in PowerShell:

& "C:\Program Files\PostgreSQL\17\bin\psql.exe" -U postgres -c "CREATE USER whmapper WITH PASSWORD 'your_strong_password';"
& "C:\Program Files\PostgreSQL\17\bin\psql.exe" -U postgres -c "CREATE DATABASE whmapper OWNER whmapper;"

6. Configure the application

Create a configuration file next to the binary:

New-Item -Path "C:\whmapper\appsettings.Production.json" -ItemType File

Edit C:\whmapper\appsettings.Production.json:

C:\whmapper\appsettings.Production.json

{
  "EveSSO": {
    "ClientId": "your_ccp_client_id",
    "Secret": "your_ccp_secret"
  },
  "ConnectionStrings": {
    "DatabaseConnection": "server=localhost;port=5432;database=whmapper;User Id=whmapper;Password=your_strong_password",
    "RedisConnection": "localhost:6379"
  },
  "Serilog": {
    "MinimumLevel": {
      "Default": "Warning"
    }
  }
}

Environment variables as alternative

You can also configure the application using system environment variables instead of a file. Environment variable names use __ as separator (e.g., EveSSO__ClientId).

7. Register as a Windows Service

Open PowerShell as Administrator:

# Set the ASPNETCORE_ENVIRONMENT so the Production config is loaded
[System.Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Production", "Machine")

# Register the service
sc.exe create "WHMapper" `
    binPath= "C:\whmapper\WHMapper.exe" `
    start= auto `
    DisplayName= "EVE Wormhole Mapper"

sc.exe description "WHMapper" "EVE Wormhole Mapper - self-hosted binary"

# Start the service
sc.exe start "WHMapper"

Check the service status:

sc.exe query "WHMapper"

Logs are written to C:\whmapper\Logs\.

8. (Optional) Configure nginx as a reverse proxy with HTTPS

Download nginx for Windows from nginx.org/en/download.html and extract it to C:\nginx.

Edit C:\nginx\conf\nginx.conf:

C:\nginx\conf\nginx.conf

worker_processes 1;

events { worker_connections 1024; }

http {
    server {
        listen 80;
        server_name your.domain.com;

        location / {
            proxy_pass http://127.0.0.1:5000;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }

    server {
        listen 443 ssl;
        server_name your.domain.com;

        ssl_certificate     C:/nginx/certs/fullchain.pem;
        ssl_certificate_key C:/nginx/certs/privkey.pem;

        location / {
            proxy_pass http://127.0.0.1:5000;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-Proto https;
        }
    }
}

Register nginx as a Windows service using NSSM:

nssm install nginx "C:\nginx\nginx.exe"
nssm start nginx

Place your SSL certificates in C:\nginx\certs\.

Add to appsettings.Production.json to bind only on localhost:

{
  "http_port": 5000,
  "https_port": null
}

Restart the WHMapper service:

sc.exe stop "WHMapper"
sc.exe start "WHMapper"

---

Configuration Reference

Key	Environment variable	Default	Description
EveSSO.ClientId	EveSSO__ClientId	(none)	CCP SSO Client ID
EveSSO.Secret	EveSSO__Secret	(none)	CCP SSO Secret
ConnectionStrings.DatabaseConnection	ConnectionStrings__DatabaseConnection	(none)	PostgreSQL connection string
ConnectionStrings.RedisConnection	ConnectionStrings__RedisConnection	(none)	Redis connection string
http_port	http_port	80	HTTP listening port
https_port	https_port	443	HTTPS listening port
Instances.SingleTenantMode	Instances__SingleTenantMode	false	Restrict to a single EVE corporation
DisableSignalRCertificateValidation	DisableSignalRCertificateValidation	false	Disable TLS validation for SignalR (local/dev only)
Serilog.MinimumLevel.Default	Serilog__MinimumLevel__Default	Warning	Log level

Updating

To update to a newer version:

1. Download the new binary from GitHub Releases.
2. Stop the service.
3. Replace the files in the installation directory (keep your appsettings.Production.json or environment file).
4. Start the service. Database migrations are applied automatically on startup.

Problems?

If you encounter any issues or need assistance, please ask for help on our GitHub repository.

---

Next step → First Start