Getting Started

Quick Start

Bring up a working on-premises instance in five steps:

Verify Requirements

Ensure your system meets the requirements

Install Nvisy

Follow the installation guide

Configure Settings

Set up basic configuration

Start Services

Launch Nvisy services

Verify Installation

Test that everything is working

Basic Configuration

Environment Variables

Create a .env file with your configuration. The example below uses Docker Compose service names — see Connection hosts for the Kubernetes and systemd equivalents.

# Server — bind to loopback until TLS terminates in front of the service
NVISY_SERVER_HOST=127.0.0.1
NVISY_SERVER_PORT=8080
NVISY_LOG_LEVEL=info

# Database — `postgres` resolves via Docker Compose service discovery
NVISY_DB_URL=postgresql://nvisy:password@postgres:5432/nvisy

# Messaging — `nats` resolves via Docker Compose service discovery
NVISY_NATS_URL=nats://nats:4222

# Storage
NVISY_STORAGE_TYPE=local
NVISY_STORAGE_PATH=/var/lib/nvisy/data

# Security
NVISY_TLS_ENABLED=false  # Only valid while the service is bound to loopback

Connection hosts

The postgres and nats hostnames above are Docker Compose service names. They do not resolve under other deployment methods — use the form that matches how you installed Nvisy.

Docker Compose
Kubernetes
Systemd

Compose resolves service names on its own network:

NVISY_DB_URL=postgresql://nvisy:password@postgres:5432/nvisy
NVISY_NATS_URL=nats://nats:4222

Use the Service DNS name. Within the same namespace the short name works; across namespaces use the fully-qualified form:

NVISY_DB_URL=postgresql://nvisy:[email protected]:5432/nvisy
NVISY_NATS_URL=nats://nvisy-nats.nvisy.svc.cluster.local:4222

Substitute the Service names your chart actually creates — check with kubectl get svc -n nvisy.

There is no service discovery, so point at the host and port each service listens on. When they run on the same machine, that is loopback:

NVISY_DB_URL=postgresql://nvisy:[email protected]:5432/nvisy
NVISY_NATS_URL=nats://127.0.0.1:4222

For dedicated hosts, use their addresses and ensure the firewall permits the connection.

Replace password with a real secret in every deployment method. Supply it through a secret manager or an environment file with restricted permissions rather than committing it.

Do not combine NVISY_SERVER_HOST=0.0.0.0 with NVISY_TLS_ENABLED=false. That serves API tokens and document content in cleartext on every interface. Before widening the bind address, either enable TLS on the service or place it behind a TLS-terminating reverse proxy and keep the service itself on loopback.

Configuration File

Alternatively, use config.yaml:

server:
  # Bind to loopback unless TLS is enabled or a TLS proxy sits in front.
  host: 127.0.0.1
  port: 8080

# Hostnames below are Docker Compose service names — see
# "Connection hosts" above for Kubernetes and systemd equivalents.
database:
  url: postgresql://nvisy:password@postgres:5432/nvisy

nats:
  url: nats://nats:4222

storage:
  type: local
  path: /var/lib/nvisy/data

ai:
  gpu_enabled: false
  max_concurrent_jobs: 10

Starting Services

Docker Compose

Start all services:

# Start in foreground
docker-compose up

# Start in background
docker-compose up -d

# View logs
docker-compose logs -f

# Check status
docker-compose ps

Kubernetes

Deploy with Helm:

# Install — always pin the chart version, and pin the image it deploys
helm install nvisy nvisy/nvisy \
  --namespace nvisy \
  --create-namespace \
  --version 1.2.3 \
  --set image.tag=1.2.3

# Check status
kubectl get pods -n nvisy

# Confirm the chart and image versions that were actually deployed
helm list -n nvisy

# View logs
kubectl logs -f -n nvisy -l app=nvisy

Systemd

Start the service:

# Start service
sudo systemctl start nvisy

# Enable on boot
sudo systemctl enable nvisy

# Check status
sudo systemctl status nvisy

# View logs
sudo journalctl -u nvisy -f

First Redaction

Create an API Token

Tokens are created in your account settings under API Tokens, or through POST /api-tokens/. See Authentication for the full lifecycle — the same endpoints apply to a self-hosted instance.

export NVISY_API_TOKEN="..."

Verify the Instance

curl http://localhost:8080/health/

A healthy instance reports each component:

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

Using cURL

curl http://localhost:8080/workspaces/ \
  -H "Authorization: Bearer $NVISY_API_TOKEN"

Using an SDK

Point the client’s base URL at your instance — everything else is identical to cloud:

import { Nvisy } from "@nvisy/sdk";

const client = new Nvisy({
  apiToken: process.env.NVISY_API_TOKEN!,
  baseUrl: "http://localhost:8080",
});

const workspaces = await client.workspaces.listWorkspaces();

import os

from nvisy import Client

client = Client({
    "api_key": os.environ["NVISY_API_TOKEN"],
    "base_url": "http://localhost:8080",
})

