vietqr-core-sdk

Installation & Custom Domain Setup Guide (Linux, Docker, SSL)

This guide covers deploying the VietQR Gateway Service on Linux environments (Ubuntu, Debian, CentOS, RHEL, Alpine) with enterprise PaaS/SaaS architecture, custom domain binding, and automated Let’s Encrypt TLS.

---

1. Deploy with Docker Compose (Recommended for SaaS)

Step 1: Prepare environment variables

Copy .env.example in deploy/docker/:

cd deploy/docker
cp .env.example .env
nano .env

Set your configuration:

DOMAIN=qr.yourdomain.com
PORT=8080
SCHEME=https
ACME_EMAIL=admin@yourdomain.com
VIETQR_API_KEYS=sk_live_tenant_prod_1,sk_live_tenant_prod_2

Step 2: Start services with automated HTTPS

docker-compose -f docker-compose.prod.yml up -d

The Caddy reverse proxy container automatically provisions and renews TLS certificates for qr.yourdomain.com from Let’s Encrypt and routes traffic to the Rust Gateway running on port 8080.

Verify container health:

docker-compose -f docker-compose.prod.yml ps
docker-compose -f docker-compose.prod.yml logs -f

---

2. Direct Linux Installation (Native Systemd Service)

An automated installer auto-detects CPU architecture (x86_64, aarch64/ARM64, armv7l) and provisions systemd units.

Step 1: Run the installer script

sudo bash deploy/linux/install.sh --domain qr.yourdomain.com --scheme https

The installer will:

1. Create an isolated system user vietqr.
2. Deploy binaries and local assets to /opt/vietqr.
3. Configure environment parameters in /etc/vietqr/vietqr.env.
4. Register and enable the vietqr.service systemd daemon.

Step 2: Service Management

# Check service status
sudo systemctl status vietqr

# Restart service
sudo systemctl restart vietqr

# Stream logs
sudo journalctl -u vietqr -f

---

3. Nginx Reverse Proxy Setup (Alternative)

If using existing Nginx installations:

1. Copy the configuration file:

   sudo cp deploy/reverse-proxy/nginx/vietqr.conf /etc/nginx/sites-available/vietqr.conf
   sudo ln -s /etc/nginx/sites-available/vietqr.conf /etc/nginx/sites-enabled/
   

2. Replace qr.yourdomain.com with your actual domain:

   sudo sed -i 's/qr.yourdomain.com/your-domain.com/g' /etc/nginx/sites-available/vietqr.conf
   

3. Issue SSL certificates via Certbot:

   sudo certbot --nginx -d your-domain.com
   sudo systemctl reload nginx
   

---

4. Verification

• Health Check: https://qr.yourdomain.com/health
• Web Studio: https://qr.yourdomain.com/studio
• Image QuickLink: https://qr.yourdomain.com/image/970436-1234567890-compact2.png?amount=50000&addInfo=Test
• Deeplink Pay Hub: https://qr.yourdomain.com/qr/pay?bin=970436&acc=1234567890&amount=50000

This site is open source. Improve this page.