Skip to content

Quick-Deploy.md

Latest commit

 

History

History
197 lines (154 loc) · 7.79 KB

Quick-Deploy.md

File metadata and controls

197 lines (154 loc) · 7.79 KB
Raw

Quick Deploy

This is the short production-style deployment path for IDEA-next; use the root README.md and component READMEs when troubleshooting or changing defaults.

Prerequisites

  • A Linux host with Docker Engine, Docker Compose v2, Git, Python 3, and enough storage for persistent Docker volumes.
  • A working /dev/kvm device for the production microsandbox backend; without it, IDEA falls back to a limited local-shell backend.
  • An OpenAI-compatible API endpoint and key, plus access to the pinned Open WebUI and sandbox images in GHCR when those packages are private.
  • An external reverse proxy or load balancer that provides HTTPS and routes the instance hostname to Open WebUI on host port 3001.

Deploy

  1. Check out the desired branch on the server:

    git clone https://github.com/uhsealevelcenter/IDEA.git
cd IDEA
git checkout next-dev

  2. Create the environment file and replace every placeholder secret:

    cp example.env .env

    At minimum, set OPENAI_API_KEY, OPENAI_BASE_URL, the Postgres credentials, WEBUI_SECRET_KEY, LITELLM_DB_PASSWORD, LANGGRAPH_DB_PASSWORD, LANGGRAPH_AES_KEY, IDEA_IDENTITY_SECRET, LITELLM_MASTER_KEY, LITELLM_VIRTUAL_KEY, INTERNAL_SERVICE_TOKEN, LANGFUSE_DB_PASSWORD, NEXTAUTH_SECRET, SALT, and ENCRYPTION_KEY; set KVM_DEVICE_PATH=/dev/kvm on the production host, keep the default IDEA_CODEX_ENABLED=true when the published guest image is selected, and review SANDBOX_BACKEND, SANDBOX_IMAGE, SANDBOX_CPUS, SANDBOX_MEMORY_MB, SANDBOX_DISK_MB, ENABLE_SIGNUP, CORS_ORIGINS, registry credentials, and the model names. Blank dedicated Codex endpoint/key values currently reuse the external OPENAI_* values.

  3. Create the isolated LiteLLM, LangGraph, and Langfuse database roles, schemas, and checkpoint tables:

    ./litellm/setup_litellm_db.sh
./langgraph/db/setup_langgraph_db.sh
./langfuse/setup_langfuse_db.sh

  4. Seed the shared scientific-data volume before first use, if a legacy data tree is available:

    docker compose run --rm --build \
  --volume "/path/to/legacy/IDEA/data:/source:ro" \
  shared-data import /source
docker compose run --rm shared-data status

  5. Build and start the production service set:

    eval "$(python3 deployment/load_env.py prod)"
docker compose up -d --build
docker compose ps

    If interpreter_kernel/ changed, first build and test its guest image locally; this command never publishes anything:

    ./interpreter_kernel/test_image.sh idea/oi-kernel:research-local

    On the Linux/KVM deployment host, also test one disposable microVM through IDEA's production SDK path:

    ./interpreter_kernel/test_microsandbox_image.sh \
  idea/oi-kernel:research-local

    Only after it passes, manually run the Microsandbox image workflow with an immutable version and publish=true, then set SANDBOX_IMAGE to that versioned tag (or, preferably, its recorded digest).

  6. Open the instance, create the first Open WebUI account as the administrator, generate an API key under Settings > Account > API Keys, and save it as OPENWEBUI_API_KEY in .env.

  7. Register the IDEA Pipe and reconcile IDEA-owned Open WebUI settings and official Assistants:

    OPENWEBUI_BASE_URL=http://localhost:3001 \
  ./deployment/post_deploy/register_idea_pipe.sh
OPENWEBUI_BASE_URL=http://localhost:3001 \
  ./deployment/post_deploy/configure_openwebui.py
OPENWEBUI_BASE_URL=http://localhost:3001 \
  ./deployment/post_deploy/deploy_assistants_openwebui.py

    For an existing installation with a different Pipe function ID, set IDEA_PIPE_FUNCTION_ID in .env before registration. Production currently uses idea_terminal_agent_langgraph; preserving this ID keeps existing chat model references valid. Enable only the intended Pipe instance.

  8. Open the Langfuse UI (internal-only unless routed through your reverse proxy - see the root README.md's "LLM Observability (Langfuse)" section), create an org/project, and generate an API key pair under Project Settings > API Keys. Save them as LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY in .env (or set the LANGFUSE_INIT_* variables beforehand to skip this manual step entirely).

  9. In Admin Panel > Functions > IDEA Agent > Valves, set INTERNAL_SERVICE_TOKEN to the same value used in .env. Signup is enabled by default and new accounts enter the pending approval queue; override ENABLE_SIGNUP=false only if required. Restart the services after any .env changes:

    eval "$(python3 deployment/load_env.py prod)"
docker compose up -d

Verify

docker compose ps
curl -f http://localhost:3001/
docker compose logs \
  --tail=100 openwebui langgraph sandbox litellm

Log in through the public HTTPS URL and confirm that Welcome Assistant can answer a prompt, run Python, read an uploaded file and image, use PaperQA on attached PDF and Word documents, delegate one read-only and one workspace-write task to Codex, and return a downloadable artifact whose link still works on a later turn.

Production HTTPS

Production serves https://app.ideaxiom.org/ using the existing certificate tree in certbot/conf, which is excluded from Git. Keep the hostname, port 443, and TLS mounts configured via deployment/config.yaml (prod section). Production requires a valid certificate before nginx can start with HTTPS.

After proxy changes, validate and recreate only nginx:

docker compose run --rm --no-deps nginx nginx -t
docker compose up -d --no-deps --force-recreate nginx
curl --fail --show-error https://app.ideaxiom.org/

The production host runs the following entry in the deployment user's crontab (time is UTC); preserve other jobs when installing it on a replacement host:

17 3 * * * /bin/bash /home/exouser/IDEA/deployment/renew-production-cert.sh >> /home/exouser/idea-cert-renewal.log 2>&1

The script runs Certbot with the port-80 ACME webroot and reloads nginx after successful renewal checks. It requires Docker access and the Certbot image. The production deploy workflow verifies the public HTTPS endpoint; other environments may set HEALTHCHECK_URL and otherwise use HTTP at VM_HOST. Workflow changes take effect only after they reach GitHub.

Update or Roll Back

Fetch and check out the target ref, rerun the database setup, rebuild the Compose services, and rerun the three Open WebUI deployment scripts above; back up the named Docker volumes before migrations or rollback testing.

Do not run interpreter_kernel/refresh_sandboxes.sh as a routine deployment step: it recreates existing microVMs and wipes their writable filesystem state. During the present developer-only testing phase, a deliberately fresh start can be performed with --allow-destructive-developer-refresh. Before IDEA admits non-developer users, implement and rehearse a snapshot/restore workspace migration; the destructive refresh is not an acceptable user rollout strategy.

The GitHub Actions workflow maps next-dev to the GitHub Environment of the same name. Automatic deployment still requires that environment's DEPLOY_ENABLED=true, SSH and app-directory values, deployment command, DNS/TLS route, and smoke-check URL to be configured.

The next-dev environment uses deployment/config.yaml (next-dev section), which publishes nginx over HTTP without mounting the production certificate tree. The production environment continues to use deployment/config.yaml (prod section). The deployment commands for all environments are managed in deployment/deploy.sh and executed automatically by .github/workflows/deploy.yml:

./deployment/deploy.sh next-dev