​

Installation

​

Full customer journey (from zero to usable)

1. Prepare host machine (Docker + Compose, networking, DNS)
2. Clone SafariDesk and create .env
3. Configure core settings (DB_*, REDIS_*, SUPERUSER_*, URLs)
4. Configure enterprise licensing values provided by SafariDesk
5. Start the stack with Docker Compose
6. Validate services, run first login, and confirm license status
7. Configure email, optional AI, backups, and monitoring

​

Preflight (do this first)

• Install Docker and Docker Compose on your host
• Make sure you run commands from the Core/ directory (the Docker Compose file lives there)
• Confirm you have 4+ GB RAM available

​

Operating system options

• Production recommendation: Linux host (Ubuntu 22.04+ recommended)
• Also possible: Debian/RHEL-family Linux, macOS, and Windows with Docker Desktop

​

Ubuntu / Debian (example)

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
# Install Docker Engine and Docker Compose plugin per Docker docs
docker --version
docker compose version

​

RHEL / Rocky / AlmaLinux (example)

sudo dnf install -y dnf-plugins-core
# Install Docker Engine and Docker Compose plugin per Docker docs
docker --version
docker compose version

​

macOS (example)

brew install --cask docker
open /Applications/Docker.app
docker --version
docker compose version

​

Windows (example)

winget install Docker.DockerDesktop
docker --version
docker compose version

​

1. Clone the repository

git clone https://github.com/SafariDesk-OS/Core.git
cd Core

git clone https://github.com/SafariDesk-OS/Core.git
Set-Location Core

​

2. Create and edit the environment file

cp .env.example .env
# Use your favorite editor to open Core/.env and set values

Copy-Item .env.example .env
# Use your favorite editor to open Core/.env and set values

• SECRET_KEY — a random Django secret
• DB_PASSWORD — Postgres password used by the db container
• SUPERUSER_USERNAME, SUPERUSER_PASSWORD, SUPERUSER_EMAIL
• SMTP values (if you want email functionality)
• Enterprise license values from SafariDesk (see Configuration)

​

3. Start the stack

docker compose up -d --build

​

4. Verify the deployment

docker compose ps
docker compose logs -f api

docker compose exec api python manage.py migrate
docker compose exec api python manage.py collectstatic --noinput

​

5. Activate and verify enterprise licensing (updated UI)

1. Sign in as the admin user (created from SUPERUSER_* in .env).
2. Open your Profile page: http://<frontend-host>/profile (or click the Profile link in the header).
3. Select the License tab (next to Security). This page shows current license Status, Edition, Features, and Last validated.
4. Paste the enterprise license key into the License Key field and click Activate.
   • The frontend posts to POST /api/v1/license/activate/ and the backend validates the key with the license-proxy (configured via LICENSE_PROXY_URL in Core/.env).
   • Activation requires a staff/admin account and a valid JWT access token; the frontend includes the token automatically when logged-in.
5. On success you will see license metadata (customer, edition, features) and enterprise features will be unlocked.

• Admin-only: only staff users may activate or revalidate a license. Non-admin requests will receive an authorization error.
• Offline handling: if the API cannot reach the license-proxy the UI will display cached status and an “offline validation” notice; features remain available until revalidation fails.
• Security: license payloads are HMAC-signed by the proxy; the backend verifies signatures and stores license data encrypted when LICENSE_ENCRYPTION_KEY is set.

• Confirm the frontend is pointing to the running API: check Core/.env VITE_API_URL (should be http://localhost:9100/api/v1 for local setups). Rebuild the frontend if you change it.
• From the admin browser session: open DevTools → Network, click Activate, and verify the POST /license/activate/ request returns HTTP 200 and JSON with license details.
• If you see CORS errors in the browser console (e.g. “No ‘Access-Control-Allow-Origin’ header”), add your frontend origin to CORS_ALLOWED_ORIGINS in Core/backend/RNSafarideskBack/settings/base.py, then restart the API.
• If activation fails with 4xx, capture the response JSON (it contains a helpful detail field). If the API returns 500, tail the API logs:

docker compose -f Core/docker-compose.yml logs -f api --tail 200

# Check current status
curl -v http://localhost:9100/api/v1/license/status/

# Activate (single-line PowerShell example; replace <TOKEN> and <KEY>)
curl -v -X POST http://localhost:9100/api/v1/license/activate/ -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" -d '{"license_key":"<KEY>"}'

​

Quick recovery tips

• If the API is failing, docker compose logs api shows the error
• If Postgres is not ready, wait and retry migrate
• If a container fails to build, check the build output and rerun docker compose up -d --build