# Openship DockerRuntime vs BareRuntime: A Complete Technical Comparison

> Compare Openship DockerRuntime vs BareRuntime to understand containerized isolation versus native host execution for your services. Choose the right runtime for your project.

- Repository: [oblien/openship](https://github.com/oblien/openship)
- Tags: deep-dive
- Published: 2026-08-19

---

**Openship executes services using either DockerRuntime for containerized isolation or BareRuntime for native host execution, with the mode determined by the `runtime` field in [`packages/db/src/schema/project.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/project.ts) or inferred from project files.**

Openship is an open-source deployment platform that abstracts service execution through dual runtime strategies. Understanding the difference between **DockerRuntime** and **BareRuntime** is essential for optimizing resource utilization and deployment flexibility in production environments. This guide examines the implementation details, configuration schema, and operational characteristics of both runtimes as defined in the `oblien/openship` repository.

## Core Runtime Concepts

Openship defines two distinct execution environments in its type system and database layer. Each runtime offers different trade-offs between isolation, performance, and operational complexity.

### DockerRuntime Definition

The **DockerRuntime** executes services via the Docker daemon, providing full containerization with isolated filesystems, network stacks, and resource constraints. In [`packages/core/src/types.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/types.ts), the runtime is represented by the enum value `"docker"` at line 73. This mode handles image resolution, health checks, and container lifecycle management through Docker's API.

### BareRuntime Definition

The **BareRuntime** executes services as native operating system processes directly on the host. Represented by the enum value `"bare"` (or `"none"` in legacy code) in [`packages/core/src/types.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/types.ts), this mode bypasses containerization entirely. The platform spawns the process using the resolved command line—often derived from `scripts.start`—without Docker daemon involvement.

## Runtime Selection Logic

Openship determines which runtime to use through a hierarchical decision process defined in the project configuration and database schema.

### Explicit Configuration

The primary selection mechanism is the `runtime` column in [`packages/db/src/schema/project.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/project.ts) at line 183. Valid values are explicitly stored as `"docker"` or `"bare"`. When set to `"docker"`, the platform activates Docker-specific validation and image resolution workflows. When set to `"bare"`, Openship skips container-related checks and prepares for direct process execution.

### Implicit Detection

If the configuration omits the `runtime` field, Openship infers the runtime from project artifacts. Presence of a `Dockerfile` or Docker Compose definition triggers DockerRuntime selection, while projects lacking these descriptors default to BareRuntime.

## Database Schema and Type System

The distinction between runtimes permeates Openship's data layer and core type definitions.

### Project Schema Storage

In [`packages/db/src/schema/project.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/project.ts), the `runtime` column stores the execution mode as a string literal. Docker-specific fields include:

- `build_image`: The image used for compilation (line 183-191)
- `runtime_image`: The execution environment image
- `docker_healthcheck`: Container health check configuration (line 117)

These columns are only relevant when `runtime` equals `"docker"`.

### Type Safety

The [`packages/core/src/types.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/types.ts) file enumerates allowed runtime strings at line 73, providing compile-time validation that prevents invalid runtime specifications from entering the database.

## Deployment Flow Comparison

The execution path diverges significantly based on the selected runtime, with distinct resolution and spawning mechanisms.

### DockerRuntime Deployment

When `runtime` is `"docker"`, Openship follows this sequence:

1. **Image Resolution**: Calls `stacks.getResolvedDockerRuntimeImage` (defined in [`packages/core/src/stacks.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/stacks.ts) at line 1091) to determine the correct container image
2. **Artifact Handling**: Pulls or pushes images to the configured registry
3. **Container Execution**: Issues `docker run` commands with configured options, ports, and resource limits

The `project.build_image` and `project.runtime_image` fields drive the build and execution phases respectively.

### BareRuntime Deployment

For BareRuntime, the workflow eliminates containerization:

1. **Command Resolution**: Parses the entry point from project scripts or configuration
2. **Process Spawning**: Uses the Openship runtime manager to spawn the process directly on the host OS
3. **Execution Monitoring**: Attaches to stdout/stderr streams without Docker abstraction

## Operational Characteristics

Each runtime manages service health, resources, and failures through different mechanisms.

### Health Checking

**DockerRuntime** utilizes Docker-specific health checks stored in the `docker_healthcheck` column ([`packages/db/src/schema/project.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/project.ts) line 117). The Docker daemon enforces these checks automatically.

**BareRuntime** relies on platform-level monitoring through systemd integration or custom status scripts. No Docker health-check abstraction is applied; the platform monitors process existence and exit codes directly.

### Resource Limits

**DockerRuntime** enforces constraints through Docker Compose definitions (`mem_limit`, `cpu_quota`) translated into Docker daemon parameters.

**BareRuntime** applies limits declared in the project's `resources` section using host-level mechanisms such as cgroups or `ulimit` configurations managed by the Openship orchestrator.

### Failure Handling

In [`packages/core/src/service-status.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/service-status.ts) at line 48, DockerRuntime maps container-specific statuses (`restarting`, `paused`, `exited`) to Openship's generic service status model.

BareRuntime surfaces process exit codes and terminal output directly to the Openship monitor without translation through Docker state abstractions.

## Configuration Examples

### Selecting Runtime in Configuration

```yaml

# openship-config.yaml - Explicit Docker selection

runtime: docker
build_image: node:22
runtime_image: node:22-alpine
docker_healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  interval: 30s

```

```yaml

# openship-config.yaml - Bare runtime explicit

runtime: bare
resources:
  memory_limit: "512m"
  cpu_limit: "1.0"

```

### Runtime-Aware Service Launch

```typescript
// packages/core/src/launch.ts
import { startDockerService } from "./docker";
import { startBareService } from "./bare";

async function launchService(project) {
  if (project.runtime === "docker") {
    // Uses packages/core/src/stacks.ts resolution logic
    await startDockerService(project);
  } else {
    // Direct process spawn without Docker daemon
    await startBareService(project);
  }
}

```

### Reading Runtime from Database

```typescript
// Querying the runtime schema
import { db } from "@openship/db";
import { Project } from "@openship/db/schema";
import { eq } from "drizzle-orm";

async function getRuntime(projectId: string) {
  const proj = await db
    .select()
    .from(Project)
    .where(eq(Project.id, projectId))
    .then(rows => rows[0]);

  // Returns "docker" or "bare" per packages/core/src/types.ts
  return proj.runtime;
}

```

## Summary

- **DockerRuntime** provides containerized isolation using Docker daemon management, image-based deployments, and Docker-specific health checks defined in [`packages/db/src/schema/project.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/project.ts).
- **BareRuntime** executes native processes directly on the host OS, bypassing containerization for improved performance and reduced overhead.
- **Runtime selection** occurs via the `runtime` column in the database schema or implicit detection of Docker descriptors in the project root.
- **Image resolution** for Docker uses `getResolvedDockerRuntimeImage` in [`packages/core/src/stacks.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/stacks.ts), while Bare runtimes resolve entry point commands from project scripts.
- **Status mapping** differs by runtime: Docker states translate through [`packages/core/src/service-status.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/service-status.ts), while Bare processes report exit codes directly.

## Frequently Asked Questions

### How does Openship decide between DockerRuntime and BareRuntime?

Openship checks the `runtime` field in the project configuration stored in [`packages/db/src/schema/project.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/project.ts). If the field is `"docker"`, it uses containerization; if `"bare"`, it runs native processes. When unspecified, Openship infers the runtime from the presence of a `Dockerfile` or Docker Compose files in the project repository.

### Can I use Docker for builds but BareRuntime for execution?

Yes. The schema in [`packages/db/src/schema/project.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/project.ts) separates `build_image` from `runtime` configuration. You can specify a Docker image for building artifacts while setting `runtime: "bare"` to execute the compiled binary directly on the host, bypassing container runtime overhead.

### What happens to health checks when using BareRuntime?

BareRuntime ignores Docker-specific health check configurations stored in the `docker_healthcheck` column. Instead, Openship relies on external process monitoring, systemd integration, or custom status scripts to detect service availability and restart failed processes.

### Where are the runtime type definitions located in the source code?

The core type definitions reside in [`packages/core/src/types.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/types.ts) at line 73, which exports the runtime enum containing `"docker"` and `"bare"` values. The database schema enforcing these types is located in [`packages/db/src/schema/project.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/project.ts), specifically around line 183 where the `runtime` column is defined with validation constraints.