diff --git a/SUMMARY.md b/SUMMARY.md index 3efc339..065d7c0 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -84,6 +84,16 @@ * [How to use Version History?](help-desk/how-to-use-version-history.md) * [๐ŸŸ How can I get free credits?](help-desk/how-can-i-get-free-credits.md) +## ๐Ÿ–ฅ๏ธ Hosting Gooey.AI Server + +* [What is Gooey Server?](hosting-gooey-server/README.md) +* [Installation Guide](hosting-gooey-server/installation/README.md) + * [Quickstart with Docker](hosting-gooey-server/installation/quickstart-with-docker.md) + * [Manual Installation](hosting-gooey-server/installation/manual-installation.md) +* [Adding Local AI Models](hosting-gooey-server/adding-local-ai-models.md) +* [Configuration Reference](hosting-gooey-server/configuration.md) +* [Platform Independence](hosting-gooey-server/platform-independence.md) + ## ๐Ÿ˜‡ CONTRIBUTING * [Contributing](contributing/contributing.md) diff --git a/hosting-gooey-server/README.md b/hosting-gooey-server/README.md new file mode 100644 index 0000000..ce96395 --- /dev/null +++ b/hosting-gooey-server/README.md @@ -0,0 +1,110 @@ +--- +icon: server +description: >- + What Gooey Server is, how the pieces fit together, and why you might want to + run it on your own infrastructure. +--- + +# What is Gooey Server? + +[Gooey.AI](https://gooey.ai) is a low-code AI recipe platform, and **Gooey Server** is our core repo โ€” the same code that runs [gooey.ai](https://gooey.ai) itself. It lets you discover, customize, and deploy AI "recipes" using the best of private and open-source AI, all behind a single API with a single auth token. + +Recipes are workflows that chain models together to accomplish a task. They are designed to be highly customizable and shareable, and everything you can do on the hosted service you can also do on a server you run yourself. + +The source lives at [github.com/GooeyAI/gooey-server](https://github.com/GooeyAI/gooey-server) under the [Apache-2.0 licence](https://github.com/GooeyAI/gooey-server/blob/master/LICENSE). + +## Architecture + +Gooey Server is four application processes running on top of four backing services. + +```mermaid +flowchart TD + Browser["Browser"] --> GUI["gooey-gui
Remix frontend ยท :3000"] + APIC["API Clients
(SDKs / curl)"] --> Server + GUI -- "render requests" --> Server["Python API + GUI Server
FastAPI ยท server.py ยท :8080"] + Server -- "enqueue recipe runs" --> Rabbit[("RabbitMQ ยท :5672
Celery broker")] + Rabbit -- "amqp" --> Celery["Celery Workers
celeryapp"] + Celery -- "model calls" --> Providers["GenAI providers
OpenAI, Gemini, Replicate, ..."] + + Server --> PG[("PostgreSQL ยท :5432
application database")] + Server --> Redis[("Redis ยท :6379
cache + pub/sub")] + Server --> Vespa[("Vespa ยท :8085
vector + text search")] + Celery --> PG + Celery --> Redis + Celery --> Vespa + Admin["Django Admin
gooeysite ยท :8000"] --> PG + Redis -. "live updates" .-> GUI +``` + +### The components + +| Component | What it does | Port | +| --------- | ------------ | ---- | +| **gooey-gui** (`gooey-gui/`) | Remix/React frontend. Asks the Python server to render each page as a JSON component tree, renders that in React, and subscribes to Redis pub/sub so pages update live while a recipe runs. | `3000` | +| **Python API + GUI Server** (`server.py`) | FastAPI app that serves the public API and the page-render endpoints used by gooey-gui. | `8080` | +| **Celery Workers** (`celeryapp/`) | Run the actual recipes: consume jobs from RabbitMQ, call the GenAI providers, save results to Postgres, and publish progress to Redis. | โ€” | +| **Django Admin** (`gooeysite/`) | Admin UI over the same Postgres database โ€” where you manage users, credits, and AI model specs. | `8000` | +| **PostgreSQL 15** | Application database. | `5432` | +| **Redis 8** | Cache and realtime pub/sub. | `6379` | +| **RabbitMQ** | Celery broker. | `5672` | +| **Vespa** | Vector and full-text search, powering document search / RAG. | `8085` | + +{% hint style="info" %} +All four backing services are open source, and a default install needs no cloud account at all. See [Platform Independence](platform-independence.md) for the full accounting. +{% endhint %} + +## Should you self-host? + +Let's be direct: **for most developers, we do not recommend running or forking Gooey Server.** Use the [Gooey.AI API](https://gooey.ai/api/) or the [Python SDK](https://github.com/GooeyAI/python-sdk) instead โ€” no servers, no API keys to juggle, no infrastructure to babysit. + +Self-hosting is the right call when you need something the hosted service can't give you: + +* **You want to create a new recipe**, rather than change the parameters on an existing one. +* **You want to add an AI model we don't support** โ€” including a model running entirely on your own hardware. +* **You have specific data-practice requirements** โ€” a particular cloud provider, a particular jurisdiction, or no cloud at all. +* **You want to run your own server cluster** for your organisation, your country, or your customers. +* **You want to add functionality** that the hosted platform doesn't offer. + +## Why local and sovereign hosting matters + +Running Gooey on your own infrastructure isn't only a developer convenience โ€” for a lot of our users it's the whole point. + +AI systems increasingly mediate healthcare advice, agricultural extension, education, and government services. When that infrastructure runs in someone else's data centre under someone else's terms, the communities being served have no say over how it behaves, what it costs, whether it understands their language, or whether it stays switched on. + +Self-hosted Gooey Server is a practical answer to that: + +* **Data stays where you put it.** Uploads, run history, and user records live in your Postgres and your filesystem. Nothing has to leave your network. +* **Models are your choice.** Point Gooey at [a model running on your own GPU](adding-local-ai-models.md) โ€” Ollama, vLLM, LocalAI, llama.cpp โ€” or at a regional provider, or at a frontier lab. Switching is a config change, not a rewrite. +* **No vendor can suspend you.** Every proprietary dependency is optional and off by default. The stack runs end to end on open-source components. +* **Workflows are portable.** Recipes built on a sovereign deployment can be shared with, and forked by, anyone else running the same open stack. + +{% hint style="success" %} +Our founders wrote about this at length in **[How Middle Powers Cooperate for AI Sovereignty](https://gooey.ai/sovereignty)** โ€” the case that middle-power nations gain more from cooperating on open benchmarks, datasets, commoditised models, and shared workflows than from each building an isolated stack. Self-hosted Gooey Server is the piece of that argument you can actually run. +{% endhint %} + +### Running with zero proprietary services + +A default local install already avoids every closed-source dependency. Nothing in this table needs configuring to reach the "Default locally" column โ€” that is what you get out of the box. + +| Concern | Default locally | Turned on by | +| ------- | --------------- | ------------ | +| Auth | Local Django email/password (`routers/local_auth.py`) | `ENABLE_FIREBASE_AUTH` | +| File storage | Local filesystem under `MEDIA_ROOT` (`./media`) | `GS_BUCKET_NAME` | +| LLMs | Any OpenAI-compatible server via `AIModelSpec.base_url` | Provider API keys | +| STT / TTS / embeddings | Self-hosted Whisper, Seamless, MMS, Bark, E5/GTE on the GPU Celery worker | Provider API keys | +| Document OCR | Standard text extraction, no OCR | `AZURE_FORM_RECOGNIZER_KEY` or `MISTRAL_API_KEY` | +| Payments | Disabled; billing UI degrades gracefully and credits are granted via the admin | `STRIPE_SECRET_KEY` | +| Image moderation | Skipped | `AZURE_IMAGE_MODERATION_ENDPOINT` | +| Managed secrets | Disabled; pass keys to functions as env vars | `AZURE_KEY_VAULT_ENDPOINT` | +| Analytics | No script served | GTM ID | +| Messaging connectors | Disabled | `FB_APP_ID`, `TWILIO_ACCOUNT_SID`, `SLACK_CLIENT_ID` | + +The backing services are PostgreSQL (PostgreSQL License), RabbitMQ (MPL-2.0), Vespa (Apache-2.0), and Redis 8 (used under its AGPL-3.0 option; [Valkey](https://valkey.io) is a drop-in alternative with no code changes). Gooey Server itself is Apache-2.0. + +Full detail, including code references for each swap point, is in [Platform Independence](platform-independence.md). + +## Where to go next + +

