ZVault Deployment Guide

Follow these steps to deploy and configure your self-hosted ZVault instance.

Introduction

This guide provides a comprehensive walkthrough for deploying the ZVault self-hosted solution. By following these instructions, you will set up the necessary server environment, configure the backend and database, and deploy the application to start accepting shielded Zcash payments on your own infrastructure.

Ensure you have a moderate understanding of server administration, Azure cloud services, and command-line interfaces before proceeding.

Prerequisites

  • An active Microsoft Azure subscription.
  • Azure CLI installed and configured, or access to the Azure Portal.
  • SSH client for accessing your server.
  • scp command-line utility (or an equivalent SFTP client) for file transfers.
  • Basic familiarity with Linux command line and ufw (Uncomplicated Firewall).
  • Access to your Z-Vault-Admin and ZPAY project repositories/files.

Deployment Steps

Follow these steps methodically to ensure a successful deployment of your ZVault instance.

Step 0: Azure Server Setup & Firewall Configuration

Begin by provisioning a new virtual machine (VM) on Microsoft Azure. A Linux distribution (e.g., Ubuntu Server 22.04 LTS) is recommended. Once the VM is running, you need to configure its network security group (NSG) in Azure and the local firewall (ufw) on the server to allow traffic on specific ports.

Ports to open:

  • 5173: For the Vite-based Z-Vault-Admin frontend.
  • 5001: For the ZPAY backend API service.
  • 22: For SSH access (ensure this is restricted to trusted IPs if possible).

Azure NSG Configuration:

  1. Navigate to your VM in the Azure Portal.
  2. Go to "Networking" under Settings.
  3. Click "Add inbound port rule".
  4. Create rules for ports 5173 (TCP), 5001 (TCP), and ensure SSH (22/TCP) is allowed from your IP.

Server Firewall (ufw) Configuration:

sudo ufw allow 22/tcp
 sudo ufw allow 5173/tcp
sudo ufw allow 5001/tcp
sudo ufw enable
sudo ufw status

Important: Always ensure your SSH port (22) is accessible before enabling ufw to avoid locking yourself out of the server.

Step 1: Configure Z-Vault-Admin Frontend

Update the .env file in your Z-Vault-Admin project. You need to set the VITE_ZPAY_BACKEND_URL variable to point to your server's public IP address and the ZPAY backend port (5001).

# Z-Vault-Admin/.env example
VITE_APP_NAME="ZVault Admin"
VITE_ZPAY_BACKEND_URL="http://<YOUR_SERVER_IP>:5001"
# Add other environment variables as needed

Replace <YOUR_SERVER_IP> with the actual public IP address of your Azure VM.

Step 2: Prepare ZPAY Database Initialization Script

Before deploying the ZPAY backend, you need to customize the create-db.sql script. This script initializes the database and sets up the initial user and API key for administrative access.

Locate the create-db.sql file within your ZPAY backend project. You will need to modify the placeholder values for user_id and api_key. Choose a secure, unique API key.

-- ZPAY/db/create-db.sql (Example Snippet - actual content may vary)
-- ... other SQL setup ...

-- Ensure this section is present and correctly inserts your initial admin user and API key
INSERT INTO users (id, email, name, role) VALUES ('your_chosen_user_id', 'admin@example.com', 'Admin User', 'ADMIN');
INSERT INTO api_keys (key, user_id, status) VALUES ('your_secure_api_key_here', 'your_chosen_user_id', 'ACTIVE');

-- ... other SQL setup ...

Replace 'your_chosen_user_id' with a unique identifier for the admin user and 'your_secure_api_key_here' with a strong, randomly generated API key. This API key will be used by the Z-Vault-Admin frontend to communicate with the backend.

Security Note: Treat this API key like a password. It provides administrative access to your ZPAY instance.

Step 3: Build and Package Application (release.sh)

The release.sh script is responsible for building both the frontend (Z-Vault-Admin) and backend (ZPAY) applications and packaging them into a distributable format (e.g., a .zip file).

Navigate to the root directory where your release.sh script is located (this might be a top-level project directory containing both frontend and backend projects or within a specific deployment scripts folder). Execute the script:

./release.sh

This script should handle all necessary build steps (e.g., npm run build for both projects) and then create a compressed archive (e.g., release.zip) containing the build artifacts and necessary deployment files (like deploy.sh and Docker configurations if used).

Step 3.5: Transfer Release Package to Server

Once the release.zip (or similarly named archive) is created, transfer it to your Azure VM. Use scp or any SFTP client for this.

scp ./release.zip your_azure_username@<YOUR_SERVER_IP>:/path/to/deployment_directory

Replace your_azure_username with your SSH username for the VM, <YOUR_SERVER_IP> with the VM's public IP, and /path/to/deployment_directory with your desired location on the server (e.g., /srv/zvault or ~/zvault-deployment). Create this directory on the server if it doesn't exist.

Step 4: Deploy Application on Server (deploy.sh)

SSH into your Azure VM. Navigate to the directory where you uploaded release.zip. Unzip the archive and then execute the deploy.sh script.

ssh your_azure_username@<YOUR_SERVER_IP>
cd /path/to/deployment_directory
unzip release.zip
# The deploy script might need execute permissions
chmod +x deploy.sh
sudo ./deploy.sh

The deploy.sh script should handle tasks such as:

  • Setting up prerequisites on the server (e.g., Docker, Node.js, PM2, Caddy/Nginx if used).
  • Initializing the database using the modified create-db.sql.
  • Configuring and starting the ZPAY backend service (e.g., using Docker Compose or PM2).
  • Configuring and starting the Z-Vault-Admin frontend (e.g., serving static files via Caddy/Nginx or a simple Node.js server).
  • Setting up reverse proxies if used (e.g., Caddy or Nginx to handle SSL and proxy requests to ports 5001 and 5173).

Monitor the output of deploy.sh for any errors. Consult its contents or related documentation if issues arise.

Step 5: Final Frontend Configuration & Verification

After the deploy.sh script completes, your ZVault instance should be running. The primary frontend configuration (VITE_ZPAY_BACKEND_URL) was done in Step 1. However, you might need to perform final checks or configurations depending on your setup.

Access your Z-Vault-Admin dashboard by navigating to http://<YOUR_SERVER_IP>:5173 in your web browser. Test the login using the credentials related to the user_id you configured in create-db.sql (if your admin app has a login system beyond just API key usage) and the API key itself when prompted or in settings.

Verify that the dashboard can communicate with the backend (e.g., by fetching data or performing actions that require API calls). Check browser console for any errors related to API connectivity.

If you have set up a domain name and SSL (e.g., via Caddy or Nginx as part of deploy.sh), you should access the application via https://yourdomain.com.

Troubleshooting

If you encounter issues:

  • Check Service Logs: For PM2: pm2 logs. For Docker: docker logs <container_name>.
  • Firewall: Double-check Azure NSG rules and server ufw status.
  • Backend API: Use curl http://localhost:5001/health (or similar health check endpoint) on the server to see if the backend is running.
  • Frontend Build: Ensure the .env for the frontend was correctly updated with the server IP before building.
  • Database: Verify the database was initialized correctly and the ZPAY backend can connect to it.