> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nvisy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Configure and start using Nvisy on-premises

## Quick Start

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

<Steps>
  <Step title="Verify Requirements">
    Ensure your system meets the [requirements](/deployment/on-premise/requirements)
  </Step>

  <Step title="Install Nvisy">
    Follow the [installation guide](/deployment/on-premise/installation)
  </Step>

  <Step title="Configure Settings">
    Set up basic configuration
  </Step>

  <Step title="Start Services">
    Launch Nvisy services
  </Step>

  <Step title="Verify Installation">
    Test that everything is working
  </Step>
</Steps>

## Basic Configuration

### Environment Variables

Create a `.env` file with your configuration. The example below uses Docker
Compose service names — see [Connection hosts](#connection-hosts) for the
Kubernetes and systemd equivalents.

```bash theme={null}
# 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.

<Tabs>
  <Tab title="Docker Compose">
    Compose resolves service names on its own network:

    ```bash theme={null}
    NVISY_DB_URL=postgresql://nvisy:password@postgres:5432/nvisy
    NVISY_NATS_URL=nats://nats:4222
    ```
  </Tab>

  <Tab title="Kubernetes">
    Use the Service DNS name. Within the same namespace the short name works;
    across namespaces use the fully-qualified form:

    ```bash theme={null}
    NVISY_DB_URL=postgresql://nvisy:password@nvisy-postgres.nvisy.svc.cluster.local: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`.
  </Tab>

  <Tab title="Systemd">
    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:

    ```bash theme={null}
    NVISY_DB_URL=postgresql://nvisy:password@127.0.0.1:5432/nvisy
    NVISY_NATS_URL=nats://127.0.0.1:4222
    ```

    For dedicated hosts, use their addresses and ensure the firewall permits
    the connection.
  </Tab>
</Tabs>

<Warning>
  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.
</Warning>

<Warning>
  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](#enabling-tls-https) on
  the service or place it behind a TLS-terminating reverse proxy and keep the
  service itself on loopback.
</Warning>

### Configuration File

Alternatively, use `config.yaml`:

```yaml theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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](/deployment/cloud/authentication) for
the full lifecycle — the same endpoints apply to a self-hosted instance.

```bash theme={null}
export NVISY_API_TOKEN="..."
```

### Verify the Instance

```bash theme={null}
curl http://localhost:8080/health/
```

A healthy instance reports each component:

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

### Using cURL

```bash theme={null}
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:

<CodeGroup>
  ```typescript TypeScript theme={null}
  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();
  ```

  ```python Python theme={null}
  import os

  from nvisy import Client

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

  ```rust Rust theme={null}
  let client = Nvisy::builder()
      .with_api_key(&std::env::var("NVISY_API_TOKEN")?)
      .with_base_url("http://localhost:8080")
      .build()?;
  ```
</CodeGroup>

See the [Quickstart](/quickstart) for the full upload → analyze → review →
redact flow.

<Note>
  Self-hosting pairs well with an `ollama` [connection](/features/integrations)
  — inference then runs inside your infrastructure too, so no document content
  leaves your network.
</Note>

## Enabling TLS/HTTPS

For production, enable TLS:

### Generate Certificate

```bash theme={null}
# 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

```yaml theme={null}
server:
  tls:
    enabled: true
    cert_file: /etc/nvisy/certs/tls.crt
    key_file: /etc/nvisy/certs/tls.key
```

### Restart Services

```bash theme={null}
docker-compose restart
```

## Setting Up Monitoring

### Enable Metrics

Configure Prometheus metrics:

```yaml theme={null}
monitoring:
  metrics:
    enabled: true
    port: 9090
```

### Prometheus Configuration

```yaml theme={null}
# 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](/deployment/cloud/authentication) for the account and token
endpoints.

## Backup Configuration

Set up automated backups:

```bash theme={null}
# 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

```yaml theme={null}
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](/deployment/on-premise/requirements) 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

```yaml theme={null}
database:
  max_connections: 100
  idle_timeout: 300
```

### Enable GPU Acceleration

If you have an NVIDIA GPU:

```yaml theme={null}
ai:
  gpu_enabled: true
  gpu_memory_fraction: 0.8  # Use 80% of GPU memory
```

## Common Tasks

### View Logs

```bash theme={null}
# Docker Compose
docker-compose logs -f nvisy

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

# Systemd
journalctl -u nvisy -f
```

### Restart Services

```bash theme={null}
# Docker Compose
docker-compose restart

# Kubernetes
kubectl rollout restart deployment/nvisy -n nvisy

# Systemd
sudo systemctl restart nvisy
```

### Check Resource Usage

```bash theme={null}
# Docker Compose
docker stats

# Kubernetes
kubectl top pods -n nvisy

# System
htop
```

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore the API
  </Card>

  <Card title="TypeScript SDK" icon="js" href="/sdks/typescript/quickstart">
    Use the SDK
  </Card>

  <Card title="Configuration" icon="gear" href="/deployment/on-premise/installation">
    Advanced configuration
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/deployment/on-premise/installation">
    Common issues and solutions
  </Card>
</CardGroup>