On-Premises Deployment

Deploy Nvisy within your own infrastructure for complete control over your data and security policies. Suited to organizations with strict data-residency needs.

Overview

On-premises deployment gives you:

Complete data sovereignty - Documents never leave your network
Full control - Customize security, networking, and infrastructure
Air-gap support - Deploy in isolated environments
Custom policies - Enforce your own data-handling rules

System Requirements

Minimum Requirements

Component	Requirement
OS	Ubuntu 20.04+, RHEL 8+, or compatible Linux
CPU	8 cores (x86_64)
RAM	16 GB
Storage	100 GB SSD
Network	1 Gbps
Container Runtime	Docker 20.10+ or Kubernetes 1.21+

Recommended for Production

Component	Requirement
CPU	16+ cores with AVX2 support
RAM	32 GB+
Storage	500 GB+ NVMe SSD
GPU	NVIDIA GPU with 8GB+ VRAM (optional, for faster processing)
Network	10 Gbps with load balancer
HA Setup	3+ nodes for high availability

Installation Methods

Docker Compose
Kubernetes
Binary

Docker Compose Installation

Quick setup for development and small deployments:

# Download a versioned compose file and verify it before use.
# Replace 1.2.3 with the release you intend to run.
NVISY_VERSION=1.2.3
curl -fsSLO https://get.nvisy.com/${NVISY_VERSION}/docker-compose.yml
curl -fsSLO https://get.nvisy.com/${NVISY_VERSION}/docker-compose.yml.sha256
sha256sum -c docker-compose.yml.sha256

# Configure environment variables
cat > .env << EOF
[email protected]
NVISY_STORAGE_PATH=/var/lib/nvisy
EOF

# Start Nvisy
docker-compose up -d

# Verify installation
curl http://localhost:8080/health

Nvisy is open-source and needs no license key. Create an API token from your account settings once the instance is up — see Authentication.

Kubernetes Installation

Production-ready deployment with Helm:

# Add Nvisy Helm repository
helm repo add nvisy https://charts.nvisy.com
helm repo update

# Create namespace
kubectl create namespace nvisy

# Install Nvisy — pin the chart version and the image it deploys
helm install nvisy nvisy/nvisy \
  --namespace nvisy \
  --version 1.2.3 \
  --set image.tag=1.2.3 \
  --set ingress.enabled=true \
  --set ingress.host=nvisy.yourcompany.com \
  --set replicaCount=3

# Verify deployment
kubectl get pods -n nvisy

Configuration options in values.yaml:

replicaCount: 3

image:
  repository: nvisy/redaction-service
  # Pin a released tag, or a digest for a fully immutable reference.
  tag: "1.2.3"
  # digest: "sha256:<image-digest>"

resources:
  requests:
    cpu: 4
    memory: 8Gi
  limits:
    cpu: 8
    memory: 16Gi

persistence:
  enabled: true
  size: 100Gi
  storageClass: fast-ssd

postgresql:
  enabled: true
  auth:
    database: nvisy
    username: nvisy

nats:
  enabled: true

Binary Installation

Direct installation on Linux servers:

# Download a versioned binary and verify its checksum before running it.
NVISY_VERSION=1.2.3
curl -fsSL https://get.nvisy.com/${NVISY_VERSION}/nvisy-linux-amd64 -o nvisy
curl -fsSL https://get.nvisy.com/${NVISY_VERSION}/nvisy-linux-amd64.sha256 \
  -o nvisy.sha256
sha256sum -c nvisy.sha256
chmod +x nvisy

# Create configuration
cat > /etc/nvisy/config.yaml << EOF
server:
  port: 8080
  # Bind to loopback and let a TLS-terminating proxy handle public traffic.
  host: 127.0.0.1
storage:
  type: local
  path: /var/lib/nvisy/data
database:
  url: postgresql://nvisy:password@localhost:5432/nvisy
EOF

# Install as systemd service
sudo ./nvisy install

# Start service
sudo systemctl start nvisy
sudo systemctl enable nvisy

# Check status
sudo systemctl status nvisy

Configuration

Environment Variables

# Core Configuration
NVISY_SERVER_PORT=8080
NVISY_LOG_LEVEL=info

# Storage Configuration
NVISY_STORAGE_TYPE=s3  # local, s3, azure, gcs
NVISY_STORAGE_PATH=/var/lib/nvisy
NVISY_S3_BUCKET=nvisy-documents
NVISY_S3_REGION=us-east-1

# Database Configuration
NVISY_DB_URL=postgresql://user:pass@localhost:5432/nvisy

