Build and connect backend services

A managed backend runs your application API, account checks, database access and business logic. Use it for ordinary create/read/update/delete features, direct file-storage operations, existing container applications, or background workers. Workflows remain useful for AI, scheduled automation, ETL and durable jobs; each API endpoint does not need its own workflow.

New APIs normally start from the verified Node API starter with its repository-owned Dockerfile. Existing stacks and explicit native-runtime choices remain valid. The service is registered and managed separately from the frontend; an existing combined server-rendered app can intentionally serve both pages and API from one process.

Open System Explorer → Services → New service. The Source control offers three ways to supply the program that Rumata will run.

Source and service type are separate choices. A Web service accepts HTTP requests; a Background worker runs work without a web endpoint. Choose the runtime policy, resources, and storage for the workload, whichever source you use.

1. Select Docker image, then Choose an image.
2. Search public Docker Hub images by name or namespace. The picker also offers quick setups such as Gotenberg, NGINX, and HTTPBin.
3. Select the intended image and version tag. Review the publisher’s documentation for its HTTP port, environment variables, startup requirements, and writable directories.
4. Check Container image and the service settings after selection. You can also enter an image reference directly. Use the optional private-registry configuration when the image requires registry authentication.
5. Choose the service name, service type, runtime policy, and endpoint access. Save settings, then deploy when ready.

An image reference identifies a repository and optionally a tag, for example `namespace/image:version`. A tag is a named version that its publisher can update; a digest identifies particular image content. Prefer an explicit reviewed version over relying on a changing `latest` tag.

1. Select Native runtime. Review Backend folder, Build context, and the optional Git branch or ref. Paths are relative to the repository root.
2. Choose Node.js or Python under Native runtime, then enter an exact supported Runtime version, including its patch number.
3. Set the Build command for dependency installation and any compilation your application needs. Leave it empty only when no build is needed.
4. Set the Start command to launch the application. For a web service, listen on `0.0.0.0` and the supplied `PORT`.
5. Review environment variables, service type, HTTP port, resources, and endpoint access. For a standalone repository build, commit and push the intended source; for a coordinated factory release, review its selected source snapshot.
6. Save settings, build the intended source, then deploy its successful artifact. Read the logs and test the running service.

For Node.js, the form offers `npm ci && npm run build --if-present` and `npm start`. These commands require a compatible package file, lockfile, and start script. For Python, use installation and startup commands appropriate to your project and its dependency files; switching runtimes does not convert your application.

1. Select Dockerfile.
2. Review Backend folder, Build context, Git branch or ref, and Dockerfile path. Use paths relative to the repository root.
3. Make sure files copied by the Dockerfile are inside its build context and are not excluded by the applicable `.dockerignore`.
4. Keep dependency installation and compilation in build instructions, and configure the container’s startup command for the running application.
5. Include the Dockerfile and all required files in the selected release source. Commit and push them for a standalone repository build, or review the coordinated factory source snapshot. Save settings, deploy, and inspect the build logs.

A Dockerfile is a recipe for building an image. A Docker image source instead runs an already-built image. Native runtime builds expose language and command settings directly; Dockerfile builds put the container setup under your control.

The frontend’s `rumata.backends.json` records backend bindings. It sits in the frontend directory, for example `factories/<factory-id>/frontend/rumata.backends.json`. It connects a frontend configuration name with a service ID and the intended production and development endpoints and access modes.

1. Open Code and find `rumata.backends.json` in the frontend that should use the service.
2. Check that the binding points to the intended service. Keep development and production endpoints separate; do not replace the production endpoint with a private preview URL.
3. Make sure the frontend’s API client uses the corresponding configuration name and the authentication required by the selected endpoint access mode.
4. Include the binding with the frontend changes in the reviewed release source. Review the frontend deployment’s backend information and deploy the connected frontend and service together when Rumata requires a coordinated deployment.
5. Test the API call in private preview and on the intended deployed environment, including an unauthorized request when the API should be private.

In managed Vite preview, the binding uses a same-origin backend path with preview authorization forwarded by the runtime. It can be relative and has no trailing slash; join it with an endpoint path instead of passing it directly to new URL. A missing development backend does not silently switch to production. Prebuilt images intentionally use their deployed service because they have no working-tree development process.

1. Configure the service’s development command, a free non-reserved port, database binding and required secrets.
2. Install dependencies and start or ensure the development process. Wait for readiness, then test an application request.
3. Connect the frontend binding and complete the task through the UI. Read service logs and browser runtime errors.

Development reads working-tree files on the development machine. Production is a separate deployment. Enabling database binding normally connects both to the project database and factory schema; do not assume preview has a disposable copy of production data.

The Node API starter includes an opt-in native email/password account module backed by PostgreSQL. Enable it with the database and factory signing-key bindings when the app needs accounts. Reuse an existing sign-in system where appropriate; passwordless login, social sign-in and app-specific roles require their own implementation. See Account contracts.

Rumata resource permissions and application-user authorization are separate checks. Private development requires an authorized Rumata session. Deployed services using Rumata permissions can allow public execution; the backend must still verify app sessions and record ownership for private data. Never copy the developer’s Rumata token or a service API key into browser code.

Use PostgreSQL for relational records and managed project storage for user files. The container’s ordinary filesystem is not durable across replacement. HTTP-disabled workers cannot wake through an HTTP request; choose their runtime policy deliberately.