let client = Nvisy::builder()
    .with_api_key(&std::env::var("NVISY_API_TOKEN")?)
    .with_base_url("http://localhost:8080")
    .build()?;

See the Quickstart for the full upload → analyze → review → redact flow.

Self-hosting pairs well with an ollama connection — inference then runs inside your infrastructure too, so no document content leaves your network.

Enabling TLS/HTTPS

For production, enable TLS:

Generate Certificate

# 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

# Or use Let's Encrypt (production)
certbot certonly --standalone -d nvisy.yourdomain.com

Update Configuration

server:
  tls:
    enabled: true
    cert_file: /etc/nvisy/certs/tls.crt
    key_file: /etc/nvisy/certs/tls.key

Restart Services

docker-compose restart

Setting Up Monitoring

Enable Metrics

Configure Prometheus metrics:

monitoring:
  metrics:
    enabled: true
    port: 9090

Prometheus Configuration

# prometheus.yml
scrape_configs:
  - job_name: 'nvisy'
    static_configs:
      - targets: ['nvisy:9090']

Grafana Dashboard

Import the Nvisy dashboard (ID: coming soon) or create custom dashboards using metrics:

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

User Management

Accounts are created through POST /auth/signup/, and access is granted per workspace through memberships and invites rather than global roles. See Authentication for the account and token endpoints.

Backup Configuration

Set up automated backups:

# Create backup script
cat > /usr/local/bin/nvisy-backup.sh << 'EOF'
#!/bin/bash
BACKUP_DIR=/backups/nvisy
DATE=$(date +%Y%m%d-%H%M%S)

# Backup database
docker-compose exec -T postgres pg_dump nvisy | \
  gzip > ${BACKUP_DIR}/db-${DATE}.sql.gz

# Backup storage
tar -czf ${BACKUP_DIR}/storage-${DATE}.tar.gz \
  /var/lib/nvisy/data

# Cleanup old backups (keep 30 days)
find ${BACKUP_DIR} -mtime +30 -delete
EOF

chmod +x /usr/local/bin/nvisy-backup.sh

# Add to crontab (daily at 2 AM)
echo "0 2 * * * /usr/local/bin/nvisy-backup.sh" | crontab -

Performance Tuning

Optimize Worker Count

ai:
  max_concurrent_jobs: 20  # Adjust based on CPU cores

A conservative starting point is (CPU cores - 2) / 2 — for a 16-core host, about 7 concurrent jobs. This is a floor for CPU-bound analysis, not a capacity figure: the capacity planning table sizes hardware for a target job count and assumes jobs spend much of their time waiting on I/O. Start low, measure with your own documents, and raise the limit only while latency stays acceptable.

Database Connection Pool

database:
  max_connections: 100
  idle_timeout: 300

Enable GPU Acceleration

If you have an NVIDIA GPU:

ai:
  gpu_enabled: true
  gpu_memory_fraction: 0.8  # Use 80% of GPU memory

Common Tasks

View Logs

# Docker Compose
docker-compose logs -f nvisy

# Kubernetes
kubectl logs -f -n nvisy -l app=nvisy

# Systemd
journalctl -u nvisy -f

Restart Services

# Docker Compose
docker-compose restart

# Kubernetes
kubectl rollout restart deployment/nvisy -n nvisy

# Systemd
sudo systemctl restart nvisy

Check Resource Usage

# Docker Compose
docker stats

# Kubernetes
kubectl top pods -n nvisy

# System
htop

Next Steps

API Reference

Explore the API

TypeScript SDK

Use the SDK

Configuration

Advanced configuration

Troubleshooting

Common issues and solutions

​Quick Start

​Basic Configuration

​Environment Variables

​Connection hosts

​Configuration File

​Starting Services

​Docker Compose

​Kubernetes

​Systemd

​First Redaction

​Create an API Token

​Verify the Instance

​Using cURL

​Using an SDK

​Enabling TLS/HTTPS

​Generate Certificate

​Update Configuration

​Restart Services

​Setting Up Monitoring

​Enable Metrics

​Prometheus Configuration

​Grafana Dashboard

​User Management

​Backup Configuration

​Performance Tuning

​Optimize Worker Count

​Database Connection Pool

​Enable GPU Acceleration

​Common Tasks

​View Logs

​Restart Services

​Check Resource Usage

​Next Steps

API Reference

TypeScript SDK

Configuration

Troubleshooting

Quick Start

Basic Configuration

Environment Variables

Connection hosts

Configuration File

Starting Services

Docker Compose

Kubernetes

Systemd

First Redaction

Create an API Token

Verify the Instance

Using cURL

Using an SDK

Enabling TLS/HTTPS

Generate Certificate

Update Configuration

Restart Services

Setting Up Monitoring

Enable Metrics

Prometheus Configuration

Grafana Dashboard

User Management

Backup Configuration

Performance Tuning

Optimize Worker Count

Database Connection Pool

Enable GPU Acceleration

Common Tasks

View Logs

Restart Services

Check Resource Usage

Next Steps