Personal AI, On Personal Devices
Python
chore(deploy): add Render Blueprint for the FastAPI server (#305)
AlienCatGirl5990244a05ee
diff --git a/deploy/docker/Dockerfile b/deploy/docker/Dockerfileindex 177f5ac7..c7cf2adc 100644--- a/deploy/docker/Dockerfile+++ b/deploy/docker/Dockerfile@@ -80,5 +80,8 @@ USER openjarvisEXPOSE 8000+# Keep `jarvis` as the image entrypoint so Docker and Compose command overrides+# remain subcommands (for example, `docker run IMAGE serve ...`). Platforms+# such as Render replace CMD while preserving this entrypoint.ENTRYPOINT ["jarvis"]CMD ["serve", "--host", "0.0.0.0", "--port", "8000"]diff --git a/docs/deployment/api-server.md b/docs/deployment/api-server.mdindex d167d6e0..72e0bf3d 100644--- a/docs/deployment/api-server.md+++ b/docs/deployment/api-server.md@@ -18,6 +18,10 @@ Start with default settings:jarvis serve```+For a cloud-hosted example, see [Deploy on Render](render.md). Its free-tier+Blueprint is intended for evaluation only because local OpenJarvis state is+ephemeral.+The server reads defaults from `~/.openjarvis/config.toml` and auto-detects available engines and models. Override any option via CLI flags:```bashdiff --git a/docs/deployment/render.md b/docs/deployment/render.mdnew file mode 100644index 00000000..be6e912c--- /dev/null+++ b/docs/deployment/render.md@@ -0,0 +1,45 @@+# Deploy on Render++The repository's `render.yaml` is a minimal Render Blueprint for the+OpenJarvis API server. It builds `deploy/docker/Dockerfile`, binds the server to+Render's default web-service port (`10000`), and uses OpenAI's `gpt-4o-mini`+through the cloud engine.++## Create the service++1. Open Render's **New Blueprint Instance** flow and select your OpenJarvis+ fork.+2. Provide `OPENAI_API_KEY` when Render asks for the Blueprint secret.+3. Apply the Blueprint and wait for `/health` to become healthy.+4. Retrieve the generated `OPENJARVIS_API_KEY` from the Render dashboard and+ send it as `Authorization: Bearer <key>` with API requests.++The Blueprint pins both the `PORT` environment variable and the server's+`--port` argument to `10000`. Render's Docker command does not expand `$PORT`,+so if you customize the service port, update both values in `render.yaml`.++The Blueprint deliberately requires one provider key. Render treats every+`sync: false` environment variable as an input during initial creation, so+listing every optional cloud provider would incorrectly require credentials+for all of them. To use another provider, install its corresponding OpenJarvis+inference extra in the image, change `--model` to a model that provider serves,+and replace the secret in your own Blueprint.++## Storage and free-instance limits++!!! warning "Free instances do not preserve OpenJarvis data"+ Render's free web-service filesystem is ephemeral. Everything written to+ `/home/openjarvis/.openjarvis` — including configuration, credentials,+ connector tokens, local databases, and learned state — is lost whenever+ the service restarts, spins down, or redeploys. Free instances also spin+ down after periods without inbound traffic and are not suitable for+ production or durable personal-assistant state.++For durable state, upgrade the service to a paid instance and attach a+persistent disk at `/home/openjarvis/.openjarvis`, or configure the relevant+feature to use an external managed datastore. Only data below a persistent+disk's mount path survives a restart; attaching a disk elsewhere does not+preserve the default OpenJarvis home.++The Blueprint intentionally does not declare a disk because Render does not+support persistent disks on free services.diff --git a/render.yaml b/render.yamlnew file mode 100644index 00000000..2477ec3a--- /dev/null+++ b/render.yaml@@ -0,0 +1,47 @@+# Render Blueprint for the OpenJarvis FastAPI server.+# Deploys src/openjarvis/server/app.py via deploy/docker/Dockerfile.+# Apply at: https://dashboard.render.com/blueprint/new?repo=https://github.com/open-jarvis/OpenJarvis+services:+ - type: web+ name: openjarvis-server+ runtime: docker+ plan: free+ region: oregon+ dockerfilePath: ./deploy/docker/Dockerfile+ dockerContext: .+ # Override the Dockerfile CMD while preserving its `jarvis` entrypoint.+ # Render's default web-service port is 10000. Pin PORT and the CLI argument+ # to that same value because Docker commands do not interpolate `$PORT`.+ # Pin a cloud model as well as the engine. The repository's default model+ # is local-only, so omitting this would make `jarvis serve` reject the+ # otherwise healthy cloud engine during startup.+ dockerCommand: serve --host 0.0.0.0 --port 10000 --engine cloud --model gpt-4o-mini+ healthCheckPath: /health+ autoDeploy: true+ envVars:+ # Force the cloud engine path. The free Render plan has no GPU and the+ # bundled local backends (Ollama/vLLM) cannot run here. The command above+ # selects the OpenAI-backed cloud engine and a model it can serve.++ # Keep Render's expected public port aligned with the fixed Docker+ # command above. Change both values together when customizing the port.+ - key: PORT+ value: "10000"++ # Auth for the OpenJarvis API itself. Required because the server refuses+ # to bind to a non-loopback host without an API key (check_bind_safety).+ - key: OPENJARVIS_API_KEY+ generateValue: true++ # Required at initial Blueprint creation. Render's `sync: false` fields+ # are operator-supplied secrets; using one provider here keeps the+ # one-click contract deterministic instead of incorrectly requiring a+ # key for every supported cloud provider.+ - key: OPENAI_API_KEY+ sync: false++ # The free service filesystem is ephemeral. OpenJarvis state under this+ # directory is lost on every restart, spin-down, or deploy. See+ # docs/deployment/render.md before storing credentials or durable state.+ - key: OPENJARVIS_HOME+ value: /home/openjarvis/.openjarvisdiff --git a/tests/deploy/test_render_blueprint.py b/tests/deploy/test_render_blueprint.pynew file mode 100644index 00000000..cf60c75d--- /dev/null+++ b/tests/deploy/test_render_blueprint.py@@ -0,0 +1,157 @@+"""Render Blueprint stays aligned with settings the server consumes."""++import json+import shlex+import subprocess+from pathlib import Path++import yaml++from openjarvis.cli.serve import serve++RENDER_BLUEPRINT = Path(__file__).resolve().parents[2] / "render.yaml"+RENDER_DOC = Path(__file__).resolve().parents[2] / "docs/deployment/render.md"+DOCKERFILE = Path(__file__).resolve().parents[2] / "deploy/docker/Dockerfile"+++def _service() -> dict:+ blueprint = yaml.safe_load(RENDER_BLUEPRINT.read_text(encoding="utf-8"))+ assert set(blueprint) == {"services"}+ assert len(blueprint["services"]) == 1+ return blueprint["services"][0]+++def _env_vars(service: dict) -> dict[str, dict]:+ return {item["key"]: item for item in service["envVars"]}+++def _docker_json_instruction(name: str) -> list[str]:+ prefix = f"{name} "+ instructions = [+ line.removeprefix(prefix)+ for line in DOCKERFILE.read_text(encoding="utf-8").splitlines()+ if line.startswith(prefix)+ ]+ assert len(instructions) == 1+ value = json.loads(instructions[0])+ assert isinstance(value, list)+ assert all(isinstance(item, str) for item in value)+ return value+++def _run_fake_jarvis(tmp_path: Path, argv: list[str]) -> list[str]:+ """Run an argv assembled with Docker's exec-form ENTRYPOINT semantics."""+ fake_jarvis = tmp_path / "jarvis"+ fake_jarvis.write_text(+ "#!/bin/sh\nprintf '%s\\0' \"$@\"\n",+ encoding="utf-8",+ )+ fake_jarvis.chmod(0o755)+ completed = subprocess.run(+ [str(fake_jarvis), *argv[1:]],+ check=True,+ capture_output=True,+ )+ return completed.stdout.rstrip(b"\0").decode().split("\0")+++def test_render_selects_cloud_engine_through_the_serve_cli(tmp_path: Path) -> None:+ service = _service()+ command = service["dockerCommand"]+ assert "$" not in command+ assert "/bin/sh" not in command++ # Render replaces CMD but preserves the image's exec-form ENTRYPOINT.+ # Exercise the resulting argv without starting a real server.+ argv = [*_docker_json_instruction("ENTRYPOINT"), *shlex.split(command)]+ args = _run_fake_jarvis(tmp_path, argv)++ assert args == [+ "serve",+ "--host",+ "0.0.0.0",+ "--port",+ "10000",+ "--engine",+ "cloud",+ "--model",+ "gpt-4o-mini",+ ]+ parsed = serve.make_context("serve", args[1:])+ assert parsed.params["host"] == "0.0.0.0"+ assert parsed.params["port"] == 10000+ assert parsed.params["engine_key"] == "cloud"+ assert parsed.params["model_name"] == "gpt-4o-mini"+ assert "OPENJARVIS_ENGINE" not in _env_vars(service)+ assert _env_vars(service)["PORT"] == {"key": "PORT", "value": "10000"}+++def test_docker_and_compose_command_overrides_remain_jarvis_subcommands(+ tmp_path: Path,+) -> None:+ entrypoint = _docker_json_instruction("ENTRYPOINT")+ default_command = _docker_json_instruction("CMD")+ compose_override = [+ "serve",+ "--host",+ "0.0.0.0",+ "--port",+ "9000",+ "--model",+ "qwen3:8b",+ ]++ assert entrypoint == ["jarvis"]+ assert default_command == [+ "serve",+ "--host",+ "0.0.0.0",+ "--port",+ "8000",+ ]+ assert (+ _run_fake_jarvis(tmp_path, [*entrypoint, *default_command]) == default_command+ )+ assert (+ _run_fake_jarvis(tmp_path, [*entrypoint, *compose_override]) == compose_override+ )+++def test_render_does_not_advertise_an_unconsumed_cors_variable() -> None:+ assert "OPENJARVIS_CORS_ORIGINS" not in _env_vars(_service())+++def test_render_public_bind_generates_an_api_key() -> None:+ env = _env_vars(_service())++ assert env["OPENJARVIS_API_KEY"] == {+ "key": "OPENJARVIS_API_KEY",+ "generateValue": True,+ }+++def test_render_contract_requires_one_supported_cloud_provider() -> None:+ service = _service()+ env = _env_vars(service)++ assert service["runtime"] == "docker"+ assert service["dockerfilePath"] == "./deploy/docker/Dockerfile"+ assert service["healthCheckPath"] == "/health"+ assert env["OPENAI_API_KEY"] == {"key": "OPENAI_API_KEY", "sync": False}+ # Every sync:false entry is mandatory during initial Blueprint creation.+ assert [+ item["key"] for item in service["envVars"] if item.get("sync") is False+ ] == ["OPENAI_API_KEY"]+++def test_render_free_tier_ephemeral_storage_is_explicitly_documented() -> None:+ service = _service()+ env = _env_vars(service)+ docs = RENDER_DOC.read_text(encoding="utf-8").lower()++ assert service["plan"] == "free"+ assert "disk" not in service+ assert env["OPENJARVIS_HOME"]["value"] == "/home/openjarvis/.openjarvis"+ assert "ephemeral" in docs+ assert "lost" in docs+ assert "persistent disk" in docs