Installation Guide

Quickstart & Installation Guide

Event Wrap Pro is packaged as a turnkey Docker container with an integrated PostgreSQL database and persistent file storage. Select your target deployment environment below for step-by-step setup instructions.

Deploy on a Fresh Linux Server (Ubuntu / Debian)

For any clean Linux VPS, cloud compute instance, or on-premises server.

Step 1: Install Docker Engine & Docker Compose

Terminal (Linux Shell)
# 1. Update package lists
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git ufw

# 2. Install official Docker Engine & Compose plugin
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 3. Add your current user to docker group (optional)
sudo usermod -aG docker $USER

# 4. Verify Docker is running
docker --version && docker compose version

Step 2: Clone Repository & Create Storage Directories

Terminal (Linux Shell)
# Create standard application directory
sudo mkdir -p /opt/eventwrappro
sudo chown -R $USER:$USER /opt/eventwrappro
cd /opt/eventwrappro

# Clone client application
git clone https://github.com/RBND/EventWrapPro.git .

# Create persistent storage directories
mkdir -p uploads/proofs uploads/artworks uploads/photos uploads/emails backups
chmod -R 775 uploads backups

Step 3: Create Environment Configuration (.env)

First, generate a secure 32-byte cryptographic secret for session encryption by running:

Terminal (Generate 32-byte Secret)
# Linux / macOS:
openssl rand -base64 32

# Or via Node.js (cross-platform):
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Then create your .env file in /opt/eventwrappro/.env, pasting your generated secret into both AUTH_SECRET and NEXTAUTH_SECRET:

/opt/eventwrappro/.env
NODE_ENV=production
PORT=3000

# Base URL (Replace with your actual server domain or IP)
NEXTAUTH_URL=http://YOUR_SERVER_IP_OR_DOMAIN:3000
NEXT_PUBLIC_APP_URL=http://YOUR_SERVER_IP_OR_DOMAIN:3000

# Session & JWT Secrets (Generate 32-byte strings)
AUTH_SECRET=paste_your_generated_32_byte_secret_here
NEXTAUTH_SECRET=paste_your_generated_32_byte_secret_here
JWT_SECRET=paste_your_generated_32_byte_secret_here

# PostgreSQL Database Credentials
POSTGRES_USER=postgres
POSTGRES_PASSWORD=YourStrongDatabasePassword123!
POSTGRES_DB=eventwrappro

# PostgreSQL Connection String (Connects to internal Docker network)
# CRITICAL: The password in this URI must EXACTLY MATCH the POSTGRES_PASSWORD set above!
DATABASE_URL=postgresql://postgres:YourStrongDatabasePassword123!@db:5432/eventwrappro?schema=public

# Commercial License Authority
LICENSE_SERVER_URL=https://eventwrappro.com
LICENSE_KEY=YOUR_COMMERCIAL_LICENSE_KEY

# Persistent uploads path in container
LOCAL_STORAGE_PATH=/app/uploads

Password & Secret Alignment

Database Password Matching: The password embedded in the DATABASE_URL URI (postgresql://postgres:PASSWORD@db:5432/...) must be identical to the password set in POSTGRES_PASSWORD. If these passwords differ, the application container will fail authentication when attempting to connect to PostgreSQL.

Session Security: Both AUTH_SECRET and NEXTAUTH_SECRET must be set to the same 32-byte random base64 string to protect encrypted auth cookies and JWTs from tampering.

Step 4: Launch the Containers

Terminal (Linux Shell)
# Build and start services in detached mode
docker compose up -d --build

# Confirm containers are running
docker compose ps

Next: Complete the First-Run Setup Wizard

Once your container starts, open your browser and navigate to http://YOUR_SERVER_IP:3000/setup.

  1. License & Backup Detection: Validates your commercial license key and scans /app/backups for existing .ewpbak snapshots for 1-click disaster recovery.
  2. Company Identity & Admin Account: Enter your shop name, primary origin, and create your root ADMIN account.
  3. Catalog Seed Mode: Choose DEMO (sample venues, vinyl catalog, and demo orders) or CLEAN (blank production slate).
  4. Outbound Email (SMTP): Optionally configure and live-test SMTP delivery before going live.
  5. Dual-Unlock Recovery Key: Save your Slot A recovery key (EWP-REC-XXXX-XXXX-XXXX-XXXX) in a password manager to unlock encrypted backups on any server.

Automatic Route Lock

Once submitted, the /setup route automatically locks to prevent unauthorized re-configuration, redirecting future visits to /login.