# NATS Configuration (for job messaging)
NVISY_NATS_URL=nats://localhost:4222

# Security Configuration
NVISY_API_KEY_REQUIRED=true
NVISY_TLS_ENABLED=true
NVISY_TLS_CERT=/etc/nvisy/certs/tls.crt
NVISY_TLS_KEY=/etc/nvisy/certs/tls.key

# AI Model Configuration
NVISY_MODEL_PATH=/opt/nvisy/models
NVISY_GPU_ENABLED=true
NVISY_MAX_CONCURRENT_JOBS=10

config.yaml

server:
  port: 8080
  # Binding to all interfaces is only safe because TLS is enabled below.
  # Without TLS, bind to 127.0.0.1 and front the service with a TLS proxy.
  host: 0.0.0.0
  tls:
    enabled: true
    cert_file: /etc/nvisy/certs/tls.crt
    key_file: /etc/nvisy/certs/tls.key

storage:
  type: s3
  s3:
    bucket: nvisy-documents
    region: us-east-1
    endpoint: https://s3.amazonaws.com

database:
  # Docker Compose service name — use the Service DNS name on Kubernetes, or
  # an explicit host/port under systemd.
  url: postgresql://nvisy:password@postgres:5432/nvisy
  max_connections: 100
  ssl_mode: require

ai:
  model_path: /opt/nvisy/models
  gpu_enabled: true
  max_concurrent: 10
  detection_types:
    - pii
    - phi
    - financial

security:
  api_keys:
    required: true
    header_name: Authorization
  cors:
    enabled: true
    origins:
      - https://app.yourcompany.com
  rate_limiting:
    enabled: true
    requests_per_second: 100

monitoring:
  metrics:
    enabled: true
    port: 9090
  tracing:
    enabled: true
    endpoint: http://jaeger:14268/api/traces

Networking

Firewall Rules

Required ports:

Port	Protocol	Purpose
443	TCP	HTTPS, when a reverse proxy terminates TLS (the NGINX example below)
8080	TCP	HTTP API on the service itself — keep internal, never public
8443	TCP	HTTPS API, only when the service terminates TLS directly without a proxy
9090	TCP	Metrics endpoint
5432	TCP	PostgreSQL (if external)
4222	TCP	NATS (if external)

Open exactly one public HTTPS port: 443 when a reverse proxy fronts the service, or 8443 when the service terminates TLS itself. Port 8080 carries cleartext and should only be reachable from the proxy or the local host.

Load Balancer Configuration

Example NGINX configuration:

upstream nvisy_backend {
    least_conn;
    server nvisy-1:8080 max_fails=3 fail_timeout=30s;
    server nvisy-2:8080 max_fails=3 fail_timeout=30s;
    server nvisy-3:8080 max_fails=3 fail_timeout=30s;
}

server {
    listen 443 ssl http2;
    server_name nvisy.yourcompany.com;

    ssl_certificate /etc/nginx/certs/tls.crt;
    ssl_certificate_key /etc/nginx/certs/tls.key;

    client_max_body_size 100M;

    location / {
        proxy_pass http://nvisy_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Timeouts for long-running redaction jobs
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
    }
}

High Availability Setup

Architecture

                    Load Balancer
                         │
        ┌────────────────┼────────────────┐
        │                │                │
    Nvisy-1          Nvisy-2          Nvisy-3
        │                │                │
        └────────────────┼────────────────┘
                         │
            ┌────────────┴────────────┐
            │                         │
    PostgreSQL (Primary/Replica)   NATS (Cluster)

Database Replication

PostgreSQL with streaming replication:

# Primary node
postgresql:
  replication:
    enabled: true
    user: replicator
    password: secure_password
    
# Replica nodes
postgresql:
  replication:
    enabled: true
    mode: slave
    primary_host: postgres-primary
    primary_port: 5432

Backup & Recovery

Automated Backups

# PostgreSQL backup
pg_dump nvisy | gzip > /backups/nvisy-$(date +%Y%m%d).sql.gz

# Storage backup (if using local storage)
tar -czf /backups/nvisy-storage-$(date +%Y%m%d).tar.gz /var/lib/nvisy

# Kubernetes backup with Velero
velero backup create nvisy-backup --include-namespaces nvisy

Backup Schedule

Recommended schedule:

Database: Daily full backup, hourly incrementals
Storage: Daily backup with 30-day retention
Configuration: Version-controlled in Git
Disaster Recovery: Test recovery quarterly

Monitoring

Metrics

