Getting Started

The OPI Proxy is designed to get you to a working local setup quickly. The public distribution is Docker-first, so most teams can test the integration without building the source project themselves.

Quick Links

What You Need

For a normal installation, you need:

• Docker Desktop or Docker Engine with Compose
• one .env file
• local copies of the terminal profile and terminal configuration examples in config/
• generated authentication in config/auth.json
• optional TLS certificate and key files if you want non-local HTTPS

Quick Start

The public repo is meant to be cloned and run directly:

git clone https://github.com/richiehug/nexi-opi-proxy.git
cd nexi-opi-proxy
cp .env.example .env
cp config/terminal-profiles.json.example config/terminal-profiles.json
cp config/terminals.json.example config/terminals.json
docker compose pull
docker compose run --rm auth-init
docker compose up -d

For a first local smoke test:

curl http://127.0.0.1:3001/health

Before processing a payment, set the terminal IP address, model, profile, and a stable workstationId in config/terminals.json.

Required Network Paths

Both OPI directions must work. With the normal defaults:

The supplied Linux deployment uses Docker host networking, so the proxy uses the host network stack directly. If the terminal cannot reach the callback port, a payment can start successfully while receipts, display messages, input prompts, or the final result fail to return.

Some terminal configurations use the second OPI channel pair: proxy to terminal on TCP 4101 and terminal to proxy on TCP 4103. Allow those ports as well when they are configured for the terminal. The pay-channel and callback ports in config/terminals.json must always match the terminal setup.

If you change the OPI ports, update the terminal configuration and config/terminals.json together. See Network Requirements for terminal infrastructure and external firewall destinations.

Initialization

The proxy does not ship with config/auth.json.

Generate it with:

docker compose run --rm auth-init

That command:

• creates config/auth.json
• creates the bootstrap admin token if no auth config exists yet
• prints the admin bearer token directly in the terminal

Store that token immediately.

Starting the Service

Once .env and config/ are in place, start the runtime with:

docker compose up -d

Useful follow-up commands:

docker compose logs -f proxy
docker compose ps

Local HTTP and HTTPS

The transport model keeps local development easy and shared setups safer:

• the public template permits HTTP for an easy first run on a trusted setup network
• shared or remotely reachable deployments should use HTTPS
• TLS material is file-based, so certificates can be mounted into certs/

For quick local HTTPS testing, the proxy can generate a development certificate:

docker compose run --rm tls-init-dev

That certificate is for testing only.

For a production-style setup, use TLS_MODE=required, provide a trusted certificate and key, and set ALLOW_INSECURE_REMOTE_HTTP=false.

What Gets Persisted

The Docker layout keeps merchant-owned runtime data outside the image:

• config/
• data/
• logs/
• certs/

That makes upgrades simpler because your configuration, auth state, transaction data, and receipt data stay on the host.

New installations normally use SQLite in data/ through STORAGE=db. Existing installations can continue using JSON files with STORAGE=json.