# How to Set Up a Development Environment for oblien/openship: A Complete Guide

> Set up your oblien openship development environment easily. Follow our guide for cloning, installing dependencies, configuring Docker, and launching services for efficient development.

- Repository: [oblien/openship](https://github.com/oblien/openship)
- Tags: how-to-guide
- Published: 2026-07-29

---

**Clone the repository, install Node.js 20+ and pnpm, copy `.env.example` to `.env`, run `pnpm install`, start the Docker Compose stack with `docker compose -f docker/docker-compose.yml up -d`, and launch individual services using `pnpm --filter` commands.**

The oblien/openship repository is a TypeScript-based monorepo that orchestrates multi-cloud deployments through a unified interface. Setting up a development environment for oblien/openship requires configuring pnpm workspaces, Docker containers for PostgreSQL and Redis, and environment variables defined in `.env.example`. This guide walks through the exact steps to configure your local machine based on the project's actual source structure and dependencies.

## Prerequisites and System Requirements

Before cloning the repository, ensure your system meets the following specifications defined in the source configuration:

- **Node.js ≥20** – The version is pinned in `.nvmrc` at the repository root. Use a version manager like `nvm` to match this exactly.
- **pnpm** – The package manager for the workspace. Install globally with `npm i -g pnpm`.
- **Docker & Docker Compose** – Required to run the PostgreSQL database, Redis cache, and API services locally.

## Repository Architecture Overview

Understanding the workspace structure helps navigate the development environment. The project uses [`pnpm-workspace.yaml`](https://github.com/oblien/openship/blob/main/pnpm-workspace.yaml) to define package boundaries across multiple logical layers:

- **`apps/web`** – Vite-based React frontend with Tailwind CSS, accessible at `http://localhost:3000`
- **`apps/api`** – Fastify server exposing the public API at `http://localhost:4000`
- **`apps/desktop`** – Electron-based desktop client sharing UI components with the web app
- **`packages/db`** – Prisma schema and database migration scripts
- **`packages/adapters`** – Plugin system for cloud providers (AWS, GCP, Azure)
- **`packages/core`** – Shared TypeScript types and service-layer abstractions

## Step-by-Step Development Environment Setup

### 1. Clone the Repository and Install Dependencies

Start by cloning the repository and installing workspace dependencies:

```bash
git clone https://github.com/oblien/openship.git
cd openship
pnpm install

```

The `pnpm install` command reads [`pnpm-workspace.yaml`](https://github.com/oblien/openship/blob/main/pnpm-workspace.yaml) and creates a single [`pnpm-lock.yaml`](https://github.com/oblien/openship/blob/main/pnpm-lock.yaml) file while maintaining isolated `node_modules` for each package.

### 2. Configure Environment Variables

Copy the example environment file and customize it with your credentials:

```bash
cp .env.example .env

```

The `.env.example` file contains placeholders for database URLs, cloud provider API keys, and service ports. Fill in any required credentials for the cloud adapters you plan to develop against.

### 3. Start the Docker Infrastructure

Launch the backing services defined in [`docker/docker-compose.yml`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml):

```bash
docker compose -f docker/docker-compose.yml up -d

```

This command starts:
- **PostgreSQL** – Primary database for the Prisma schema
- **Redis** – Caching layer for the API
- **API prerequisites** – Network configurations shared with the Fastify server

### 4. Initialize the Database

Run Prisma migrations to set up the database schema:

```bash
pnpm --filter @openship/db migrate dev

```

## Running Development Services

The monorepo uses `pnpm --filter` commands to target specific packages. Each service runs independently, allowing you to develop specific components without starting the entire stack.

### Web UI (Vite Development Server)

Start the React frontend with hot-module replacement:

```bash
pnpm --filter @openship/web dev

```

The Vite dev server binds to `http://localhost:3000`. The entry point at [`apps/web/src/main.tsx`](https://github.com/oblien/openship/blob/main/apps/web/src/main.tsx) bootstraps the React application:

```typescript
// apps/web/src/main.tsx
import { createRoot } from 'react-dom/client';
import { App } from './App';

const container = document.getElementById('root')!;
createRoot(container).render(<App />);

```

To configure API communication, the web app uses environment variables pointing to the local Fastify server:

```typescript
// apps/web/src/lib/api.ts
import axios from 'axios';

export const client = axios.create({
  baseURL: import.meta.env.VITE_API_URL ?? 'http://localhost:4000',
  timeout: 10_000,
});

export async function fetchProjects() {
  const { data } = await client.get('/projects');
  return data;
}

```

### API Server (Fastify)

Start the backend service with:

```bash
pnpm --filter @openship/api dev

```

The Fastify server entry point at [`apps/api/src/server.ts`](https://github.com/oblien/openship/blob/main/apps/api/src/server.ts) initializes the HTTP listener on port 4000:

```typescript
// apps/api/src/server.ts
import Fastify from 'fastify';
import { registerRoutes } from './routes';

export const server = Fastify({ logger: true });

registerRoutes(server);

server.listen({ port: 4000, host: '0.0.0.0' });

```

### Desktop Application (Electron)

Run the Electron client using:

```bash
pnpm --filter @openship/desktop dev

```

The desktop app imports the same React components as the web UI but wraps them in a native Electron shell defined in [`apps/desktop/src/main.ts`](https://github.com/oblien/openship/blob/main/apps/desktop/src/main.ts).

## Testing and Code Quality

The repository uses **Vitest** for unit testing and **ESLint** with **Prettier** for code quality.

Run all tests across the workspace:

```bash
pnpm test

```

Target a specific package:

```bash
pnpm --filter @openship/db test

```

Lint and format the codebase:

```bash
pnpm lint
pnpm format

```

## Extending the Platform: Adding Custom Adapters

To add a new cloud provider adapter, create a package within `packages/adapters/src/providers/`:

```bash

# Create a new provider directory

mkdir packages/adapters/src/providers/mock

```

Implement the `CloudAdapter` interface:

```typescript
// packages/adapters/src/providers/mock/index.ts
import { CloudAdapter } from '../../types';

export class MockAdapter implements CloudAdapter {
  async listBuckets() {
    return [{ name: 'demo-bucket', region: 'us-east-1' }];
  }
}

```

## Building for Production

Create production bundles for deployment:

```bash

# Static web bundle

pnpm --filter @openship/web build

# API compilation

pnpm --filter @openship/api build

# Desktop binaries

pnpm --filter @openship/desktop build

```

## Summary

- **Clone** the oblien/openship repository and ensure Node.js 20+ and pnpm are installed.
- **Copy** `.env.example` to `.env` and configure your cloud provider credentials and database URLs.
- **Start** the Docker Compose stack from [`docker/docker-compose.yml`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml) to run PostgreSQL and Redis.
- **Install** dependencies with `pnpm install`, which respects the [`pnpm-workspace.yaml`](https://github.com/oblien/openship/blob/main/pnpm-workspace.yaml) configuration.
- **Launch** individual services using `pnpm --filter @openship/web dev`, `pnpm --filter @openship/api dev`, or `pnpm --filter @openship/desktop dev`.
- **Test** changes using `pnpm test` and validate code quality with `pnpm lint`.

## Frequently Asked Questions

### What Node.js version is required for oblien/openship?

The repository requires **Node.js 20 or higher**, as specified in the `.nvmrc` file at the repository root. Using a version manager like `nvm` ensures compatibility with the TypeScript build tools and pnpm workspaces.

### Can I use npm or yarn instead of pnpm?

No. The oblien/openship monorepo relies on **pnpm workspaces** defined in [`pnpm-workspace.yaml`](https://github.com/oblien/openship/blob/main/pnpm-workspace.yaml) for dependency hoisting and isolated package management. The workspace scripts in the root [`package.json`](https://github.com/oblien/openship/blob/main/package.json) assume pnpm-specific commands and filtering syntax.

### Is Docker mandatory for local development?

Yes. The **Fastify API** depends on PostgreSQL and Redis instances defined in [`docker/docker-compose.yml`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml). While you can run the web UI (`@openship/web`) independently using mock data, full integration development requires the Docker stack to handle database migrations and API requests.

### How do I add environment variables for new cloud providers?

Add your provider-specific keys to the `.env` file you created from `.env.example`. The `packages/adapters` modules read these variables during initialization. Refer to [`docs/installation.md`](https://github.com/oblien/openship/blob/main/docs/installation.md) for provider-specific configuration requirements and ensure you restart the API server after modifying environment variables.