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
• terminal configuration 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
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

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:

• localhost can use HTTP
• non-local traffic 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.

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.