The Difference Between Compose Mode and Bare Mode Deployment in Openship

Openship runs in Compose mode as Docker containers with PostgreSQL and OpenResty, or in Bare mode as host processes using SQLite, automatically selecting based on Docker availability or explicit CLI flags.

The oblien/openship repository supports two fundamentally different runtime strategies to accommodate diverse infrastructure constraints. Understanding the difference between compose mode and bare mode deployment in Openship determines whether your services run as isolated containers or as native processes on the host machine. Your choice affects database selection, TLS termination architecture, and resource isolation boundaries.

Runtime Architecture: Containers vs Host Processes

Openship’s deployment modes represent a architectural trade-off between container isolation and host-native execution.

Compose Mode (Docker Stack)

In Compose mode, Openship orchestrates all services as Docker containers defined in docker/docker-compose.yml. This stack includes PostgreSQL for persistence, Redis for caching, the API and dashboard services, and an OpenResty edge proxy configured with network_mode: host to bind directly to ports 80 and 443. The runtime configuration in packages/core/src/runtime-config.ts defines this as the "docker" deploy mode, which provides clear process boundaries and simplifies individual component upgrades.

Bare Mode (Host Processes)

Bare mode launches services as ordinary host processes using process managers like pm2, systemd, or nohup. Instead of containerized PostgreSQL, the platform uses an embedded SQLite database accessed through the schema definitions in packages/db/src/schema/project.ts where RuntimeMode is stored as "bare". The OpenResty edge proxy installs directly onto the host at /usr/local/openresty and runs without containerization, though it still manages TLS certificates.

Automatic Mode Selection Logic

Openship determines the deployment strategy through runtime detection logic implemented in scripts/install.sh and packages/core/src/runtime-config.ts.

When you execute openship up, the CLI checks for Docker presence on Linux systems. If detected, it defaults to Compose mode; otherwise, it falls back to Bare mode. This behavior is documented in the Korean quick-start guide (docs/i18n/README.ko.md, lines 91-95), which states that Compose mode is the default on Docker-enabled Linux, while Bare mode serves macOS, Windows, and Docker-less environments.

You can override automatic selection using explicit flags:

# Force Compose mode (requires Docker)

openship up --compose

# Force Bare mode (no Docker required)

openship up --bare

Database and Edge Proxy Differences

The deployment mode fundamentally changes how Openship handles persistence and edge routing.

• Database: Compose mode relies on external PostgreSQL containers, while Bare mode uses SQLite embedded within the application process. The schema in packages/db/src/schema/project.ts accommodates both backends through the RuntimeMode enum.
• Edge Proxy: In Compose mode, OpenResty runs inside a container with automatic Let’s Encrypt certificate management. In Bare mode, OpenResty operates as a host process with TLS still provisioned, but without the container abstraction layer.

Resource Requirements and Use Cases

Each mode targets specific operational environments.

Compose mode requires Docker installation and suits team environments needing push-to-deploy workflows on VPS or dedicated servers. The container isolation in docker/docker-compose.yml enables independent scaling of the database and application tiers.

Bare mode requires no Docker infrastructure, making it ideal for personal development on macOS or Windows, and for bare-metal servers where container runtime installation is undesirable. All services share the host process space, reducing overhead but eliminating container-level isolation boundaries.

Practical Deployment Commands

Deploy the full container stack manually without the CLI:

git clone https://github.com/oblien/openship.git && cd openship
cp .env.example .env
docker compose --env-file .env -f docker/docker-compose.yml up -d

Verify Bare mode edge proxy operation:

# After running openship up --bare

ps aux | grep openresty

The runtime configuration at line 76 of packages/core/src/runtime-config.ts validates these modes as part of the deploy/build mode (docker | bare | cloud | desktop) enumeration.

Summary

• Compose mode runs PostgreSQL, Redis, and OpenResty as Docker containers with full process isolation.
• Bare mode executes services as host processes using SQLite and a bare-metal OpenResty installation.
• Selection method: Automatic detection via scripts/install.sh, overridable with --compose or --bare flags.
• Database: PostgreSQL in Compose mode versus SQLite in Bare mode.
• Edge proxy: Containerized OpenResty (Compose) versus host-installed OpenResty (Bare).

Frequently Asked Questions

Can I switch from Bare mode to Compose mode without losing data?

Migrating between modes requires manual database transfer because Compose mode uses PostgreSQL while Bare mode uses SQLite. You must export your SQLite data and import it into PostgreSQL before switching, as the schema definitions in packages/db/src/schema/project.ts handle different backends but do not automatically synchronize data between them.

Does Bare mode support TLS certificates like Compose mode?

Yes, Bare mode provides TLS termination through the host-installed OpenResty instance at /usr/local/openresty. While the implementation differs from the containerized approach in docker/docker-compose.yml, the Bare mode edge proxy still provisions and renews Let’s Encrypt certificates automatically.

Why does Openship use SQLite in Bare mode but PostgreSQL in Compose mode?

SQLite requires no external service configuration, making it ideal for Bare mode’s zero-dependency philosophy on macOS, Windows, or minimal Linux hosts. PostgreSQL in Compose mode leverages existing container infrastructure to provide concurrent connection handling and advanced database features suitable for production multi-user environments.

Is Compose mode more secure than Bare mode?

Compose mode offers stronger process isolation through Docker’s container boundaries, preventing service-to-service privilege escalation at the kernel level. Bare mode runs all services in the host process space, requiring reliance on operating system-level security controls rather than container abstraction, though both modes implement TLS encryption and authentication checks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}