Nvisy exposes Prometheus metrics at /metrics:

# Prometheus scrape config
scrape_configs:
  - job_name: 'nvisy'
    static_configs:
      - targets: ['nvisy:9090']

Key metrics:

nvisy_requests_total - Total API requests
nvisy_processing_duration_seconds - Processing time
nvisy_detections_total - Total detections
nvisy_errors_total - Error count

Health Checks

curl http://localhost:8080/health/

Response:

{
  "status": "healthy",
  "checks": [
    { "name": "postgres", "status": "healthy" },
    { "name": "nats", "status": "healthy" },
    { "name": "webhook", "status": "healthy" }
  ],
  "timestamp": "2025-01-01T00:00:00Z"
}

checks is an array with one entry per dependency. The top-level status is healthy only when every check reports healthy.

Security Hardening

TLS Configuration

Generate self-signed certificate (development):

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/nvisy/certs/tls.key \
  -out /etc/nvisy/certs/tls.crt

API Key Management

API tokens are managed through the API (or the account settings UI), not a local CLI:

GET    /api-tokens/
POST   /api-tokens/
DELETE /api-tokens/{tokenId}/

The token value is returned only when it is created. Store it in a secret manager and rotate it by creating the replacement before revoking the old one — see Authentication.

Network Isolation

Run in isolated network:

# Docker Compose network isolation
networks:
  nvisy_internal:
    driver: bridge
    internal: true
  nvisy_external:
    driver: bridge

services:
  nvisy:
    networks:
      - nvisy_external
      - nvisy_internal
  
  postgres:
    networks:
      - nvisy_internal  # Not exposed externally

Troubleshooting

Common Issues

Service won't start

Check logs:

docker logs nvisy
# or
journalctl -u nvisy -f

Common causes:

Database connection failure
Port already in use
Insufficient permissions

Slow processing

Check resource usage:

docker stats nvisy
# or
kubectl top pods -n nvisy

Solutions:

Increase CPU/memory allocation
Enable GPU acceleration
Increase concurrent job limit
Check network latency to storage

Database connection errors

Verify database:

psql -h localhost -U nvisy -d nvisy -c "SELECT 1"

Check:

Database URL is correct
Credentials are valid
Database is accessible from Nvisy
SSL mode matches database config

Upgrading

Docker Compose Upgrade

# Backup database
docker-compose exec postgres pg_dump nvisy > backup.sql

# Pull new images
docker-compose pull

# Restart services
docker-compose up -d

# Verify upgrade
curl http://localhost:8080/version

Kubernetes Upgrade

# Backup
velero backup create pre-upgrade-backup --include-namespaces nvisy

# Upgrade with Helm
helm upgrade nvisy nvisy/nvisy \
  --namespace nvisy \
  --version 2.0.0

# Monitor rollout
kubectl rollout status deployment/nvisy -n nvisy

Support

Enterprise Support

Priority support with SLA for on-premises customers

Documentation

Complete deployment guides and API reference

Email Support

[email protected]

GitHub Issues

Report issues or request features

Next Steps

Configuration Reference

View all configuration options

API Reference

Integrate with your applications

​Overview

​System Requirements

​Minimum Requirements

​Recommended for Production

​Installation Methods

​Docker Compose Installation

​Kubernetes Installation

​Binary Installation

​Configuration

​Environment Variables

​config.yaml

​Networking

​Firewall Rules

​Load Balancer Configuration

​High Availability Setup

​Architecture

​Database Replication

​Backup & Recovery

​Automated Backups

​Backup Schedule

​Monitoring

​Metrics

​Health Checks

​Security Hardening

​TLS Configuration

​API Key Management

​Network Isolation

​Troubleshooting

​Common Issues

​Upgrading

​Docker Compose Upgrade

​Kubernetes Upgrade

​Support

Enterprise Support

Documentation

Email Support

GitHub Issues

​Next Steps

Configuration Reference

API Reference

Overview

System Requirements

Minimum Requirements

Recommended for Production

Installation Methods

Docker Compose Installation

Kubernetes Installation

Binary Installation

Configuration

Environment Variables

config.yaml

Networking

Firewall Rules

Load Balancer Configuration

High Availability Setup

Architecture

Database Replication

Backup & Recovery

Automated Backups

Backup Schedule

Monitoring

Metrics

Health Checks

Security Hardening

TLS Configuration

API Key Management

Network Isolation

Troubleshooting

Common Issues

Upgrading

Docker Compose Upgrade

Kubernetes Upgrade

Support

Next Steps