Services and releases
Build several services from one repository and deploy them together as one project.
A project can contain several services: for example, a Next.js frontend, an API and a private Worker. A release records their source, deployments, public routes, private connections and resource assignments together. Every service must finish building and pass validation before the release can be published. If any member fails, the previous release keeps serving.
Configure services in a file
Place a configuration file in the root directory selected in Settings › Git. Arkor reads
the first existing file in this order: upwind.config.ts, upwind.jsonc, upwind.json,
arkor.config.ts, arkor.jsonc, arkor.json. Files are not merged, and vercel.json does not
declare services. Existing cron and Function settings can stay in the same file.
export default {
services: {
primaryService: 'main',
defaultService: 'main',
members: [
{
slug: 'main',
rootDirectory: 'apps/web',
bindings: [{ name: 'API', targetService: 'api' }],
},
{
slug: 'api',
rootDirectory: 'apps/api',
routes: [{ pathPrefix: '/api' }],
resourceBindings: [{ resource: 'PROJECT_DB', name: 'DB' }],
},
],
},
};Member directories are relative to the repository, even when the configuration is in a subdirectory.
Repository access and branch settings come from the connected project. The primary service keeps
its existing identity; its omitted directory and commands use the Git settings. Other members
default to directory . and detected install/build commands. name, runtime and container
accept the same settings as the dashboard.
Connections use the target's slug. Resource assignments use the existing project's binding name
in resource, and the name exposed to this service in name; the file does not create resources.
For a Durable Object or Cloudflare Workflow implementation, set
resourceOwners: { ROOMS: 'api' } inside services, and assign that resource to its implementation
service. defaultService selects unmatched public requests; omitted, it uses the primary service.
The primary service must be included in members.
For each field, an explicit dashboard setting wins over the file, which wins over the default.
Changing only a name leaves the file's routes and connections inherited. Lists replace the whole
list, including an explicit empty list. A command of null selects automatic detection. Existing
saved settings remain explicit overrides when this feature is enabled; clear a field's dashboard
override checkbox to inherit its repository value or default. Deleting a file-defined service saves an exclusion, so the file
cannot silently recreate it; restore it in the dashboard when needed. Environment variables and
secrets remain in the dashboard and are not accepted in this section.
Arkor evaluates the selected file at the deployment's fixed commit in a separate preparation build. JSON and JSONC need no dependency installation; TypeScript can import installed project dependencies and export an object or a synchronous/asynchronous function returning one. Evaluation is limited to 30 seconds and the returned service configuration to 256 KiB. Preparation uses additional build time and usage. It receives the captured primary build environment, before service resources are resolved; configuration should not call managed resource bindings. Invalid configuration fails the release while the previous release continues serving.
The graph and environment values are fixed for the attempt. Resume and rollback do not reevaluate the file, and previews never replace the production dashboard's repository configuration. The dashboard labels the commit supplying its repository values; these can describe a prepared release that has not finished building. Serving requests never read or evaluate this configuration.
Add a service
- Connect the project's Git repository in Settings › Git.
- Open Settings › Services and choose Add service.
- Give the service a name and identifier. Set its root directory, such as
apps/api, and any install or build command overrides. Empty commands use framework detection. - Save the service. New services are private by default.
Services currently build from the project's connected repository. Each service has its own source identity and build settings; the release captures those settings separately. Supported frameworks and native Workers use the same service model.
After changing the repository in Git settings, open each additional service and choose Use the current project repository, then save. Reconnecting keeps its root directory and install/build command overrides.
Public routes and the default service
Choose the Default public service for requests without a matching public route. The existing service remains the default until you change it. Project domains belong to the project; a service route selects which member answers a request on those domains.
Add a public route to expose another service. A hostname is optional; leave it empty to match all
project domains. Routes with an exact hostname take priority over routes without a hostname.
Within that priority, the longest path prefix wins. Prefixes match complete path segments:
/api matches /api and /api/orders, but not /apiculture.
Enter prefixes in URL pathname form, such as /caf%C3%A9. Literal Unicode, spaces, and . or
.. path segments are rejected. Prefixes are matched without decoding or rewriting them.
The request path is preserved. A Next.js service mounted at /docs must be built with
basePath: '/docs'. An assetPrefix alone does not make Next.js routes work under that path.
Use distinct, publicly reachable asset paths when several Next.js applications share a hostname.
See the current Next.js basePath reference
and multi-zones guide.
An ordinary project with one public Next.js service keeps its direct delivery path. Service configuration is compiled during deployment; serving a request does not query project settings or discover the private service graph.
Private communication
Add a Private service connection on the calling service. Select its target service and a
binding name such as ORDERS. The target can remain private, without a public route.
In a Worker, use the native binding:
export default {
async fetch(request: Request, env: { ORDERS: Fetcher }) {
return env.ORDERS.fetch('https://orders.internal/orders');
},
};In a Next.js server route or other application code using the SDK:
import { service } from '@stayingupwind/sdk/service';
export async function GET() {
const orders = service('ORDERS');
if (orders === undefined) return new Response('Unavailable', { status: 503 });
return orders.fetch('https://orders.internal/orders');
}The SDK returns the native Fetcher; reading it makes no request. Only declared connections
grant access. Each release pins its target deployments, so a retained release never starts
calling the newer API accidentally. See Cloudflare service bindings.
When an older release has running workflows, its runtimes and resource assignments stay available together until all its workflows finish. There is no retirement time limit on unfinished Workflow SDK runs, including runs waiting on a timer or webhook. Completed, failed and cancelled run history still has its existing 30-day retention. Expired public URLs stay withdrawn while those private connections remain available.
Older Workflow SDK registrations without complete admission tracking may keep their runtimes and resources after the listed runs finish, because an empty list cannot prove that no admitted work remains. Re-registering the deployment does not remove that protection. These resources are still removed when an explicitly deleted project is purged.
Environment and resources
Project environment variables are shared defaults. Open a service's Environment overrides to replace individual names for that service. Deleting an override reveals the shared default again. Build and runtime environments use the same merge. Stored secrets are never shown.
Create resources in the project's Bindings page, then assign them to the services that need access. An assignment uses the resource's identity and the service's chosen binding name, so several services can share one database or use separate databases. An unassigned service has no access to the resource.
For a Durable Object resource, choose one implementation owner. That service supplies the class module; all services requiring its namespace must also be assigned the resource. Ownership and assignments are recorded in the release.
Deploy and restore
The Deployments page shows Git deployments as releases, including projects with one service. Choose Deploy all services to build a production or preview release from a fixed commit. Open the release to see every member's status and build log. Existing deploy-on-push and manual Git deployment actions also deploy the complete group.
Direct bundle uploads remain available for a single service using its default configuration. Uploads return a conflict if the service has public routes, private connections, production environment overrides, resource aliases or unassigned production resources. Deploy from the project source to use these settings. Previously sealed deployments keep their original bindings when retried or restored.
Every service build uses the project's and repository installation's shared build allowance. Additional builds wait for capacity for up to one hour per service. Restoring saved artifacts does not use this allowance.
The public pointer changes only after every member is prepared and validated. A service build or validation failure does not publish a partial release. Restoring a retained release restores the entire original graph: deployments, routes, default service, private connections and resource assignments. Service settings edited since that release do not change its snapshot.
Scheduled jobs
Each service can declare its own cron jobs. Native Workers read
triggers.crons from their Wrangler configuration and invoke scheduled() with that service's
deployment, environment overrides and assigned resources. A private service needs no public route
to run a scheduled handler. HTTP jobs keep their existing path-based declarations.
Jobs become active together when the production release is published, and restoring a retained release restores its schedules. Preview releases do not register jobs. The project-wide limit of 100 jobs applies across services; each invocation has a five-minute limit without retries. Scheduling a private Worker does not change the visitor delivery path of a public Next.js service.
Container HTTP services
Select Container HTTP service in the service's runtime field. Choose either a Dockerfile
inside the connected repository or an existing public Docker Hub/GHCR image. Use a fully qualified
reference such as docker.io/library/nginx:alpine. Dockerfile and build-context paths
are relative to the service's root directory; . selects that directory as the build context.
The image must support linux/amd64. Dockerfile build archives are limited to 2 GiB; the
unpacked image must also fit the selected instance disk.
Set the listening port, instance size, maximum running instances and idle timeout. New
configuration starts with one lite instance at most, port 8080 and a 300-second idle timeout.
Images are resolved to an immutable digest during deployment. An image tag changing later does
not change a retained release.
Container services are private by default. Add a private connection on the calling service and
use service('YOUR_BINDING') as described above. Public routes and the default public service
work the same way as for Workers. Requests preserve their path, method, body and streaming
response. WebSocket upgrades are forwarded. Startup preparation has a deadline; a request that
has already reached the application is not automatically replayed.
Each HTTP service deployment has its own container application and namespace. A failed build or preparation leaves the current release serving; restoring a release restores its original image and connections. Production, branch previews and validation use isolated applications. Container files are ephemeral. Store persistent data outside the container.
A Next.js frontend keeps its existing edge delivery path. Adding a private container does not put container startup or control-plane queries ahead of static assets, cached responses or PPR shells. Only requests that explicitly call the container wait for it.
Arkor meters container runtime usage separately from Workers and Durable Objects. Budget pauses stop running containers and prevent new starts until resumed. Images required by retained releases remain available until those releases are retired.
For a user-controlled container lifecycle and named instances, use a Container-backed Durable Object.
A managed HTTP container can call its declared private services using plain HTTP. Each connection
binding name is available as an environment variable containing its private URL; for example,
ORDERS points to the Orders service in the same release.
Native JavaScript resource bindings require Worker code; use a custom Container-backed Durable
Object to access those resources.