Installation

Requirements

• Docker, docker-compose
• Postgres 14+ (use can run it via docker)
• Website with configured SSL certificate e.g. pay.your-site.com

tip

For HTTPs usage you can run OxygenPay under any reverse-proxy server such as Nginx, Traefik, or others.

Setting up third-party services

OxygenPay relies on several third-party providers including:

• TronGrid for communicating with TRON blockchain. You need to register and issue an API token. It's free for most use-cases. Required for:
  • TRONGRID_API_KEY
• Tatum for communicating with EVM-based chains, receiving on-chain events, and gathering latest exchange rates. It's free for demo usage, but we recommend buying a paid plan for production usage . Required for:
  • TATUM_API_KEY
  • TATUM_TEST_API_KEY
  • TATUM_HMAC_SECRET

Commands Overview

OxygenPay consists of several services that can be run either within a single bundle or separately. For the simplicity of installation we recommend using docker-compose with an all-in-one command, but you can also use plain Docker, or Kubernetes, or run the binary without containerized environment at all.

Available Commands:
  serve-kms     Start KMS (Key Management Server)
  serve-web     Start Oxygen Server
  run-scheduler Start Scheduler Service
  all-in-one    Runs server, scheduler, and KMS in a single instance
  create-user   Creates new user with provided email & password
  list-wallets  List wallets in the database
  env           Outputs available ENV variables

Running with docker-compose

You can access docker images using GitHub Container Registry (link). To run an instance, copy docker-compose.yml, create and edit oxygen.env, then run compose stack:

$ >tree
.
├── docker-compose.yml
└── oxygen.env

docker-compose up -d

docker-compose.yml:

version: '3.8'
services:
  oxygen:
    image: ghcr.io/oxygenpay/oxygen:latest
    command: all-in-one --skip-config
    env_file: [ oxygen.env ]
    volumes: [ 'app-volume:/app' ]
    ports: [ '80:80' ]
    networks: [ net-oxygen ]
    depends_on: [ postgres ]
    restart: on-failure

  postgres:
    image: postgres:15-alpine
    restart: on-failure
    environment:
      # don't forget to change credentials!
      - POSTGRES_DB=oxygen
      - POSTGRES_USER=oxygen
      - POSTGRES_PASSWORD=<required>
    volumes:
      - 'pg-data:/var/lib/postgresql/data'
    ports: [ '5432:5432' ]
    networks: [ net-oxygen ]

networks:
  net-oxygen:

volumes:
  app-volume:
  pg-data:

oxygen.env:

# Oxygen
WEB_PORT=80
DB_DATA_SOURCE="host=postgres sslmode=disable dbname=oxygen user=oxygen password=oxygen pool_max_conns=32"
SESSION_FS_PATH=/app/sessions

# Random secure string
SESSION_SECRET=<required>

CORS_ALLOW_ORIGINS=https://pay.your-site.com
PROCESSING_WEBHOOK_BASE_PATH=https://pay.your-site.com
PROCESSING_PAYMENT_FRONTEND_BASE_PATH=https://pay.your-site.com
KMS_DB_DATA_SOURCE=/app/kms/kms.db

# Specify initial user here
EMAIL_AUTH_USER_EMAIL=<required>

# Random secure string
EMAIL_AUTH_USER_PASSWORD=<required>

# Providers 
TATUM_API_KEY=<required>
TATUM_TEST_API_KEY=<required>
TRONGRID_API_KEY=<required>

# Random secure string
TATUM_HMAC_SECRET=<required>

caution

Don't forget to change sensitive credentials like DB_DATA_SOURCE, SESSION_SECRET, EMAIL_AUTH_USER_PASSWORD, and others.

After completing these steps, open configured website and proceed to /dashboard. Log in by using email credentials:

Notes after installation

Internal fees

Oxygen uses inbound wallets to receive payments and then transfers assets to outbound addresses. This involves additional internal gas fees depending on the blockchain. Keep that in mind.

Tron outbound wallet

Tron blockchain is notorious for requiring an "activation" transaction for new addresses. To facilitate internal transfers from inbound to outbound wallets on this network you need to activate outbound tron address manually by sending to it any amount of TRX (0.000001). You can use docker-compose run oxygen list-wallets --skip-config command to find the exact address of Tron outbound wallet.