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

# Architecture

> Self-hosted SafariDesk architecture, infrastructure requirements, storage and licensing

# SafariDesk Self-Hosted Architecture

## Overview

SafariDesk supports two deployment models:

### 1. Cloud Version

* Multi-tenant SaaS platform
* Hosted and managed by SafariDesk
* Billing handled internally via Stripe
* Shared infrastructure across organizations

### 2. Self-Hosted Enterprise Version

* Single-tenant deployment
* Installed on customer-owned infrastructure
* Enterprise license required
* License validation performed through SafariDesk License Proxy
* Multi-tenancy disabled

***

# Self-Hosted Deployment Model

Each self-hosted deployment represents a single organization.

One deployment contains:

* One frontend instance
* One backend API instance
* One PostgreSQL database
* One Redis instance
* One Nginx reverse proxy
* One uploads storage volume

No tenant switching or multi-workspace isolation is required inside the deployment.

***

# Infrastructure Requirements

Minimum requirements:

* Linux host with Docker and Docker Compose (Ubuntu 22.04+ recommended)
* Docker
* Docker Compose Plugin
* 4 GB RAM minimum
* 20 GB SSD storage
* Ports 80 and 443 available

Recommended:

* 8 GB RAM
* 4 CPU cores
* Domain with SSL

Other supported host options for non-production or pilot deployments:

* macOS with Docker Desktop
* Windows with Docker Desktop

For production reliability and performance, Linux is strongly recommended.

***

# Deployment Architecture

Internet
↓
Nginx Reverse Proxy
├── Frontend
├── Backend API
└── Uploads

Backend Services
├── PostgreSQL
├── Redis
└── License Validation

***

# Upload Storage

Uploads are stored using a shared Docker volume.

Backend writes uploads to:

* `/srv/uploads`

Nginx serves uploads from:

* `/api/uploads/*`

Uploads must persist across container restarts and updates. Use Docker volumes or an external storage mount to ensure persistence.

***

# Licensing Requirements

Self-hosted enterprise deployments require:

* SafariDesk license key
* Stable instance ID
* License proxy connectivity

License validation flow:

1. Customer enters license key
2. SafariDesk calls license proxy
3. License proxy validates against Keygen
4. Enterprise features enabled based on entitlements

***

# Enterprise Features

Feature access is controlled through license entitlements. Supported entitlement codes:

* `advanced_reports`
* `sla_automation`
* `ai_assistant`
* `white_label`
* `custom_domains`

The self-hosted edition must not enable:

* `multi_tenancy`

Even if returned by Keygen, the proxy strips this entitlement.

***

# License Validation Endpoint

POST `/v1/licenses/validate`

Headers:
Authorization: Bearer `LICENSE_KEY`

Request body:

* `instance_id`
* `deployment_type=self_hosted`
* `edition=enterprise`
* `version`
* `hostname`

SafariDesk verifies signed responses using the `LICENSE_RESPONSE_SIGNING_SECRET`.

## Example: validate a license (curl)

```bash theme={null}
curl -X POST https://api.yourdomain.com/v1/licenses/validate \
	-H "Authorization: Bearer YOUR_LICENSE_KEY" \
	-H "Content-Type: application/json" \
	-d '{
		"instance_id": "your-instance-id",
		"deployment_type": "self_hosted",
		"edition": "enterprise",
		"version": "1.2.3",
		"hostname": "helpdesk.yourdomain.com"
	}'
```

## Quick verification commands (run on the host in `Core/`)

```bash theme={null}
# show running containers
docker compose ps

# view recent API logs
docker compose logs --tail 200 api

# run migrations if needed
docker compose exec api python manage.py migrate
```