Deployment & Operations Guide

Jozie AI is a platform for building, cleaning, and evaluating training data, then fine-tuning and serving domain-specific AI models — for one team, department, or the whole company, run on hardware you control.

It has three moving parts, all of which run on infrastructure you own:

• The application — a web app (FastAPI backend + React frontend) with organizations, projects, role-based access, and an audit log.
• The data layer — PostgreSQL (with the pgvector extension) and Redis, both standard, well-understood infrastructure your team likely already runs elsewhere.
• The model layer — Ollama for local LLM inference, and an optional on-device fine-tuning pipeline (Apple Silicon only — see System requirements).

A single logical instance is one host (or one VM) running every service below. There is no multi-node clustering in this version — see Known limitations.

flowchart TB
  Browser["Employee browser"]

  subgraph Host["Self-hosted instance — one server or Mac"]
    Caddy["Reverse proxy (Caddy)\nTLS termination"]
    FE["Frontend\nstatic build"]
    API["Backend\nFastAPI"]
    Worker["Workers\nCelery"]
    PG[("PostgreSQL\n+ pgvector")]
    Redis[("Redis\nqueue + live updates")]
    Ollama["Ollama\nlocal LLM inference"]
    MLX["Fine-Tuning\nMLX — Apple Silicon only"]
  end

  subgraph External["Outbound only, on demand — no company data sent"]
    HF["Hugging Face\nbase model weights"]
    Reg["Ollama registry\nmodel weights"]
  end

  Browser -- HTTPS --> Caddy
  Caddy --> FE
  Caddy -- "/api/*" --> API
  API --> PG
  API --> Redis
  API --> Ollama
  Worker --> PG
  Worker --> Redis
  Worker --> Ollama
  Worker --> MLX
  MLX --> Ollama
  Ollama -. pulls weights .-> Reg
  MLX -. downloads base model .-> HF
        

Components

Sized by usage tier. All tiers assume the single-node architecture above.

Only the reverse proxy should be reachable from outside the host. Everything else should be bound to localhost or an internal network segment.

Outbound: HTTPS to ollama.com and huggingface.co, only when an admin explicitly pulls a new model or starts a fine-tuning job that needs a base model not yet cached. Nothing calls out on a schedule, and no request carries uploaded documents, dataset content, or conversation text.

Everything the product touches is written to local disk, under paths you control and back up.

Confirm each of these before exposing the instance to real users.

• Set ENVIRONMENT=production and a real JWT_SECRET (openssl rand -hex 32)The app refuses to start in production mode with the default secret — this is enforced, not just documented.
• Confirm /docs (the API reference) is disabledDisabled by default outside local/dev mode.
• Issue a real TLS certificate for the reverse proxyThe default local setup uses Caddy's self-signed local CA, which is fine for a single machine but should be replaced with your internal CA or a public cert for shared access.
• Confirm Postgres, Redis, Ollama, and the backend port are not reachable from outside the hostOnly the reverse proxy's port should be exposed — see Network & ports.
• Assign roles deliberately: owner > admin > editor > viewerOnly owner/admin can manage users and API keys; keep that group small.
• Rotate or scope API keys per integration, not sharedAPI keys are hashed at rest and revocable individually — treat each integration as its own key.
• Confirm backups are scheduled and a restore has been testedSee Backup & recovery.
• Review the audit log retention against your compliance requirementsEvery mutating action (create/edit/delete/export) is recorded with actor, action, and timestamp.

Logical backups of the database; file-level backup for everything else.

To restore: stop the backend and workers, run the restore script against the target database, then restart. Test this procedure before you need it for real.

1. Back up first. Run a manual backup even if a nightly one ran recently.
2. Announce a maintenance window. The app is unavailable while services restart (single-node, no rolling upgrade in this version).
3. Stop the backend and worker processes. Leave Postgres, Redis, and Ollama running.
4. Deploy the new backend and frontend code. Rebuild the frontend if it changed.
5. Apply database migrations before starting the new backend.
6. Start the backend and worker processes and confirm the Dashboard shows Ollama and Database as reachable.
7. Smoke-test the pipeline that matters most to your users (e.g. upload a document, or run one conversation).
8. Roll back by restoring the previous backup and redeploying the previous code version if step 7 fails.

What to watch day to day, and where to look when something's wrong.

Stated plainly, so your evaluation is based on what this actually does today — not on smoothed-over marketing language.

What's covered, and what stays your team's responsibility in a self-hosted model.