Skip to content

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/Dockerfile
index 177f5ac7..c7cf2adc 100644
--- a/deploy/docker/Dockerfile
+++ b/deploy/docker/Dockerfile
@@ -80,5 +80,8 @@ USER openjarvis
EXPOSE 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.md
index 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:
```bash
diff --git a/docs/deployment/render.md b/docs/deployment/render.md
new file mode 100644
index 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.yaml
new file mode 100644
index 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/.openjarvis
diff --git a/tests/deploy/test_render_blueprint.py b/tests/deploy/test_render_blueprint.py
new file mode 100644
index 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