Installation Guide

Get a server running, with Docker or a full manual installinstallation

Adding Local AI Models

Point Gooey at Ollama, vLLM, or any OpenAI-compatible serveradding-local-ai-models.md

Configuration Reference

Every environment variable, with defaultsconfiguration.md

Platform Independence

How each proprietary dependency is made optionalplatform-independence.md
+ +Still stuck? Ask in [Discord](https://gooey.ai/discord). diff --git a/hosting-gooey-server/adding-local-ai-models.md b/hosting-gooey-server/adding-local-ai-models.md new file mode 100644 index 0000000..aaad9ff --- /dev/null +++ b/hosting-gooey-server/adding-local-ai-models.md @@ -0,0 +1,50 @@ +--- +icon: microchip +description: >- + Point Gooey Server at Ollama, vLLM, LocalAI, LM Studio or llama.cpp and run + recipes with no cloud model access at all. +--- + +# Adding Local AI Models + +`setup_local` seeds specs for cloud models (OpenAI, Google, Anthropic), which need the corresponding API keys to actually run. To run Gooey with no cloud model access at all, point it at a local OpenAI-compatible server โ€” **Ollama, vLLM, LocalAI, LM Studio, or llama.cpp** all work. + +{% hint style="success" %} +This is pure runtime configuration. No code changes, no forking, no rebuild. +{% endhint %} + +## 1. Run the model server + +With [Ollama](https://ollama.com), `ollama pull ` fetches a model and its server listens on port `11434` by default: + +```bash +ollama pull qwen3.5:4b +``` + +## 2. Register it in the Django admin + +Go to **AI Models โ†’ AI Model Specs โ†’ Add** ([http://localhost:8000/ai\_models/aimodelspec/add/](http://localhost:8000/ai_models/aimodelspec/add/)), set **Category** to `LLM`, and fill in: + +| Field | Value | +| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| **Name** | Internal id used in API calls, e.g. `qwen3_5_4b`. Don't change it after use. | +| **Label** | UI display name, e.g. `qwen3.5 4b` | +| **Creator** | Select or add, e.g. `Qwen` | +| **Model id** | The provider/HuggingFace id, exactly as the server expects it, e.g. `qwen3.5:4b` | +| **Priority** | Sort order within the creator group | +| **Provider** (Provider Settings) | `OpenAI` โ€” Ollama speaks the OpenAI-compatible API | +| Context Window, Max Output Tokens (Model Settings) | Per the model; check Chat Model / Thinking Model / Supports Temperature as applicable | +| **API Key** (API Settings) | `ollama` โ€” a placeholder, it isn't validated | +| **Base URL** (API Settings) | `http://localhost:11434/v1`, or wherever you're hosting the model | + +Click **Save**, and the model shows up in the model pickers. + +{% hint style="info" %} +On the [Docker path](installation/quickstart-with-docker.md), `http://localhost:11434/v1` works from inside the containers too: `docker-compose.local.yml` maps `localhost` to the host gateway for every app service. +{% endhint %} + +## Beyond LLMs + +LLMs are the most common thing to self-host, but they aren't the only one. Embeddings (`intfloat/e5-*`, `thenlper/gte-*`), speech-to-text (Whisper, Seamless M4T, MMS), and text-to-speech (Bark) all run on the self-hosted GPU Celery worker, with cloud providers as optional alternatives behind the same abstraction. + +See [Platform Independence](platform-independence.md#4-ai-models-abstraction-layers-with-self-hosted-alternatives-path-2) for the full picture, including where each abstraction lives in the code. diff --git a/hosting-gooey-server/configuration.md b/hosting-gooey-server/configuration.md new file mode 100644 index 0000000..b9ee97b --- /dev/null +++ b/hosting-gooey-server/configuration.md @@ -0,0 +1,288 @@ +--- +icon: sliders +description: Every environment variable Gooey Server reads, with defaults. +--- + +# Configuration Reference + +All settings are read from environment variables (or a `.env` file). + +--- + +## Server URLs + +| Variable | Required | Default | Description | +| ---------------- | -------- | ------------------------- | --------------------------------------------------------- | +| `APP_BASE_URL` | No | `http://localhost:3000` | Public base URL of the frontend (e.g. `https://gooey.ai`) | +| `API_BASE_URL` | No | `http://localhost:8080` | Public base URL of the API server | +| `ADMIN_BASE_URL` | No | `https://admin.gooey.ai/` | Public base URL of the Django admin site | + +--- + +## Django + +| Variable | Required | Default | Description | +| ----------------------- | ------------- | -------------- | -------------------------------------------------------------------- | +| `DEBUG` | No | `True` | Enable Django debug mode. Set to `False` in production. | +| `SECRET_KEY` | **Prod only** | `"xxxx"` (dev) | Django secret key. Must be a strong random value when `DEBUG=False`. | +| `SENTRY_DSN` | No | โ€” | Sentry error reporting DSN. Works only when `DEBUG=False`. | +| `SECURE_HSTS_SECONDS` | No | `0` | HSTS max-age in seconds. Set to a non-zero value in production. | +| `SESSION_COOKIE_SECURE` | No | `not DEBUG` | Require HTTPS for session cookies. | + +--- + +## Database (PostgreSQL) + +If none of these are set, the server falls back to SQLite (suitable for development only). + +| Variable | Required | Description | +| ------------ | -------------- | ---------------------- | +| `PGHOST` | For PostgreSQL | Postgres host | +| `PGPORT` | For PostgreSQL | Postgres port | +| `PGUSER` | For PostgreSQL | Postgres user | +| `PGDATABASE` | For PostgreSQL | Postgres database name | +| `PGPASSWORD` | For PostgreSQL | Postgres password | + +--- + +## Redis / Celery + +| Variable | Required | Default | Description | +| ----------------------------- | -------- | ------------------------ | --------------------------------------------------- | +| `REDIS_URL` | No | `redis://localhost:6379` | Redis URL used for session/cache and Celery results | +| `REDIS_CACHE_URL` | No | `redis://localhost:6379` | Redis URL used as Django cache backend | +| `LOCAL_CELERY_BROKER_URL` | No | `amqp://` | RabbitMQ URL for the local Celery worker | +| `LOCAL_CELERY_RESULT_BACKEND` | No | `REDIS_URL` | Result backend for local Celery tasks | +| `GPU_CELERY_BROKER_URL` | No | `amqp://localhost:5674` | RabbitMQ URL for the GPU Celery worker | +| `GPU_CELERY_RESULT_BACKEND` | No | `redis://localhost:6374` | Result backend for GPU Celery tasks | + +--- + +## Google Cloud / Firebase + +A Google Cloud service account (`serviceAccountKey.json` or `GOOGLE_APPLICATION_CREDENTIALS_JSON`) is used by multiple +parts of the system: Firebase auth, GCS file storage, Google TTS, Google Speech-to-Text, Google Translate, and Gemini +models. By default we use the local filesystem for file storage and django db for authentication. + +| Variable | Required | Default | Description | +| ---------------------------------------------------------------- | -------- | ------- |----------------------------------------------------------------------------------------------------------------------------------------------------| +| `GOOGLE_APPLICATION_CREDENTIALS_JSON` / `serviceAccountKey.json` | No | โ€” | Service account key as a JSON string (alternative to `serviceAccountKey.json`). Required if you want to use any Google Cloud services. | +| `ENABLE_FIREBASE_AUTH` | No | `False` | Enable Firebase Authentication instead of local password hash | +| `GOOGLE_CLIENT_ID` | No | - | Google OAuth client ID (for Firebase Google sign-in) | +| `FIREBASE_CONFIG` | No | - | Firebase web app config JSON string | +| `GCP_PROJECT` | No | - | Google Cloud project ID | +| `GCP_REGION` | No | - | Google Cloud region | +| `GS_BUCKET_NAME` | No | - | Use this GCS bucket for file storage instead of local filesystem | +| `GS_MEDIA_PATH` | No | - | Path prefix inside the GCS bucket for media files | +| `GS_STATIC_PATH` | No | - | Path prefix inside the GCS bucket for static pages | + +### โ˜๏ธ Create a google cloud / firebase account + +1. Create a [google cloud](https://console.cloud.google.com/) project +2. Create a [firebase project](https://console.firebase.google.com/) (using the same google cloud project) +3. Enable the following services: + - [Authentication](https://console.firebase.google.com/project/_/authentication) + - [Storage](https://console.firebase.google.com/project/_/storage) + - [Speech-to-Text](https://console.cloud.google.com/marketplace/product/google/speech.googleapis.com) + - [Text-to-Speech](https://console.cloud.google.com/marketplace/product/google/texttospeech.googleapis.com) + - [Translation API](https://console.cloud.google.com/marketplace/product/google/translate.googleapis.com) + - [Google Drive API](https://console.cloud.google.com/apis/library/drive.googleapis.com) +4. Go to IAM, Create a service account with following roles: + - Cloud Datastore User + - Cloud Speech Administrator + - Cloud Translation API Admin + - Firebase Authentication Admin + - Storage Admin +5. Create and Download a JSON Key for this service account and save it to the project root as `serviceAccountKey.json`. +6. Add your project & bucket name to `.env` (see [configuration.md](configuration.md) for all available settings) + +--- + +## Local filesystem storage + +Used by default when `GS_BUCKET_NAME` is unset. Uploaded files are written under +`MEDIA_ROOT` and served by the API server at `MEDIA_URL`. + +| Variable | Required | Default | Description | +| ------------ | -------- | --------- | ------------------------------------------------ | +| `MEDIA_ROOT` | No | `./media` | Local directory where uploaded files are stored | +| `MEDIA_URL` | No | `/media/` | URL path under which stored files are served | + +--- + +## AI model API keys + +All optional. Enable the models you intend to use. + +| Variable | Provider | +| ---------------------------------- | -------------------------------- | +| `OPENAI_API_KEY` | OpenAI (GPT, Whisper, DALL-E, โ€ฆ) | +| `ANTHROPIC_API_KEY` | Anthropic (Claude) | +| `REPLICATE_API_TOKEN` | Replicate | +| `REPLICATE_API_KEY` | Replicate (alternate key) | +| `FAL_API_KEY` | fal.ai | +| `GROQ_API_KEY` | Groq | +| `FIREWORKS_API_KEY` | Fireworks AI | +| `MISTRAL_API_KEY` | Mistral AI | +| `HF_TOKEN` | Hugging Face | +| `SARVAM_API_KEY` | Sarvam AI | +| `DEEPGRAM_API_KEY` | Deepgram (speech-to-text) | +| `ELEVEN_LABS_API_KEY` | ElevenLabs (TTS) | +| `UBERDUCK_KEY` / `UBERDUCK_SECRET` | Uberduck (TTS) | +| `PUBLICAI_API_KEY` | PublicAI | +| `SEA_LION_API_KEY` | SEA-LION | +| `GHANA_NLP_SUBKEY` | GhanaNLP | +| `LELAPA_API_KEY` | Lelapa AI | +| `INTRON_API_KEY` | Intron | + +--- + +## Azure AI services + +All optional. Needed only for workflows using Azure-hosted models or moderation. + +| Variable | Description | +| --------------------------------- | --------------------------------- | +| `AZURE_SPEECH_REGION` | Azure Speech region | +| `AZURE_SPEECH_KEY` | Azure Speech API key | +| `AZURE_OPENAI_ENDPOINT_CA` | Azure OpenAI endpoint (Canada) | +| `AZURE_OPENAI_KEY_CA` | Azure OpenAI key (Canada) | +| `AZURE_OPENAI_ENDPOINT_EASTUS2` | Azure OpenAI endpoint (East US 2) | +| `AZURE_OPENAI_KEY_EASTUS2` | Azure OpenAI key (East US 2) | +| `AZURE_FORM_RECOGNIZER_ENDPOINT` | Azure Form Recognizer endpoint | +| `AZURE_FORM_RECOGNIZER_KEY` | Azure Form Recognizer key | +| `AZURE_IMAGE_MODERATION_ENDPOINT` | Azure Content Moderator endpoint | +| `AZURE_IMAGE_MODERATION_KEY` | Azure Content Moderator key | +| `AZURE_KEY_VAULT_ENDPOINT` | Azure Key Vault endpoint | + +--- + +## Payments + +| Variable | Description | +| ------------------------ | ------------------------------ | +| `STRIPE_SECRET_KEY` | Stripe secret key | +| `STRIPE_ENDPOINT_SECRET` | Stripe webhook endpoint secret | +| `PAYPAL_CLIENT_ID` | PayPal client ID | +| `PAYPAL_SECRET` | PayPal secret | +| `PAYPAL_BASE` | PayPal API base URL | +| `PAYPAL_WEBHOOK_ID` | PayPal webhook ID | + +--- + +## Messaging integrations + +| Variable | Description | +| -------------------------- | ------------------------------------------------------------- | +| `FB_APP_ID` | Facebook / Meta app ID | +| `FB_APP_SECRET` | Facebook / Meta app secret | +| `FB_WEBHOOK_TOKEN` | Facebook webhook verification token | +| `FB_WHATSAPP_CONFIG_ID` | WhatsApp configuration ID | +| `WHATSAPP_ACCESS_TOKEN` | WhatsApp access token | +| `SLACK_CLIENT_ID` | Slack app client ID | +| `SLACK_CLIENT_SECRET` | Slack app client secret | +| `SLACK_VERIFICATION_TOKEN` | Slack verification token | +| `TELEGRAM_WEBHOOK_SECRET` | Telegram webhook secret | +| `ONEDRIVE_CLIENT_ID` | Microsoft OneDrive client ID | +| `ONEDRIVE_CLIENT_SECRET` | Microsoft OneDrive client secret | +| `TWILIO_ACCOUNT_SID` | Twilio account SID | +| `TWILIO_API_KEY_SID` | Twilio API key SID | +| `TWILIO_API_KEY_SECRET` | Twilio API key secret | +| `WS_STREAM_API_BASE_URL` | derived from `API_BASE_URL`, userd for twilio voice streaming | +| `WS_PROXY_API_BASE_URL` | derived from `API_BASE_URL`, userd for twilio voice streaming | +| `TWITTER_BEARER_TOKEN` | Twitter/X bearer token | + +--- + +## Email + +| Variable | Default | Description | +| -------------------- | ------- | --------------------------------------------- | +| `POSTMARK_API_TOKEN` | - | Postmark API token for transactional email | +| `ADMIN_EMAILS` | - | Comma-separated list of admin email addresses | + +--- + +## Search & maps + +| Variable | Description | +| -------------------------- | ------------------------------ | +| `SERPER_API_KEY` | Serper Google Search API key | +| `GOOGLE_GEOCODING_API_KEY` | Google Geocoding API key | +| `GOOGLE_MAPS_API_KEY` | Google Maps JavaScript API key | + +--- + +## Vector search (Vespa) + +| Variable | Default | Description | +| ------------------------- | ------------------------ | ---------------------------- | +| `VESPA_URL` | `http://localhost:8085` | Vespa query/document API URL | +| `VESPA_CONFIG_SERVER_URL` | `http://localhost:19071` | Vespa config server URL | + +--- + +## Functions runtime (Cloudflare Workers) + +See [Installation Guide ยง Functions runtime](installation/#functions-runtime-cloudflare-workers) for deployment instructions. + +| Variable | Description | +| ------------------------- | --------------------------------------------------------------------------------------- | +| `CF_FUNCTIONS_URL` | URL of the Cloudflare Worker executor | +| `CF_ACCESS_CLIENT_ID` | Cloudflare Access service token ID, sent as the `CF-Access-Client-Id` header | +| `CF_ACCESS_CLIENT_SECRET` | Cloudflare Access service token secret, sent as the `CF-Access-Client-Secret` header | + +--- + +## Modal (serverless GPU) + +| Variable | Description | +| -------------------- | ----------------------------- | +| `MODAL_TOKEN_ID` | Modal token ID | +| `MODAL_TOKEN_SECRET` | Modal token secret | +| `MODAL_VLLM_API_KEY` | API key for Modal-hosted vLLM | + +--- + +## LiveKit + +| Variable | Description | +| ---------------------------- | ------------------ | +| `LIVEKIT_API_KEY` | LiveKit API key | +| `LIVEKIT_API_SECRET` | LiveKit API secret | +| `LIVEKIT_URL` | LiveKit server URL | +| `LIVEKIT_SIP_URL` | LiveKit SIP URL | +| `LIVEKIT_SIP_TRUNK_NAME` | SIP trunk name | +| `LIVEKIT_SIP_TRUNK_USERNAME` | SIP trunk username | +| `LIVEKIT_SIP_TRUNK_PASSWORD` | SIP trunk password | + +--- + +## Scraping proxy + +| Variable | Description | +| ------------------------- | ------------------------------------------ | +| `SCRAPING_PROXY_HOST` | Proxy host for web scraping | +| `SCRAPING_PROXY_USERNAME` | Proxy username | +| `SCRAPING_PROXY_PASSWORD` | Proxy password | +| `SCRAPING_PROXY_CERT_URL` | URL to download the proxy's CA certificate | + +--- + +## Observability + +| Variable | Required | Description | +| --------------------- | ------------- | ---------------------------------------- | +| `SENTRY_DSN` | **Prod only** | Sentry DSN. Required when `DEBUG=False`. | +| `APOLLO_API_KEY` | No | Apollo.io API key | +| `LANGFUSE_PUBLIC_KEY` | No | Langfuse public key | +| `LANGFUSE_SECRET_KEY` | No | Langfuse secret key | +| `LANGFUSE_BASE_URL` | No | Langfuse base URL (for self-hosted) | + +--- + +## Misc + +| Variable | Default | Description | +| ------------------ | ------- | ---------------- | +| `COMPOSIO_API_KEY` | - | Composio API key | diff --git a/hosting-gooey-server/installation/README.md b/hosting-gooey-server/installation/README.md new file mode 100644 index 0000000..a45a463 --- /dev/null +++ b/hosting-gooey-server/installation/README.md @@ -0,0 +1,209 @@ +--- +icon: download +description: >- + Choose an installation path, understand what gets installed, and verify the + result. +--- + +# Installation Guide + +A step-by-step guide to getting Gooey Server running on your own machine. + +Before you invest the time: for most developers we **do not** recommend running or forking Gooey Server โ€” use the [API](https://gooey.ai/api/) or the [Python SDK](https://github.com/GooeyAI/python-sdk) instead. Install locally if you want to build a new recipe, add an unsupported AI model, run your own server cluster, or meet enterprise data requirements. See [What is Gooey Server?](../) for the full rationale. + +## Choose your path + +| | **Quickstart with Docker** | **Manual Installation** | +| ------------------- | ---------------------------------------------------------------------- | -------------------------------------------------- | +| **Setup time** | ~10 min (mostly the first build) | ~45 min | +| **Platforms** | macOS, Linux, Windows | macOS, Linux | +| **Recipe coverage** | All except recipes needing playwright or mediapipe | Everything | +| **Best for** | Trying Gooey out, running it as a self-hosted service, backend work | Day-to-day development, debugging individual services | + +{% hint style="success" %} +**Start with [Quickstart with Docker](quickstart-with-docker.md).** Switch to [Manual Installation](manual-installation.md) when you need full recipe parity or a faster edit-run loop. The two paths share the same ports and credentials, so you can also run the backing services from Docker Compose while running the app processes natively. +{% endhint %} + +

Quickstart with Docker

One command brings up the whole stack. Recommended starting point.quickstart-with-docker.md

Manual Installation

Everything runs natively. Full recipe coverage, easier debugging.manual-installation.md
+ +## What gets installed + +Four app processes on top of four backing services: + +| Component | What it does | Port | +| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------ | +| gooey-gui (`gooey-gui/`) | Remix/React frontend. Asks the Python server to render each page as a JSON component tree and subscribes to Redis pub/sub for live updates | `3000` | +| Python API + GUI Server (`server.py`) | FastAPI app serving the public API and the page-render endpoints | `8080` | +| Celery workers (`celeryapp/`) | Run the actual recipes: pull jobs from RabbitMQ, call model providers, save results | โ€” | +| Django Admin (`gooeysite/`) | Admin UI over the same Postgres database | `8000` | +| PostgreSQL 15 | Application database | `5432` | +| Redis 8 | Cache + realtime pub/sub | `6379` | +| RabbitMQ | Celery broker | `5672` | +| Vespa | Vector + full-text search (doc search / RAG) | `8085` | + +See the [architecture diagram](../#architecture) for how they connect. + +{% hint style="info" %} +**No cloud account is required.** A default install authenticates with local Django email/password (Firebase auth is off unless you set `ENABLE_FIREBASE_AUTH`), stores uploads on the local filesystem (Google Cloud Storage is off unless you set `GS_BUCKET_NAME`), and leaves payments, analytics, cloud moderation, and managed secrets disabled. All four backing services are open source. See [Platform Independence](../platform-independence.md) for the full accounting. +{% endhint %} + +## Optional add-ons + +Everything here is opt-in โ€” skip it until you need the feature. + +### Provider API keys + +Each model provider becomes usable once its key is in `.env`; on the Docker path the app services read the same root `.env`, so add keys there and restart. `COMPOSIO_API_KEY` enables the Composio tools selector. Bot deployments need `FB_APP_ID` / `TWILIO_ACCOUNT_SID` / `SLACK_CLIENT_ID` โ€” the deploy buttons stay hidden and creation is blocked until they're set. Full list: [Configuration Reference](../configuration.md). + +### Functions runtime (Cloudflare Workers) + +The Functions recipe executes user-supplied JavaScript in sandboxed [Cloudflare Dynamic Workers](https://developers.cloudflare.com/dynamic-workers/) via `functions/executor_cf/`. Run it locally with wrangler: + +```bash +cd functions/executor_cf +npm install +npx wrangler dev +``` + +Then point Gooey at it in `.env`: + +```env +CF_FUNCTIONS_URL=http://localhost:8787 +``` + +To deploy it to Cloudflare instead, see [`functions/executor_cf/wrangler.jsonc`](https://github.com/GooeyAI/gooey-server/blob/master/functions/executor_cf/wrangler.jsonc). + +### Secret scanning + +Gitleaks runs pre-commit (see `.pre-commit-config.yaml`). Test it without committing by running `pre-commit`. Prefer labelling false positives with a `#gitleaks:allow` comment over skipping with `SKIP=gitleaks git commit`. + +### Code formatting + +This project uses [ruff](https://docs.astral.sh/ruff/). + +## Keeping your install up to date + +After a `git pull`, three kinds of change need action: + +```bash +git pull + +# new/changed Python or Node dependencies (pyproject.toml, poetry.lock, package.json) +poetry install --with dev # Manual install +docker compose -f docker-compose.local.yml up --build # Docker + +# new database migrations +./manage.py migrate # Manual install +docker compose -f docker-compose.local.yml run --rm admin ./manage.py migrate # Docker + +# changed Vespa schema +./manage.py runscript setup_vespa_db +``` + +On the Docker path the `admin` service applies migrations on every start, so a plain `up` usually covers it. On the manual path nothing is automatic โ€” and remember the Celery worker needs a manual restart to pick up any code change. + +## Verifying your install + +Work through this once: + +* [ ] [http://localhost:3000/explore](http://localhost:3000/explore) lists workflows +* [ ] [http://localhost:8080/docs](http://localhost:8080/docs) renders the API reference +* [ ] [http://localhost:8000](http://localhost:8000) accepts your Django admin login +* [ ] You can log in at [http://localhost:3000/login/](http://localhost:3000/login/) with your own email +* [ ] Your workspace has a non-zero balance in the admin +* [ ] A recipe run completes โ€” pick a simple one, hit Run, and watch the Celery logs + +Then run the test suite: + +```bash +ulimit -n unlimited # raise the open-file limit +./scripts/run-tests.sh +``` + +The script downloads `fixture.json`, checks formatting with `ruff format --diff`, and runs pytest. Extra arguments are passed through to pytest, e.g. `./scripts/run-tests.sh -k asr`. + +## Troubleshooting + +
+ +The first Docker build is very slow + +Expected โ€” it installs the full Python dependency set and builds the frontend. Later builds hit the layer cache. On Apple Silicon, OrbStack builds native arm64 and is noticeably faster than Docker Desktop. + +
+ +
+ +A recipe fails with an insufficient-credits error + +Your workspace balance is 0. Top it up at [http://localhost:8000/workspaces/workspace/](http://localhost:8000/workspaces/workspace/). + +
+ +
+ +A recipe fails with an authentication or API-key error + +You picked a cloud-hosted model. Either add that provider's key to `.env` and restart, or [register a local model](../adding-local-ai-models.md). + +
+ +
+ +Migrations ran but my data isn't in Postgres + +On the manual path, missing `PG*` variables make Django fall back to `db.sqlite3` in the repo root. Fill in `.env` per [step 4 of the manual install](manual-installation.md#4-configure-env) and re-run `./manage.py migrate`. + +
+ +
+ +Doc search / RAG recipes error out + +Vespa isn't running or its schema was never applied. Check that the container is up, then run `./manage.py runscript setup_vespa_db`. + +
+ +
+ +Recipes hang as "queued" forever + +The Celery worker isn't running, or it can't reach RabbitMQ. Check its logs โ€” on the Docker path, `docker compose -f docker-compose.local.yml logs -f celery`. + +
+ +
+ +Code changes don't take effect + +The Celery worker never picks up code changes on its own โ€” restart it. On the Docker path, frontend changes require a rebuild (`up --build`). + +
+ +
+ +localhost:3000 is flaky on macOS + +Under OrbStack, use `https://ui.gooey-server.orb.local` instead. + +
+ +
+ +Some recipe complains about playwright or mediapipe + +You're on the Docker path; `Dockerfile.local` omits both. Use [Manual Installation](manual-installation.md) for those recipes. + +
+ +
+ +Something in the Docker stack is wedged + +Rebuild from scratch with `docker compose -f docker-compose.local.yml build --no-cache`. Only resort to `down -v` if you're willing to lose your local database. + +
+ +--- + +Still stuck? Ask in [Discord](https://gooey.ai/discord). diff --git a/hosting-gooey-server/installation/manual-installation.md b/hosting-gooey-server/installation/manual-installation.md new file mode 100644 index 0000000..074e8f4 --- /dev/null +++ b/hosting-gooey-server/installation/manual-installation.md @@ -0,0 +1,201 @@ +--- +icon: screwdriver-wrench +description: >- + Run every service natively for full recipe coverage and easier per-service + debugging. +--- + +# Manual Installation + +Everything runs directly on your machine. More setup than the [Docker path](quickstart-with-docker.md), but full recipe coverage and easier per-service debugging. + +**Setup time:** ~45 minutes ยท **Platforms:** macOS, Linux + +## 1. Python and Poetry + +Install [pyenv](https://github.com/pyenv/pyenv), then the same Python version as the [Dockerfile](https://github.com/GooeyAI/gooey-server/blob/master/Dockerfile) โ€” currently **3.10.12**: + +```bash +# linux, if you don't have pyenv yet +curl https://pyenv.run | bash + +pyenv install 3.10.12 +pyenv local 3.10.12 +``` + +Install [Poetry](https://python-poetry.org/docs/) (on Linux it's likely in your distro's package repos), then create the virtualenv and install dependencies: + +```bash +poetry shell +poetry install --with dev +``` + +{% hint style="info" %} +On Linux you may have to remove `package-mode = false` from line 7 of `pyproject.toml` for `poetry install` to succeed. +{% endhint %} + +## 2. System packages + +{% tabs %} +{% tab title="macOS" %} +```bash +brew install redis rabbitmq postgresql@15 zbar +``` + +Optional, for HEIC image support ([wand docs](https://docs.wand-py.org/en/0.5.7/guide/install.html)): + +```bash +brew install freetype imagemagick +export MAGICK_HOME=/opt/homebrew +``` +{% endtab %} + +{% tab title="Linux" %} +Install `redis`, `rabbitmq-server`, `postgresql` 15, and the `zbar` library with your distro's package manager. +{% endtab %} +{% endtabs %} + +## 3. Start the backing services + +{% tabs %} +{% tab title="macOS" %} +```bash +brew services start redis +brew services start rabbitmq +brew services start postgresql@15 +``` +{% endtab %} + +{% tab title="Linux" %} +```bash +sudo systemctl enable --now redis rabbitmq-server postgresql +``` + +Also enable password authentication for the `gooey` user. Open `pg_hba.conf` (usually `/etc/postgresql//main/` or `/var/lib/pgsql//data/`) and add these lines at the bottom: + +``` +local all gooey md5 +host all gooey md5 +``` + +Then `sudo systemctl restart postgresql`. +{% endtab %} +{% endtabs %} + +## 4. Configure `.env` + +Create a `.env` at the repo root. + +{% hint style="warning" %} +This step is easy to miss and matters: **if the `PG*` variables are unset, the server silently falls back to SQLite** instead of your Postgres database. +{% endhint %} + +```env +PGHOST=localhost +PGPORT=5432 +PGUSER=gooey +PGPASSWORD=gooey +PGDATABASE=gooey + +REDIS_URL=redis://localhost:6379 +REDIS_CACHE_URL=redis://localhost:6379 +LOCAL_CELERY_BROKER_URL=amqp:// +``` + +Everything else has a working local default. See the [Configuration Reference](../configuration.md) for the full list of settings. + +## 5. Initialize the database + +```bash +# create the gooey user and database +./manage.py sqlcreate | psql postgres # macOS +./manage.py sqlcreate | sudo -u postgres psql postgres # Linux + +# confirm you can connect (password: gooey) +psql -W -U gooey gooey + +# apply migrations +./manage.py migrate + +# create your Django admin user +./manage.py createsuperuser +``` + +Optionally load the sample data fixture. `fixture.json` is downloaded by `./scripts/run-tests.sh`, so run that first (or fetch the URL from the script): + +```bash +./manage.py loaddata fixture.json +``` + +{% hint style="danger" %} +To start over from scratch: `./manage.py reset_db -c` drops the entire database. Everything in it is lost. +{% endhint %} + +## 6. Vespa + +Vespa runs in a container even on the native path, so you still need OrbStack or Docker Desktop. + +```bash +docker volume create vespa + +docker run \ + --hostname vespa-container \ + -p 8085:8080 -p 19071:19071 \ + --volume vespa:/opt/vespa/var \ + -it --rm --name vespa vespaengine/vespa +``` + +With the container running, apply the schema: + +```bash +./manage.py runscript setup_vespa_db +``` + +## 7. Frontend dependencies + +Node 20 is what the project's own image uses: + +```bash +cd gooey-gui +npm install +``` + +## 8. Run the services + +Open each in its own terminal so you can read and restart them independently: + +| Service | Port | Command | +| ----------------------- | ------ | ------------------------------------------------------------------------------------------- | +| Python API + GUI Server | `8080` | `poetry run uvicorn server:app --host 127.0.0.1 --port 8080 --reload` | +| Node frontend | `3000` | `cd gooey-gui/; PORT=3000 REDIS_URL=redis://localhost:6379 npm run build && npm run start` | +| Celery (task runner) | โ€” | `poetry run celery -A celeryapp worker -P threads -c 16 -l DEBUG` | +| Django admin | `8000` | `poetry run python manage.py runserver 127.0.0.1:8000` | +| Vespa | `8085` | see [step 6](#6-vespa) | + +Then create your app account and grant it credits exactly as on the Docker path โ€” see [step 5](quickstart-with-docker.md#5-create-your-app-account) and [step 6](quickstart-with-docker.md#6-give-your-workspace-credits) there. + +## Reloading on code changes + +* **Python API + GUI Server** โ€” reloads on save with `--reload`; refresh the page to see changes. +* **Celery worker** โ€” must be restarted manually after every code change. +* **Frontend** โ€” use `cd gooey-gui/; PORT=3000 REDIS_URL=redis://localhost:6379 npm run dev` while working on React code. +* **Hot reload for UI iteration** โ€” `poetry run python server.py` reloads the webpage in place on code changes. Handy for fast UI work, but it uses more memory and usually OOMs after a few reloads. + +## Starting everything at once (Honcho) + +```bash +poetry run honcho start +``` + +Honcho runs the processes defined in [`Procfile`](https://github.com/GooeyAI/gooey-server/blob/master/Procfile) โ€” comment out any you don't need. + +{% hint style="warning" %} +Convenient, but it makes individual services much harder to debug. Prefer separate terminals for real work. +{% endhint %} + +## Next steps + +* [Verify your install](./#verifying-your-install) +* [Add a local AI model](../adding-local-ai-models.md) so you can run recipes without any cloud API keys +* [Configuration Reference](../configuration.md) for every available setting +* [Troubleshooting](./#troubleshooting) if something isn't working diff --git a/hosting-gooey-server/installation/quickstart-with-docker.md b/hosting-gooey-server/installation/quickstart-with-docker.md new file mode 100644 index 0000000..dbe8cdd --- /dev/null +++ b/hosting-gooey-server/installation/quickstart-with-docker.md @@ -0,0 +1,133 @@ +--- +icon: bolt +description: >- + Bring up Postgres, Redis, RabbitMQ, Vespa and all four app services with a + single Docker Compose command. +--- + +# Quickstart with Docker + +The fastest way to run Gooey Server. One command starts Postgres, Redis, RabbitMQ, Vespa, and all four app services. + +**Setup time:** ~10 minutes, mostly the first build ยท **Platforms:** macOS, Linux, Windows + +{% hint style="info" %} +`Dockerfile.local` is a deliberately lightweight image. A few recipes that depend on playwright or mediapipe won't work in-container โ€” see [Known limitations](#known-limitations) below. For full recipe parity, use [Manual Installation](manual-installation.md). +{% endhint %} + +## 1. Install Docker + +{% tabs %} +{% tab title="macOS" %} +Install [OrbStack](https://orbstack.dev/download). Recommended on Apple Silicon: native arm64, fast builds. + +{% hint style="warning" %} +OrbStack requires you to launch it manually the first time. +{% endhint %} +{% endtab %} + +{% tab title="Linux" %} +Install [Docker Engine](https://docs.docker.com/engine/install/) and the [Compose plugin](https://docs.docker.com/compose/install/linux/). +{% endtab %} + +{% tab title="Windows" %} +Install [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/). +{% endtab %} +{% endtabs %} + +## 2. Clone the repo + +```bash +git clone https://github.com/GooeyAI/gooey-server.git +cd gooey-server +``` + +The frontend lives at `gooey-gui/` inside this repo โ€” there are no submodules to initialize. + +## 3. Start the stack + +```bash +docker compose -f docker-compose.local.yml up --build +``` + +The first build takes a few minutes. Leave this terminal running (or add `-d` to detach). Database migrations and the Vespa schema are applied automatically by the `admin` service on startup. + +Once it's up: + +| Service | URL | +| ------------------- | ---------------------------------------------------------------- | +| UI | [http://localhost:3000/explore](http://localhost:3000/explore) | +| API docs | [http://localhost:8080/docs](http://localhost:8080/docs) | +| Django admin | [http://localhost:8000](http://localhost:8000) | +| RabbitMQ management | [http://localhost:15672](http://localhost:15672) | + +{% hint style="info" %} +On OrbStack, services are also reachable at `https://.gooey-server.orb.local` (e.g. [https://ui.gooey-server.orb.local](https://ui.gooey-server.orb.local)), which is often more reliable than `localhost:3000`. +{% endhint %} + +## 4. Run first-time setup + +Once, after the stack is up: + +```bash +docker compose -f docker-compose.local.yml run --rm admin ./manage.py runscript setup_local +``` + +This runs migrations, seeds a starter set of LLM model specs, and creates a Django admin superuser. + +Log in to [http://localhost:8000](http://localhost:8000) with username **`admin`** / password **`admin`**. + +{% hint style="danger" %} +These credentials are for local development only โ€” never expose this instance publicly as-is. +{% endhint %} + +## 5. Create your app account + +The Django admin user is separate from your Gooey app account. Go to [http://localhost:3000/login/](http://localhost:3000/login/) and enter any email and password: with local auth, an unknown email signs up as a new user and the password you type is set on first login. + +## 6. Give your workspace credits + +Recipe runs are metered against workspace credits, and a locally created account starts at **0**. Grant yourself credits in the Django admin: + +1. Open [http://localhost:8000/workspaces/workspace/](http://localhost:8000/workspaces/workspace/) +2. Search for your email and open your personal workspace +3. Set **Balance** to something generous, e.g. `10000`, and save + +Skip this and recipe runs will fail with an insufficient-credits error. + +{% hint style="success" %} +The app links you there directly. Visit [http://localhost:3000/account/billing](http://localhost:3000/account/billing) โ€” with no Stripe key configured, the billing page shows your balance plus an **Add balance in Django admin** link straight to your workspace's admin page. The link honours `ADMIN_BASE_URL`, which already defaults to `http://localhost:8000`. +{% endhint %} + +## 7. Everyday commands + +```bash +# stop everything (data is preserved) +docker compose -f docker-compose.local.yml down + +# follow logs for one service +docker compose -f docker-compose.local.yml logs -f celery + +# rebuild after changing pyproject.toml / package.json +docker compose -f docker-compose.local.yml up --build + +# open a shell in the app image +docker compose -f docker-compose.local.yml run --rm admin bash +``` + +Python source is bind-mounted into the containers, so Python edits need only a restart of the affected service (`docker compose -f docker-compose.local.yml restart api celery`) โ€” not a rebuild. Frontend changes are baked in at build time, so they do need `--build`. + +{% hint style="danger" %} +`docker compose -f docker-compose.local.yml down -v` also deletes the named volumes โ€” your database, uploads, and Vespa index are gone for good. Use it only when you want a truly clean slate, and re-run [step 4](#4-run-first-time-setup) afterwards. +{% endhint %} + +## Known limitations + +`Dockerfile.local` is a deliberately lightweight image: it skips compiling poppler from source, amd64-only packages, playwright, and mediapipe. A few recipes that depend on playwright or mediapipe won't work in-container. For full parity, use [Manual Installation](manual-installation.md). + +## Next steps + +* [Verify your install](./#verifying-your-install) +* [Add a local AI model](../adding-local-ai-models.md) so you can run recipes without any cloud API keys +* [Configuration Reference](../configuration.md) for every available setting +* [Troubleshooting](./#troubleshooting) if something isn't working diff --git a/hosting-gooey-server/platform-independence.md b/hosting-gooey-server/platform-independence.md new file mode 100644 index 0000000..f8e0dae --- /dev/null +++ b/hosting-gooey-server/platform-independence.md @@ -0,0 +1,159 @@ +--- +icon: scale-balanced +description: >- + How Gooey Server complies with Indicator 4 of the DPG Standard - every + proprietary dependency, its open alternative, and the swap mechanism. +--- + +# Platform Independence + +This document describes how Gooey Server complies with [Indicator 4 (Platform Independence)](https://github.com/DPGAlliance/dpg-resources/wiki/4.-Platform-Independence) of the DPG Standard, following the [DPG Alliance Platform Independence guide](https://github.com/DPGAlliance/dpg-resources/tree/main/docs/platform-independence). + +For every proprietary or closed-source component, we list the open alternative, the mechanism used to swap it (abstraction layer, feature flag, or migration path), and where the relevant code lives. + +Gooey Server itself is licensed under [Apache License 2.0](https://github.com/GooeyAI/gooey-server/blob/master/LICENSE). + +--- + +## Summary + +| Dependency | Type | Open alternative | Swap mechanism | Status | +|---|---|---|---|---| +| PostgreSQL | Database | โ€” (already open, PostgreSQL License) | n/a | โœ… Open | +| RabbitMQ | Message broker | โ€” (already open, MPL-2.0) | n/a | โœ… Open | +| Vespa | Search / vector store | โ€” (already open, Apache-2.0) | n/a | โœ… Open | +| Redis | Cache / result backend | Redis 8 (tri-licensed; used under its OSI-approved AGPL-3.0 option); Valkey (BSD-3) also drop-in | Container image only โ€” zero code coupling | โœ… Open (`redis:8`) | +| Firebase Auth | Authentication | Built-in local Django auth | Feature flag (`ENABLE_FIREBASE_AUTH`, default **off**) | โœ… Abstracted | +| Google Cloud Storage | File storage | Local filesystem storage | Feature flag (`GS_BUCKET_NAME`, default **unset**) | โœ… Abstracted | +| Cloud LLM APIs (OpenAI, Anthropic, Google, etc.) | AI models | Any OpenAI-compatible server (Ollama, vLLM, LocalAI, llama.cpp) | Abstraction layer (`AIModelSpec.base_url`) | โœ… Abstracted | +| Cloud STT / TTS / embeddings | AI models | Self-hosted Whisper, Seamless, MMS, Bark, E5/GTE on GPU worker | Abstraction layer (provider enums + GPU Celery worker) | โœ… Abstracted | +| Azure Document Intelligence / Mistral OCR | Document OCR | Standard text extraction (no OCR) | Feature flag + graceful degradation (default **unset**) | โœ… Abstracted | +| Stripe / PayPal | Payments | Not required โ€” billing gracefully disabled when keys unset (default) | Feature flag with graceful UI fallback | โœ… Abstracted | +| Azure Content Moderator | Image safety checker | Not required โ€” check skipped when endpoint unset (default) | Feature flag (`AZURE_IMAGE_MODERATION_ENDPOINT`, default **unset**) | โœ… Optional | +| Azure Key Vault | Managed secrets | Not required โ€” pass API keys as plain environment variables to functions instead | Optional (`AZURE_KEY_VAULT_ENDPOINT` unset โ‡’ disabled) | โœ… Optional | +| Modal (MMS TTS, Omnilingual ASR, SraVaani ASR) | AI model hosting | Optional feature; core TTS/ASR works via GPU worker or other providers | Optional integration | โœ… Optional | +| Font Awesome Pro | UI icons | Font Awesome Free (self-hosted) | Asset swap for self-hosted builds | ๐Ÿ”ง In progress | +| Google Tag Manager | Analytics | Not required for operation | Env-gated script (unset โ‡’ not rendered) | ๐Ÿ”ง In progress | +| WhatsApp / Slack / Facebook / Twilio integrations | Messaging connectors | Optional integrations; core product functions without them | Optional (keys unset โ‡’ disabled) | โœ… Optional | + +> Deployment, testing, CI/CD, containerization, and monitoring tools (Docker, GitHub Actions, Sentry) are exempt from platform independence per the DPG guide. + +--- + +## 1. Core infrastructure โ€” fully open + +The mandatory backing services are all under OSI-approved licenses and ship in [docker-compose.local.yml](https://github.com/GooeyAI/gooey-server/blob/master/docker-compose.local.yml): + +- **PostgreSQL 15** (PostgreSQL License) โ€” primary database for all application data, via the Django ORM. +- **RabbitMQ** (MPL-2.0) โ€” Celery task broker. +- **Vespa** (Apache-2.0) โ€” search and vector store for document retrieval, self-hosted. +- **Redis 8** โ€” cache and Celery result backend. Redis 8 is tri-licensed (RSALv2 / SSPLv1 / AGPL-3.0); this deployment uses it under the AGPL-3.0 option, which is OSI-approved. The `redis:8` image is used in both [docker-compose.local.yml](https://github.com/GooeyAI/gooey-server/blob/master/docker-compose.local.yml) and the CapRover deployment ([scripts/deployment/redis.Dockerfile](https://github.com/GooeyAI/gooey-server/blob/master/scripts/deployment/redis.Dockerfile)). The application has zero Redis-version coupling: it uses only connection URLs ([daras_ai_v2/settings.py#L455](https://github.com/GooeyAI/gooey-server/blob/master/daras_ai_v2/settings.py#L455)) and the MIT-licensed `redis-py` client over the standard wire protocol, so [Valkey](https://valkey.io) (BSD-3-Clause) is an equally drop-in alternative with no code changes. + +## 2. Authentication โ€” abstraction layer (Path 2) + +Firebase Auth is **optional and off by default**. The toggle is `ENABLE_FIREBASE_AUTH` ([daras_ai_v2/settings.py#L255](https://github.com/GooeyAI/gooey-server/blob/master/daras_ai_v2/settings.py#L255), default `False`). + +- Router selection: [server.py#L104-L111](https://github.com/GooeyAI/gooey-server/blob/master/server.py#L104) mounts either `routers/firebase_auth.py` or `routers/local_auth.py` based on the flag. +- Session verification: [auth/auth_backend.py#L38-L41](https://github.com/GooeyAI/gooey-server/blob/master/auth/auth_backend.py#L38) selects the matching `authenticate_session` implementation behind a common interface. +- The open path, [routers/local_auth.py](https://github.com/GooeyAI/gooey-server/blob/master/routers/local_auth.py), is a complete email/password flow built on Django's auth primitives (password hashing, session invalidation on password change, admin-driven password reset). It is the default for self-hosted deployments โ€” no Google account or Firebase project needed. + +Users previously created via Firebase are interoperable: accounts migrated from Firebase set a local password on first login ([routers/local_auth.py#L139-L156](https://github.com/GooeyAI/gooey-server/blob/master/routers/local_auth.py#L139)). + +## 3. File storage โ€” abstraction layer (Path 2) + +Google Cloud Storage is **optional and off by default**. When `GS_BUCKET_NAME` is unset (the default), all uploads are stored on the local filesystem under `MEDIA_ROOT` and served by the app itself. + +- Branch points: [daras_ai/image_input.py#L71-L137](https://github.com/GooeyAI/gooey-server/blob/master/daras_ai/image_input.py#L71) (`upload_file_from_bytes` and friends fall through to `save_local_file_from_bytes`). +- Guard: settings assert GCS is only enabled when credentials are actually provided ([daras_ai_v2/settings.py#L279](https://github.com/GooeyAI/gooey-server/blob/master/daras_ai_v2/settings.py#L279)). + +Any S3-compatible open object store (e.g., MinIO, AGPL-3.0) can also be fronted via the local path or a reverse proxy without code changes to callers, since all call sites go through the same upload helpers. + +## 4. AI models โ€” abstraction layers with self-hosted alternatives (Path 2) + +Gooey Server is multi-provider by design. No single AI vendor is mandatory. Each self-hosted path is runtime configuration, as described below โ€” no code changes required. + +### LLMs +Any server exposing an OpenAI-compatible `/v1/chat/completions` endpoint works โ€” **Ollama, vLLM, LocalAI, LM Studio, llama.cpp** โ€” by setting `base_url`/`api_key`/`model_id` on an `AIModelSpec` in the Django admin ([daras_ai_v2/language_model.py](https://github.com/GooeyAI/gooey-server/blob/master/daras_ai_v2/language_model.py)). No code changes required; this is runtime configuration. + +##### **How to Add Local AI Models** + +Go to **AI Models > AI Model Specs > Add** or http://localhost:8000/ai_models/aimodelspec/add/ +Choose the Category from dropdown as `LLM` + +Add the following details: +- **Name**: internal id used in API calls (e.g. `qwen3_5_4b`), don't change after use +- **Label**: UI display name (e.g. `qwen3.5 4b`) +- **Creator**: select or add (e.g. `Qwen`) +- **Model id**: provider/huggingface id (e.g. `qwen3.5:4b`). Please name this exactly as the provider id +- **Priority**: sort order within creator group +- **Under Provider Settings**: set Provider to OpenAI (Ollama uses an OpenAI-compatible API) +- **Under Model Settings**: set Context Window, Max Output Tokens, check Chat Model / Thinking Model / Supports Temperature as applicable +- **Under API Settings**: set **API Key** to `ollama` (placeholder, not validated), **Base URL** to `http://localhost:11434/v1` (wherever you are hosting your model) +- Click **Save** + +### Embeddings +Open-weight models (`intfloat/e5-*`, `thenlper/gte-*`) run on the self-hosted GPU Celery worker ([daras_ai_v2/embedding_model.py](https://github.com/GooeyAI/gooey-server/blob/master/daras_ai_v2/embedding_model.py)). Cloud embedding APIs are optional alternatives, not requirements. + +### Speech-to-text +Self-hosted **Whisper**, **Seamless M4T**, and **MMS** run on the GPU worker ([daras_ai_v2/asr.py](https://github.com/GooeyAI/gooey-server/blob/master/daras_ai_v2/asr.py)). Cloud STT providers (Google, Deepgram, Azure, ElevenLabs) are optional alternatives behind the same `AsrModels` enum. + +### Text-to-speech +Self-hosted **Bark** runs on the GPU worker; cloud TTS providers are optional alternatives behind the `TextToSpeechProviders` enum ([daras_ai_v2/text_to_speech_settings_widgets.py](https://github.com/GooeyAI/gooey-server/blob/master/daras_ai_v2/text_to_speech_settings_widgets.py)). + +### Document Intelligence / OCR +Document extraction workflows support multiple OCR providers through a unified abstraction ([recipes/DocExtract.py#L606-L631](https://github.com/GooeyAI/gooey-server/blob/master/recipes/DocExtract.py#L606)): + +- **Azure Document Intelligence** (proprietary) โ€” enabled when `AZURE_FORM_RECOGNIZER_KEY` is set ([daras_ai_v2/azure_doc_extract.py](https://github.com/GooeyAI/gooey-server/blob/master/daras_ai_v2/azure_doc_extract.py)) +- **Mistral OCR** (cloud API, self-hostable models) โ€” enabled when `MISTRAL_API_KEY` is set ([daras_ai_v2/mistral_ocr.py](https://github.com/GooeyAI/gooey-server/blob/master/daras_ai_v2/mistral_ocr.py)) +- **Fallback to standard text extraction** โ€” when no OCR provider is configured (the default), documents use standard text extraction methods without OCR capabilities + +The UI gracefully degrades when OCR providers are unavailable, displaying a warning and falling back to basic text extraction. Both providers are optional; neither is required for core document processing functionality. + +### Modal-hosted models +Three models (MMS TTS, Omnilingual ASR, SraVaani ASR) are deployed on [Modal](https://modal.com). These are **optional features**: TTS and ASR each have multiple self-hosted and provider alternatives, and the platform functions fully without Modal credentials. + +## 5. Payments โ€” feature flag with graceful degradation (Path 2) + +Stripe and PayPal power billing on the hosted gooey.ai service. Payment processing is **not required to run the software**, and billing degrades gracefully when disabled: + +- Payment credentials default to unset: `STRIPE_SECRET_KEY = config("STRIPE_SECRET_KEY", None)` ([daras_ai_v2/settings.py#L415](https://github.com/GooeyAI/gooey-server/blob/master/daras_ai_v2/settings.py#L415)), so a fresh self-hosted install has payments off with no configuration needed. +- The billing page checks the flag and falls back cleanly: when `STRIPE_SECRET_KEY` is unset, [daras_ai_v2/billing.py#L247](https://github.com/GooeyAI/gooey-server/blob/master/daras_ai_v2/billing.py#L247) hides all plans, checkout, and payment-method UI and instead directs operators to top up credits via the Django admin. No payment provider is ever contacted. +- Background billing tasks (e.g., auto-recharge) only run for workspaces with a paid subscription, which cannot exist when payments are disabled โ€” so no code path reaches Stripe/PayPal on a self-hosted deployment. + +Credit accounting itself is fully open (rows in PostgreSQL); self-hosted operators grant credits through the Django admin. + +## 6. Image safety checker โ€” feature flag (Path 2) + +Image moderation calls Azure Content Moderator from [daras_ai_v2/safety_checker.py](https://github.com/GooeyAI/gooey-server/blob/master/daras_ai_v2/safety_checker.py), gated on `AZURE_IMAGE_MODERATION_ENDPOINT`. When the endpoint is unset โ€” the default for self-hosted deployments โ€” the check is simply skipped ([daras_ai_v2/azure_image_moderation.py#L13-L14](https://github.com/GooeyAI/gooey-server/blob/master/daras_ai_v2/azure_image_moderation.py#L13)). Text moderation runs through the LLM abstraction (any configured model, including self-hosted ones). + +## 7. Managed secrets โ€” optional feature + +The managed-secrets feature (user-supplied API keys) stores values in Azure Key Vault ([managed_secrets/models.py](https://github.com/GooeyAI/gooey-server/blob/master/managed_secrets/models.py)), gated on `AZURE_KEY_VAULT_ENDPOINT` (default unset, [daras_ai_v2/settings.py#L481](https://github.com/GooeyAI/gooey-server/blob/master/daras_ai_v2/settings.py#L481)). It is not required: self-hosted deployments pass API keys to functions as plain environment variables instead. + +## 8. Frontend assets (in progress) + +- **Font Awesome Pro** is loaded from a kit URL. Self-hosted builds will ship with Font Awesome Free (or an equivalent open icon set) bundled locally. +- **Google Tag Manager** will render only when a GTM ID is configured; unset (the default for self-hosted) means no analytics script is served. +- Static brand assets currently referenced from cloud storage URLs will be bundled with the repository. + +## 9. Optional messaging integrations + +WhatsApp, Slack, Facebook Messenger, and Twilio voice/SMS connectors let bots built on Gooey reach users on those networks. They are inherently integrations *to* proprietary platforms, are disabled unless the corresponding credentials are set, and are not required for any core functionality (the web widget, API, and web UI are fully independent of them). + +--- + +## Verifying a fully-open deployment + +The reference self-hosted stack runs with **zero proprietary services**: + +```bash +docker compose -f docker-compose.local.yml up -d +``` + +- Auth: local Django email/password (`ENABLE_FIREBASE_AUTH` unset) +- Storage: local filesystem (`GS_BUCKET_NAME` unset) +- LLM: Ollama or any OpenAI-compatible server (configured via `AIModelSpec` in the Django admin โ€” see section 4 above) +- STT/TTS/embeddings: GPU Celery worker (optional, for AI features that need it) +- Payments, analytics, cloud moderation, Key Vault: disabled (keys unset) + +Backing services: PostgreSQL, RabbitMQ, Redis 8 (AGPL-3.0 option), Vespa โ€” all open source.